Develop BPC plugins

This page describes BPC plugins.

Definition

A plugin is an (ExtJS) component that is designed to be integrated at various predefined locations (hooks).

The assignment of the plugin to the usage location is the task of the BPC and cannot be influenced by the plugin. The display of the plugin at the usage location (hook) depends on the hook. This is a sub-class of Ext.Container and can determine its own "layout".

Lifecycle

If a module or module component containing a plugin hook is created in the BPC, the plugin configuration of this module (plugin_configuration) is retrieved at this point. All plugins configured there are then created via the createPlugin function on the PluginInterface (initially as an ExtJS configuration; the actual creation then takes place implicitly in the hook container). An object with information about the hook, the module context and optional plugin configuration is transferred to the plugin via the pluginConfiguration attribute. The plugin components exist until they are explicitly removed from the hook or the hook itself is removed.

Beispiel Interface:

Ext.define("demo.PluginInterface", {
	extend : "BpcCommon.plugin.Interface",

	inheritableStatics : {
		NAME                  : "Demo Plugin",
		COMPONENT_XTYPE       : "demoPluginComponent",
		PLUGIN_ID             : "demo_plugin",
		DEFAULT_CONFIGURATION : {
			pluginMessage : "Messgage from the demo plugin"
		}
	}
});

The plugin interface derives(extends) from the BpcCommon.plugin.Interface class. This means that it is recognized as a plugin by the BPC.

The following attributes should be set:

NAME: The name that is offered to the user in the interface.
COMPONENT_XTYPE : Reference to the alias of the ExtJS component to be rendered.
PLUGIN_ID: Unique ID for the plugin
DEFAULT_CONFIGURATION (optional): Standard configuration object that can be viewed and edited in the interface.

Beispiel Plugin Klasse

Ext.define("demo.Plugin", {
	extend : "Ext.Component",
	alias  : "widget.demoPluginComponent",
	html   : "Default Message",

	initComponent : function () {
		this.callParent();
		/*
		 Prüfung, ob eine Plugin konfiguration gesetzt wurde und diese eine pluginMessage enthält
		* Trifft dies zu, wird die pluginMessage als HTML dargestellt
		* Ist die s nicht der Fall wird das default HTML("Default Message") aus der Klasse dargestellt
		*   */
		if (Ext.isDefined(this.pluginConfiguration) && Ext.isDefined(this.pluginConfiguration.configuration.pluginMessage)) {
			const htmlString = `<p>${  this.pluginConfiguration.configuration.pluginMessage} </p> `;
			this.setHtml(htmlString);
		}

		// Kontext-Informationen sind unter this.pluginConfiguration.context vorhanden
		// z.B. pluginConfiguration.context.demoCounter

		// listener für refresh events vom Hook
		this.pluginConfiguration.context.hook.on("refresh",this.onContextRefresh,this);
	},

	onContextRefresh: function (hook, newContextObj){
		// hier können die neuen Kontext-Informationen behandelt werden
		// console.log(newContextObj.demoCounter);
	}

});

The attribute alias is made up of "widget." and the COMPONENT_XTYPE referenced from the PluginInterface. In this case, "widget.demoPluginComponent". The plugin configuration can be accessed in the initComponent method under the this.pluginConfiguration.configuration attribute. Initially, this corresponds to DEFAULT_CONFIGURATION from the plugin interface. However, this can be edited in the interface (see Plugin configuration). Plugins created in this way are automatically recognized by the BPC and can be assigned to plugin-enabled modules (these require at least one hook) via the configuration.

Provide hook

In order for a module to "receive" plugins, it must provide at least one hook. These must extend the HookContainer class and can be used anywhere in the module, like normal ExtJS containers. However, there should be a separate hook for each "location", as otherwise the assignment of the plugins is problematic. The hooks are then available on the module for the plugin assignment.

Further information or data can be passed on to the plugins via the context attribute.

Beispiel Hook:

Ext.define("demo.PluginHook", {
	extend : "BpcCommon.plugin.HookContainer",
	alias  : "widget.demoPluginHook",

	layout : {
		type  : "hbox",
		align : "stretch"
	},


	inheritableStatics : {
		NAME    : "Demo Hook",
		HOOK_ID : "demo_hook",
		MODULE  : "demo"
	},

	context : {
		moduleId : "demo",
		demoCounter: 1
	},

	incrementCounter: function (){
		const me = this;

		me.context.demoCounter++;

		// Die refresh Funktion ist in BpcCommon.plugin.HookContainer implementiert und erzeugt einen "refresh" Event
		me.refresh({
			demoCounter: me.context.demoCounter
		});

		// alternativ auch folgendes möglich
		// me.refresh(me.context);
	}

});

If something changes in the context information, plugins can be informed by calling the function refresh() with the new context information as parameters on the hook component. This is possible in the Hook example example.

In order for plugins to receive the information from the hook, they must store an event listener for the refresh event on the hook. This is implemented in the Example plugin class as an example.

Keywords: