Connecting Dashboard Plugin in the Web Application

On working with plugins in the desktop application, units written in the Fore language are used. To work in the web application, a plugin must be written on JavaScript.

Plugins are registered in general repository parameters and refer to the Fore unit for working in the desktop application and to the script for working in the web application.

To connect the plugin:

Register the plugin in common resources. Plugin registration is executed in the development environment in the Fore or Fore.NET language using the ISharedPluginsContainer.Plugins property.

On registration:

Plugin identifier is set in upper case using the INamedEntity.Id property.

NOTE. Plugin identifier must match with the identifier in the plugin JS script structure.

A URL to *.js file is set as a relative path using the ISharedAdhocPlugin.WebUrl property.

An example of plugin registration in the development environment is contains in description of the ISharedPluginsContainer.Plugins property.

Set up a web application dashboard. To display the plugin registered in services, set the ServicesPlugins property using one of the methods:

For the entire web application in the PP.xml file. Add the <modules> tag inside the <pp> tag, in which set the property:

<?xml version="1.0" encoding="utf-8" ?>
<pp>
  <service url=" http://localhost:9090/axis2/services/PP.SOM.Som" />
  <metabase id="REPOSITORY" ping="120000" />
  <cultures>
    <culture cultureName="en" />
    <culture cultureName="ru" />
  </cultures>
  <modules>
   <dashboard>
    <reportBox ServicesPlugins="true"/>
   </dashboard>
  </modules>
</pp>

On creating an instance of the KapBox component, for example:

kapBox = new Kap.KapBox({
    Metabase: metabase,
    ParentNode: "DashboardBox",
    Key: ppKey,
    Mode: ppMode,
    ServicesPlugins: true
});

Restart the web server used by the web application.

After executing the operations the plugin is connected in the web application.

To connect the plugin:

Add plugin description in the PP.xml file. Add the <plugins> tag with description inside the <pp> tag, for example:

<?xml version="1.0" encoding="utf-8" ?>
<pp>
  <service url=" http://localhost:9090/axis2/services/PP.SOM.Som" />
  <metabase id="REPOSITORY" ping="120000" />
  <cultures>
    <culture cultureName="en" />
    <culture cultureName="ru" />
  </cultures>
  <plugins>
    <plugin type="PP.Ui.MyLabel" path="../plugins/SourceLabel.js" loaded="true" name="SourceLabel"/>
  </plugins>
</pp>

Restart the web server used by the web application.

After executing the operations the plugin is connected in the web application.

To manually connect the plugin:

Make sure that the *.js file of the plugin does not contain registration block.
Open a dashboard in the web application.
Execute the Kap.regPluginBlock method in the browser console:

Kap.regPluginBlock({
    Id: "SOURCELABEL", //id, by which plugin block is linked with its implementation
    Name: "Sourcelabel", //block type name
    View: "PP.Ui.MyLabel", //visualizer class or visualizer class name
    Master: "PP.Ui.MyMaster", //master class or master class name
    Icon: "../build/img/app/MainIcon.png", //path to icon (16*16) for plugin, optional parameter
    SourceClass: 2561, //data source class code; if it is not set, dashboard designer does not provide data source for plugin
    Js: "http://test/fp_App_v9.2/plugins/SourceLabel.js " //for dynamic script loading with plugin implementation

});

After executing the operations the plugin is manually connected in the web application.

IMPORTANT. When the plugin is registered manually, all changes in dashboard settings are active before browser page refresh.

NOTE. If the Kap.regPluginBlock registration method is used, the plugin is connected during method call, otherwise it is connected on system login.

Plugins are displayed in the drop-down menu of the

Plugins button on the dashboard ribbon.

Plugin JS Script Structure

// Set self-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 icon (16*16) for plugin, optional parameter
      SourceClass: PP.Mb.MetabaseObjectClass.KE_CLASS_EXPRESSREPORT, // type or code of data source class
      Js: "../plugins/MyLabel.js",  //for dynamic script loading with plugin implementation, optional parameter
      Master: "PP.Ui.MyMaster",  //master class or master class name
      Props: {  // additional plugin parameters for setting default values, optional parameter
        pluginProps: {}
      }
    });
  }
})();
 
if (!PP.Ui.MyLabel)
{
  PP.Ui.MyLabel = {};
  PP.initNamespace(PP.Ui.MyLabel, "PP.Ui.MyLabel");
}
 
// Create a prototype of custom visualizer 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 must work with data source,
// set data source for visualizer, which is opened in dashboard
PP.Ui.MyLabel.prototype.setSource = function(source) {
  this._Source = source;
  this.setContent("Source loaded: " + this._Source.getId());
  this._refreshedFire();
};
 
// If plugin must support stored properties, set the setProps and getProps methods 
PP.Ui.MyLabel.prototype.setProps = function(value) {  // method for setting stored block 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 providing properties to store 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 data block refresh
};
 
PP.Ui.MyLabel.prototype.setWidth = function () {
  if (this._Instance)   this._redraw();
};
 
PP.Ui.MyLabel.prototype.setHeight = function () {
  if (this._Instance)   this._redraw();
};
 
// If plugin must have 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 must display additional side panel tabs with plugin settings,
// set implementation of the setDataView(view) method, where view - 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();
};