Inserting and Setting Up Plugins

In this article:

Connecting Plugin in the Desktop Application

Connecting Plugin in the Web Application

Plugin JS Script Structure

Plugins are modules connected to a dashboard to enhance its functionality. The desktop application allows for creating plugins as units written in the Fore programming language. The web application uses the JavaScript language for creating plugins.

To insert a plugin:

  1. Connect a plugin to a dashboard in the desktop application and/or in the web application.

  2. Execute one of the operations in the dashboard:

After executing the operations the plugin will be inserted to the dashboard as a single object. All operations with objects described in the Building Dashboard section are available for plugins. If the plugin supports work with data sources, it is also possible to select a data source for it.

Select data source

The following plugin can be connected in the web application:

Connecting Plugin in the Desktop Application

To connect a plugin to a dashboard in the desktop application:

  1. Create a visualizer form. This form contains components that form plugin appearance, and a code that describes logic of component work in the plugin. The visualizer form must be inherited from the AdhocUserViewForm class. Features of visualizer form code:

  2. Create a master form. This form contains components that form side panel tabs that are used to set up the plugin, and a code that describes logic of applying settings to the plugin. The master form must be inherited from the AdhocUserMasterForm class.

  1. Register the plugin in services. A plugin can be registered in the development environment in the Fore or Fore.NET programming language using the ISharedPluginsContainer.Plugins property.

Add links to the Metabase, Fore (KeFore for Fore.NET) system assemblies and execute the unit:

Sub UserProc;
Var
    mb: IMetabase;
    plugins: ISharedPlugins;
    cont: ISharedPluginsContainer;
    adhoc_plugs: ISharedAdhocPlugins;
    plugin: ISharedAdhocPlugin;

Begin
    
// Get object to work with the current repository
    mb := MetabaseClass.Active;
    
// Get object to work with plugin container
    cont := mb.SpecialObject(MetabaseSpecialObject.SharedParams).Edit As ISharedPluginsContainer;
    
// Get object to work with plugins
    plugins := cont.Plugins;
    
// Get collection of plugins of the Dashboards tool
    adhoc_plugs := plugins.AdhocPlugins;
    
// Create a new plugin
    plugin := plugins.AdhocPlugins.Add;
    
// Set plugin identifier and name
    plugin.Id := 
"ID"// Specify unique plugin identifier in upper case instead of "ID", which matches identifier in plugin js script structure
    plugin.Name := "name"// Specify plugin name to be displayed in dashboard instead of "name"
    // Set visualizer form and master form
    plugin.ViewForm := mb.ItemById("ViewForm_Id"); // Specify visualizer form identifier instead of "ViewForm_Id"
    plugin.MasterForm := mb.ItemById("MasterForm_Id"); // Specify master form identifier instead of "MasterForm_Id"
    // Saved created plugin
    (cont As IMetabaseObject).Save;
End Sub UserProc;

Imports Prognoz.Platform.Interop.Metabase;
Imports Prognoz.Platform.Interop.KeFore;

Public Shared Sub Main(Params: StartParams);
Var
    mb: IMetabase;
    plugins: ISharedPlugins;
    cont: ISharedPluginsContainer;
    adhoc_plugs: ISharedAdhocPlugins;
    plugin: ISharedAdhocPlugin;

Begin
    
// Get object to work with the current repository
    mb := Params.Metabase;
    
// Get object to work with plugin container
    cont := mb.SpecialObject[MetabaseSpecialObject.msoSharedParams].Edit() As ISharedPluginsContainer;
    
// Get object to work with plugins
    plugins := cont.Plugins;
    
// Get collection of plugins of the Dashboards tool
    adhoc_plugs := plugins.AdhocPlugins;
    
// Create a new plugin
    plugin := plugins.AdhocPlugins.Add();
    
// Set plugin identifier and name
    plugin.Id := "ID"// Specify unique plugin identifier in upper case instead of "ID" that matches plugin js script  structure identifier
    plugin.Name := "name"// Specify plugin name to be displayed in dashboard instead of "name"
    // Set visualizer form and master form
    plugin.ViewForm := mb.ItemById("ViewForm_Id"); // Specify visualizer form identifier instead of "ViewForm_Id"
    plugin.MasterForm := mb.ItemById("MasterForm_Id"); // Specify master form identifier instead of "MasterForm_Id"
    // Save created plugin
    (cont As IMetabaseObject).Save();
End Sub;

After the unit is executed, the plugin will be registered in services and will be available for inserting to dashboard.

After executing the operations the plugin will be created in the object navigator as a visualizer form and a unit form, it will be registered in shared resources and will be available for inserting to dashboard in the desktop application.

Connecting Plugin in the Web Application

To connect a plugin to a dashboard in the web application:

  1. Create a *.js plugin file taking into account js script structure.

  2. Add a *.js plugin to the web application root folder, for example, C:\Program Files (x86)\Foresight\Foresight Analytics Platform 9 Web Application\plugins.

  3. Connect the plugin in one of the ways:

Connect plugin via repository

Connect plugin via the PP.xml file

After executing the operations the autonomous registration of the plugin will be executed on opening the dashboard in the web application. The plugin will be available for inserting to dashboard.

When developing a web application using DHTML components to connect a plugin via repository, use the KapBox constructor of the Kap.regPluginBlock method used as a separate method of plugin connection.

Plugin JS Script Structure

When writing a plugin and new classes follow the code writing recommendations.

Plugin js script structure:

