Custom Plug-In structure

This topic describes how to use plug-in components.

A plug-in must contain the following components:
  • index.html: Contains the plug-in html code.
  • main.js: Contains the plug-in javascript code.
  • manifest.json: Contains the plug-in configuration details.
  • style.css: Contains the plug-in stylesheet details.
  • The scripts folder: Contains external scripts.

Get started with the sample templates to build your own plug-in.

Template Type How to Use
Download the sample template for simple plug-in

Includes examples using data source.

 Use this template to build a simple plug-in.
  1. Unzip the downloaded file. The unzipped file contains a folder called template with components to build a simple plug-in.
  2. Modify the plug-in components.
  3. Rename the template folder to match with the typeName (plug-in name) in manifest.json.
  4. Create a zip file of your modified folder (do not zip only plug-in components). The zip filename should also be the plug-in name.

    For example, if your plug-in name is table, then the zip file and the folder within should also be named as table.

  5. Import the modified zip file to Operations Hub to load as a plug-in.
Download the sample template for advanced plug-in
  • Includes examples using data source and data target.
  • Loads external scripts (tools.zip) imported using webpack.
  • Loads DevExtreme using manifest (scripts element).
  • tools.js contains color conversion script and connecting to datasources for manual, global, query, or formula.
 Use this template to build an advanced plug-in.
  1. Unzip the downloaded file.
  2. Perform npm install in the root folder to download dependencies.
  3. Modify the plug-in components.
  4. To generate a zip file of the modified template:
    • Perform npm run build to generate a development package.
    • Perform npm run buildProd to generate a production package (minified).
  5. The generated zip file is saved to the dist folder in the project folder.

  6. Import the zip file to Operations Hub to load as a plug-in.

The index.html file

Each plug-in must contain an index.html file in the root folder of the plug-in.
Note: If html code is not required, create a blank file.
The markup defined in the index.html file is included in the body of a page in an application. Therefore, tags such as html, head, meta will be omitted.
Important: Do not use the script tag because of the asynchronous behavior of the tag outside of the html head.

JavaScript Dependencies

The easiest way to add external javascript dependencies is to place them in the scripts folder (in the root folder) and reference this dependency in the manifest.json file.

Important: When using this method, all javascript dependencies are included in the global scope of the application, which can create conflicts between different plug-ins. Therefore, we recommend that you use a build tool like Webpack to manage dependencies of plug-ins.

The manifest.json file

Every plug-in must contain a manifest.json file in the root folder of the plug-in. This file provides the essential information about the plug-in to Operations Hub.

The following table provides the parameters that you must include in the manifest.json file.
ParameterDescription
typeName [String]The unique name of the plug-in.
pluginId [String]The unique ID of the plug-in. The value for this parameter must be a long, random one.
Type [String]The type of the plug-in.
category [String]The category of the plug-in.
description [String]The description of the plug-in. This value appears in Operations Hub when you design an application to include the plug-in.
infoThe following information about the plug-in:
  • version
  • update
  • size
  • developer
scripts [Array]The array for the scripts that you want to use in the plug-in.
customIcon [String]The icon that will appear next to the name of the plug-in in Operations Hub when designing an application to include the plug-in.
origin [String]The origin of the plug-in. Provide the value custom for this parameter.
placeholder [String]A placeholder for the plug-in, which will appear in Operations Hub when designing an application to include the plug-in.
preview [String]The picture preview of the plug-in that will appear in Operations Hub when designing an application to include the plug-in.
fieldsDescription [Object]The plug-in description for informational messages.
isNotAllowToAddFields [Boolean]Indicates whether to allow the user to add more data fields when designing an application to include the plug-in. If you do not want the user to add data fields, enter true.
schema{}An array of the following types of schema:
  • JSONSchema{}
  • UISchema{}

Schema

The schema is based on JSON. It is used in the manifest.json file to specify the plug-in input and output.
  • Input: The input for a plug-in can be static or dynamic. Static data is available in any of the following JSON schema types:
    • string
    • number
    • integer
    • boolean
    • null
    • object
    • array
    The dynamic data is available in an Operations Hub component such as a query, global variable, or manual entry of data.
  • Output: The output of a plug-in is defined in the Operations Hub target, such as a query with inputs or a global variable.
The schema defined in the manifest.json is presented in Operations Hub in the html format. This format is implemented using the react-jsonschema-form library, which introduces the concept of UI schema to provide the information about the form behavior and to give an extensive API for the form customization. Customization is typically done using custom fields and widgets that become part of the default form registry. The library renders all form fields leveraging the Bootstrap semantics, so that it can be styled with bootstrap themes or custom CSS.
Tip: The following websites provide information on creating plug-ins:

Supported Widgets

The following table provides the supported widgets for each field type.
Field TypeSupported Widgets
Boolean
  • Check box
  • Radio button
  • Select
String
  • Text
  • Password
  • Email
  • URI
  • Radio button
  • Select
  • Text area
  • Datetime
  • Color
Number
  • Text
  • Select
  • Range
  • Radio button

The main.js file

The plug-in API is exposed through the global object EMBED. You can access this object when the plug-in source code is included in Operations Hub. The following table provides the methods used in EMBED.
MethodDescription
EMBED.getRootElement()Returns the jqLite element, which must be used as the mounting point of the root element of the plug-in.
EMBED.onChangeData(callback)This method is a general data change listener. callback - function, which is invoked with one argument every time when data change event is triggered.
EMBED.getData()Returns existing page data.
The following table provides the four main methods to work with the Data Source and Data Target fields.
MethodDescription
EMBED.subscribeFieldToQueryChange(field, callback)Field object: Data Source

Callback: Function that is invoked when query change event received. Callback is invoked with one argument, which is a data selection as per field configuration.

EMBED.subscribeFieldToGlobalChange(field, callback)Field object: Data Source

Callback: Function that is invoked when global change event received. Callback is invoked with one argument, which is a global data as per field configuration.

EMBED.subscribeFieldToDataChange(field, callback)Field object: Data Source

Callback: Function that is invoked when global or query change event received.

EMBED.submitTarget(field, value)Field object: Data Target

Value: javascript primitives or Object/Array

This method targets the input of a query or a global variable, as per field configuration.