Aha! Develop | View extension contributions

View extension contributions run in the context of the browser using the permissions of the current user who is viewing the contribution.

Click any of the following links to skip ahead:

• Definition

• Current view extension contributions

• package.json example

• package.json schema

• API

• Add the view to the user interface

Definition

View extension contributions allow an extension developer to add visible content to the Aha! Develop user interface by generating HTML that is inserted in specific places in the UI.

There are three different places, called the host, that a view might appear:

1. As an attribute on a record.

2. As a tab on a record. This allows per-record information to be displayed with more space.

3. As a page in the Aha! Develop UI. A page is not associated with a specific record and can take advantage of most of the screen. Page views are suitable for use cases like reports where data from multiple records is displayed at once.

Top

Current view extension contributions

We have created view extensions with the following tools. You can always create your own view extension to a tool not listed here:

Top

package.json example

An extension that has a view to show a list of GitHub links as an attribute on features, epics, and requirements would specify it in the package.json like this:

{
  "ahaExtension": {
    "contributes": {
      "views": {
        "links": {
          "title": "GitHub",
          "host": "attribute",
          "entryPoint": "src/links.js",
          "recordTypes": [
            "Feature",
            "Epic",
            "Requirement"
          ]
        },
      }
    }
  }
}

An extension that has a full-page overview of GitHub pull request statuses would specify it like this:

{
  "ahaExtension": {
    "contributes": {
      "views": {
        "prs": {
          "title": "GitHub Pull Requests",
          "host": "page",
          "entryPoint": "src/prs.js",
          "location": {
            "menu": "Work"
          }
        }
      }
    }
  }
}

Top

package.json schema

Top

API

aha.on("viewName", ({ record, fields, onUnmounted }, { identifier, settings }) => {
  onUnmounted(() => {
    console.log("Un-mounting component for", record.identifier);
  });

  return <MyViewReactComponent record={record} />;
});

The handler takes two parameters:

• The name of the handler.

• A render function that will be invoked when the view should be rendered.

The render function is passed an object that contains a number of values that may be useful during rendering:

• record is the data for the record to be rendered for attribute and tab contributions.

• fields contains extension fields that were previously stored for the record as a JSON object.

• onUnmounted takes a function that will be called when the view will no longer appear in the user interface. It can be used to unregister event handlers or perform any other action that is necessary to clean up. For React components, it is not necessary to unmount the component — it will be handled automatically.

The context object contains information about the extension:

• settings contains the settings for the extension as a JSON object.

• identifier is set to the string identifier of the extension.

The render function should return the HTML that will be displayed for the record. The return value can be one of three types:

• A plain text string will be used as-is. HTML elements in the string will be escaped.

• A single DOM node or an array of DOM nodes.

• A React component. JSX can be used with React components and will automatically be processed as the extension is installed.

Top

Add the view to the user interface

View contributions that are hosted in a page will automatically appear in the navigation menu when the extension is installed.

Contributions that are hosted as an attribute or a tab need to be manually added into a custom layout. The easiest way to do this is:

1. Navigate to a record — a feature, epic or requirement — where you want the view to appear.

2. Click the More options button, then Edit custom layout.

3. On the left side choose Extension fields.

4. Drag your new extension field onto the Overview tab.

View extensions are disabled whenever you export an Aha! Develop record (to PDF, PNG, etc.). For that reason, view extension data will not be included in any export.

Top