Act! Extension Points

Now that we understand the manifest and its properties, let's dive into the definitions that link your plugin to the Act! application. These definitions are called extension points. There are three extension points for Act! plugins:

Section
View
Actions

Let's dive into what these extension points mean.

Section

A contextual extension point means the plugin has functionality that is based off of the currently viewed entity. Act! allows for extensions off of the main entities (Contacts, Companies, Groups, and Opportunities). This type of extension will appear as a new tab within the detail view for the desired entity.

When utilizing this type of extension point, you will want to get the current context via the @act/plugins library. The context object is similar to a RxJS Observable and allows you to call .subscribe in order to listen to the context. If the context changes via user events (ex. the entity is edited), then the function passed to the .subscribe method will be called again. This allows you to maintain the current value of the context at all times within your application.

A contextual definition requires the following properties:

{
  "entity": "contact",
  "payload": {
    "src": "http://localhost:8000/tab.html",
    "disabled": "tabDisabledFunction",
    "hidden": "tabHiddenFunction",
    "name": "directions",
    "label": "DIRECTIONS",
    "position": {
      "name": "opportunities",
      "type": "after"
    }
  },
  "type": "tab"
}

The currently supported type for contextual definitions is tab. This definition will create a new tab on the contact detail view with the string value set in the translations for DIRECTIONS. Your application will render in an iframe within the detail view for the contact when the tab is selected. Be sure to grab the context using the @act/plugins library to show any necessary data.

View

View extensions are linked to the Act! application through the navigation menu and will display as a full view within the application. As such, a view extension is one in which your plugin is responsible for requesting data and managing its own state.

A view definition has the following structure:

{
  "type": "view",
  "payload": {
    "src": "http://localhost:8000/index.html",
    "name": "testing",
    "label": "TEST",
    "position": {
      "name": "contacts",
      "type": "after"
    },
    "icon": "contacts"
  }
}

This will create a route with the name of testing and place a navigation menu item with the provided icon and translation matching the passed label value.

A view extension should not try to access the context$ property as this will not be valid. The Act! application updates that entity based on user navigation within the application to the detail views of the entities that are available for extension.

Actions

The simplest of the plugin extension points is the action. Actions are specific to certain views. Currently Act! allows developers to add actions to the detail views for the main entities (Contacts, Companies, Groups, and Opportunities).

Detail view actions appear as icon buttons and as such the properties to create that extension are based on the properties of the icon button from Act! Web Components. Here is an example of what an action will look like when rendered within Act!

An action definition has the following structure:

{
  "entity": "contact",
  "payload": [{
    "disabled": "disabledFunction",
    "functionName": "onClick",
    "functionParams": [],
    "label": "DIRECTIONS",
    "staticLabel": null,
    "name": "directions",
    "position": {
      "name": "call",
      "type": "after"
    }
  }],
  "type": "actions"
}

Let's walk through each property separately:

entity: This value represents the detail view for the entity that the action will show for. The available values are contact, company, opportunity, and group.
payload: This is a dynamic value based on the provided type. In this case, for actions it is required to include the name and functionName. The functionName should map to a global function available in your actions JS file defined in the manifest. You can declare the position of your action through the position property. Utilize the unique name attribute on the action element to determine the reference point, then define whether the position should be before or after via the type property.

The functionName and disabled properties are names of functions within your provided actions file. This file will be automatically generated for you by the CLI if you used that method, else you should create your own. Act! sets the variable actPlugin with type ActPlugin as a global to that file. From it you can access the available functionality in the API section.

functionParams lets you pass data from your dynamically registered action to the action.js function. They will be passed as the first set of elements to the function (while the entity data will be the final parameter). This should be an array of value(s).

staticLabel allows you to override the label used with a static value. This will not be translated and therefore should take the shape of a normal string. This should only be used when dynamically adding actions as you should provide translations for any text used. Please make sure you have a method of translating this string available to ensure that your plugin will be accessible to other locales (at minimum the locales supported by Act!).

type: The defined type for the extension. In this case actions.

API Fundamentals

Now that we understand the extension points for Act! plugins, let's examine the details of the ActPlugin class exposed by the @act/plugins package.

Settings