Developing BPC Plugins

This page describes BPC plugins.

Definition

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

The assignment of a plugin to its point of use is the responsibility of the BPC and cannot be influenced by the plugin itself. The plugin’s appearance at the point of use (hook) depends on the hook. The plugin is a subclass of Ext.Container and can determine its own “layout.”

Lifecycle

When a module or module component containing a plugin hook is created in the BPC, the plugin configuration for that module (plugin_configuration) is retrieved at that point. All plugins configured there are then created via the createPlugin function on the PluginInterface (initially as an ExtJS configuration; the actual creation then occurs implicitly in the hook container). In the process, an object containing information about the hook, the module context, and optional plugin configuration is passed to the plugin via the pluginConfiguration attribute. The plugin components persist 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"
		}
	}
});

Das Plugin Interface leitet(extend) von der Klasse BpcCommon.plugin.Interface ab. Dadurch wird dieses vom BPC als Plugin erkannt.

Folgende Attribute sollten gesetzt werden:

NAME: Der Name, der dem Benutzer in der Oberfläche angeboten wird.
COMPONENT_XTYPE : Referenz auf den alias der ExtJS Komponente, die gerendert werden soll.
PLUGIN_ID : Eineindeutige ID für das Plugin
DEFAULT_CONFIGURATION (optional): Standard Konfigurationsobjekt, die in der Oberfläche eingesehen und bearbeitet werden kann.

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);
	}

});

Das Attribut alias setzt sich aus "widget." und dem aus dem PluginInterface referenzierten COMPONENT_XTYPE zusammen. In diesem Fall "widget.demoPluginComponent". In der initComponent methode kann unter dem Attribut this.pluginConfiguration.configuration auf die Konfiguration des Plugins zugegriffen werden. Initial entspricht diese der DEFAULT_CONFIGURATION aus de, Plugin Interface. Diese kann jedoch in der Oberfläche bearbeitet werden (siehe Plugin konfiguration). So erstellte Plugins werden vom BPC automatisch erkannt und können Plugin-Fähigen Modulen (diese benötigen mindestens ein Hook) über die Konfiguration zugeordnet werden.

Hook bereitstellen

Damit ein Modul Plugins "empfangen" kann, muss dieses mindestens ein Hook bereitstellen. Diese müssen die HookContainer-Klasse erweitern und können an beliebigen Stellen im Modul, wie normale ExtJS Container eingesetzt werden. Dabei sollte es jedoch für jede "Stelle" ein eigenen Hook geben, da sonst die Zuordnung der Plugins problematisch ist. Die Hooks stehen dann am Modul für die Plugin-Zuweisung zur Verfügung.

Über das context Attribut können weitere Informationen oder Daten an die Plugins weitergereicht werden.

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 the context information changes, plugins can be notified by calling the function ` refresh() ` on the hook component with the new context information as a Parameter. This is implemented as an example in the example hook.

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

Keywords: