Act Plugin Development

Welcome to the Act! Developer Documentation for plugin development. This site will walk you through getting yourself setup for creating an Act! plugin.

Requirements

CLI

You can run the CLI using the npx command.

First, login to the Act! NPM registry:

npm set registry http://npm.actops.com
npm login

Use the username and password given to you when you signed up.

Then, from the terminal, go to the directory you wish to hold your project and run the following command:

npx @act/plugins plugin init

This function will generate your project structure for you with initial code and configuration. The script will ask whether your project uses Actions. This is a type of extension provided to plugin developers and requires another JavaScript file to be used for global actions called by the Act! application. Choosing yes will result in a new property in your manifest and an actions.js file being created with some initial code to contain your global functions. You will still need to define the action extension within the plugin-manifest.json file. Use the extensions docs to see the model for that.

This should place you through all of the Getting Started. Check out the API section for consuming this library.

Sample

Check out the sample plugin built to demonstrate a Google Maps integration for the Contact entity. To see the full plugin in action, acquire an API key from Google for their Google Maps API. Insert the key into the code at the corresponding TODO section, then build and run the project.

Getting Started

Create your JavaScript project using your favorite Framework or vanilla JS!

If your project does not have a package.json, run

npm init

to initialize your package.json for your project.

Add the latest @act/plugins package to your package.json.

Create a plugin-manifest.json.

Copy the following into the plugin-manifest.json file and fill with values for your plugin:

{
  "actions": "http://localhost:8000/actions.js",
  "company": "Your Company",
  "description": "DESCRIPTION",
  "extensions": [{
    "type": "view",
    "payload": {
      "src": "http://localhost:8000/index.html",
      "name": "plugin-docs",
      "label": "PLUGIN_DOCS",
      "icon": "note"
    }
  }],
  "name": "Your Plugin Name",
  "permissions": {
    "dialog": "false"
  },
  "pluginImageSrc": "",
  "settings": {},
  "supportEmail": "",
  "translations": {
    "de": {
      "DESCRIPTION": "Description of your plugin"
    },
    "en-GB": {
      "DESCRIPTION": "Description of your plugin"
    },
    "en-US": {
      "DESCRIPTION": "Description of your plugin"
    },
    "fr": {
      "DESCRIPTION": "Description of your plugin"
    }
  },
  "version": {
    "major": 0,
    "minor": 0,
    "patch": 0
  }
}

Please note, you do not need an actions property if you do not use global actions. See the Actions section below if this functionality is desired.

There are multiple ways to create extension points for Act!:

Here are the following models for each extension type. Add the object to the extensions array in your plugin-manifest.json.

Tab

{
  "entity": "contact",
  "payload": {
    "src": "http://localhost:8000/tab.html",
    "name": "test",
    "label": "TEST"
  },
  "type": "tab"
}

Contextual Action

{
  "entity": "contact",
  "payload": [{
    "color": "purple",
    "disabled": "isDirectionsDisabled",
    "functionName": "onMapsClick",
    "icon": "map",
    "label": "DIRECTIONS",
    "name": "directions",
    "position": {
      "name": "call",
      "type": "after"
    }
  }],
  "type": "actions"
}

For a full screen view, add the object to the extensions array on your plugin-manifest.json

View

{
  "type": "view",
  "payload": {
    "src": "http://localhost:8000/index.html",
    "name": "your-plugin",
    "label": "TEST",
    "icon": "groups"
  }
}

The label property should map to the translations property per locale. Please note that locales are restricted to the available locales within the Act! product.

The icon property should exist within Act! icons or point to a URL for the icon you desire rendered (TODO: Add this functionality).

The color property should map to one of the colors in the color palette for Act!.

Overview