// Set registration block
(function ()
{
  if (window.Kap)
  {
    Kap.regPluginBlock({
      Id: "MyLabel",  //id, by which plugin block is linked with its implementation
      Name: "MyLabelText",  //block type name
      View: "PP.Ui.Dashboard.MyLabel",  //visualizer class or visualizer class name
      Icon: "../build/img/app/MainIcon.png",  //path to plugin icon (16*16), optional parameter
      SourceClass: PP.Mb.MetabaseObjectClass.KE_CLASS_EXPRESSREPORT, // data source class type or code
      Js: "../plugins/MyLabel.js",  //for dynamic script loading with plugin implementation, mandatory parameter
      Master: "PP.Ui.MyMaster",  //master class or master class name
      Props: {  // additional plugin parameters to install default values, optional parameter
        pluginProps: {}
      }
    });
  }
})();
 
if (!PP.Ui.MyLabel)
{
  PP.Ui.MyLabel = {};
  PP.initNamespace(PP.Ui.MyLabel, "PP.Ui.MyLabel");
}
 
// Create a proper plugin prototype for registered block
PP.Ui.MyLabel = function(settings) {
  this._Source = null;
  this._bgFlag = false;
  this.PropertyChanged = new PP.Delegate();
  this.Refreshed = new PP.Delegate();
  PP.Ui.MyLabel.base.constructor.apply(this, arguments);
  this.setContent("MyLabelText");
};
PP.initClass(PP.Ui.MyLabel, PP.Ui.Label, "PP.Ui.MyLabel");
 
PP.Ui.MyLabel.prototype._propertyChangedFire = function () {
  this.PropertyChanged.fire(this);
};
 
PP.Ui.MyLabel.prototype._refreshedFire = function () {
  console.log("My Label Refreshed");
  this.Refreshed.fire(this);
};
 
// If plugin should support work with data source,
// set data source for the visualizer opened in dashboard
PP.Ui.MyLabel.prototype.setSource = function(source) {
  this._Source = source;
  this.setContent("Source loaded: " + this._Source.getId());
  this._refreshedFire();
};
 
// If plugin should support stored properties, set the setProps and getProps methods
PP.Ui.MyLabel.prototype.setProps = function(value) {  // method for setting block stored properties
  if (value) {
    var props = JSON.parse(value);
    this._bgFlag = props.bgFlag ? props.bgFlag : false;
  } else {
    this._bgFlag = false;
  }
  this.refresh();
};
 
PP.Ui.MyLabel.prototype.getProps = function() {  //method that provides stored properties for dashboard
  var props = {
    bgFlag: this._bgFlag
  };
  return JSON.stringify(props);
};
 
PP.Ui.MyLabel.prototype.refresh = function() {
  this._DomNode.style.backgroundColor = this._bgFlag ? "green" : "transparent";
  this._refreshedFire();
};
 
PP.Ui.MyLabel.prototype.refreshAll = function () {  // method is called on refreshing block with report
};
 
PP.Ui.MyLabel.prototype.setWidth = function () {
  if (this._Instance)   this._redraw();
};
 
PP.Ui.MyLabel.prototype.setHeight = function () {
  if (this._Instance)   this._redraw();
};
 
// If plugin should have its own context menu, set the getContextMenu method
PP.Ui.MyLabel.prototype.getContextMenu = function() {
  var _DataView = this;
  var menu = new PP.Ui.Menu({
    Items : [ {
      MenuItem : {
        Id : "pluginMenuItem",
        Content : "plugin menu item",
        Checked : _DataView._bgFlag,
        CheckedChanged : function(sender, args) {
          _DataView._bgFlag = sender.getChecked();
          _DataView.refresh();
        }
      }
    }]
  });
  return menu;
};
 
// Create a master prototype for registered block
PP.Ui.MyMaster = function(settings) {
  this._DataView;
  PP.Ui.MyMaster.base.constructor.apply(this, arguments);
  var myPanel = new PP.Ui.MasterPanel(
  {
    Id: "MyPluginMaster",
    ViewType: PP.Ui.NavigationItem,
    Content: "Plugin settings...",
    Title: "My plugin master"
  });
  myPanel.getHeaderControl().CheckedChanged.add(this._onPropsChanged, this);
  this.addMasterPanel(myPanel);
};
PP.initClass(PP.Ui.MyMaster, PP.Ui.Master, "PP.Ui.MyMaster");
 
// If plugin should display additional side panel tabs with plugin settings,
// set implementation of the setDataView(view) method where view is plugin visualizer instance.
// Additionally set the Master property in registration block
PP.Ui.MyMaster.prototype.setDataView = function(view) {
  this._DataView = view;
  for (var i = 0; i < this.getItems().length; i++) {
    var item = this.getItem(i);
    if (item.getId() === "MyPluginMaster") {
      item.setTitle("My plugin master. Data view type: " + view.getTypeName());
      if (view._bgFlag) {
        item.getHeaderControl().setChecked(view._bgFlag, false);
      }
    }
  }
};
 
PP.Ui.MyMaster.prototype._onPropsChanged = function(sender, args) {
  this._DataView._bgFlag = args.CheckedState;
  this._DataView._propertyChangedFire();
  this._DataView.refresh();
};

Below are the example of methods and functions included in plugin js script structure that can be used to solve the following tasks:

Build a plugin based on report

Get visualizer data in plugin based on report

Get dimension selection in the plugin based on express report

Set up synchronization of plugin data source dimensions with other object data sources

Execute Fore function in plugin an get execution result in browser console

See also:

Building Dashboard