BPC Widgets entwickeln

Diese Seite beschreibt die Entwicklung individueller BPC Widgets. Ein Widget stellt eine spezifische Ansicht eines Moduls dar, die im Dashboard angezeigt und konfiguriert werden kann.

Definition

Damit das BPC ein Widget erkennt, muss es in der Interface-Klasse des BPC-Moduls referenziert werden (siehe Modul Frontend Interface).

Ausschnitt der Interface-Klasse

Ext.define("template.BpcInterface", {
   extend : "BpcCommon.BpcInterface",
...
   requires : [
      "template.view.widget.TemplateWidget",
   ],
...
   config : {
...
      widgets : [
         "template.view.widget.TemplateWidget",
        ],
...
   }
});

Zusätzlich muss die Hauptklasse das folgende Attribut enthalten:

Ausschnitt aus der Widget.js-Klasse

{
    "mixins" : [
          "BpcCommon.mixin.Widget"
   ]
}

Nach dieser Konfiguration steht die Komponente dem Anwender im Dashboard zur Auswahl bereit (siehe Widget hinzufügen).

Beispiele für Widget-Implementierungen können unter Widgets im Template Module eingesehen werden.

Best Practice Tipp

Es empfiehlt sich, Widgets in getrennte Unterkomponenten aufzuteilen. Eine bewährte Struktur besteht aus vier Dateien:

Hauptklasse (Widget.js): Verwaltet die verschiedenen Ansichten und den Gesamtzustand.
Inhaltsansicht (ContentPanel.js): Stellt den Inhalt des Widgets dar.
Konfigurationsansicht (ConfigurationPanel.js): Optionen zur Widget-Einstellung.
Fehleransicht (WrongConfigurationPanel.js): Informiert den Anwender über eine unvollständige oder fehlerhafte Konfiguration.

Haupt-Widget-Klasse (Widget)

Unter dem Attribut statics befinden sich die Default-Settings des Widgets.

WIDGET_NAME:
Der Name, der dem Nutzer in der Widget-Liste angeboten wird (siehe Widget hinzufügen). Der Name dient auch als Titel des Widgets.
Es kann dem Benutzer die Möglichkeit gegeben werden, diesen nachträglich anzupassen.
WIDGET_DESCRIPTION:
Die Beschreibung, die dem Benutzer in der Widget-Liste angeboten wird (siehe Widget hinzufügen).
- WIDGET_ICON_CLS:
  Das Icon, das dem Benutzer in der Widget-Liste angeboten wird (siehe Widget hinzufügen).
- WIDGET_ADDITIONAl_ACTIONS:
  Zusätzliche Buttons im Widget Header.
  Es kann ein Array von Objekten mit den Attributen handler , iconCls und/oder text angegeben werden.

Die Methoden this.getWidgetConfiguration und this.setWidgetConfiguration sind in dem mixin definiert und ermöglichen den Zugriff auf die Widget-Settings.

Beim Speichern der Settings sollte das Event widgetConfigurationChange geworfen werden, damit dass Dashboard die Änderung mitbekommt.

Beispiel Haupt-Widget-Klasse:

Ext.define("template.view.widget.TemplateWidget", {
   extend : "Ext.panel.Panel",

   mixins : [
      "BpcCommon.mixin.Widget"
   ],
   moduleId : "templateWidget",

   statics : {
      WIDGET_NAME               : "Template Widget",
      WIDGET_DESCRIPTION        : "Template Widget Description",
      WIDGET_ICON_CLS           : "x-fal fa-bar-chart",
      /* zusätzliche Aktionen können in den Widget-Header konfiguriert werden.*/
      WIDGET_ADDITIONAl_ACTIONS : [
         {
            iconCls : BpcCommon.Icons.EDIT,
            handler : function () {
               alert("additional Action");
            },
            text :"additional Action"
         }
      ]
   },
   additionalActionScope : true,
   /*Das Layout Card bietet sich an, da mit der Methode this.getLayout.setActiveItem(cmp)
    verschiedene Ansichten eingeblendet werden können.*/
   layout    : "card",
   minHeight : 300,


   initComponent : function () {
      const me  = this;

      /*Methode aus dem Mixin, gibt die WidgetKonfiguration aus den Settings zurück */
      const widgetConfiguration =  me.getWidgetConfiguration();
      me.configuration = widgetConfiguration;

      me.callParent();

      /*Erzeugen der Konfigurations-Ansicht*/
      this.settingPanel = this.add({
         xtype               : "templateWidgetConfigurationPanel",
         widgetConfiguration : widgetConfiguration,
         listeners           : {
            saveWidgetConfiguration : me.onSaveConfiguration.bind(me),
         }
      });
      /*Erzeugen der falschen Konfigurations-Ansicht*/
      this.wrongConfigPanel = this.add({
         xtype     : "templateWidgetWrongConfigurationPanel",
         listeners : {
            showSettingPanel : me.onShowSettingPanel.bind(me),
         }
      });

      this.checkConfiguration();
   },

   onShowSettingPanel : function() {
      this.getLayout().setActiveItem(this.settingPanel);
   },

   configureWidget : function () {
      if (this.settingPanel.isVisible(true)) {
         this.getLayout().setActiveItem(this.contentPanel);
      } else {
         this.onShowSettingPanel();
      }
   },

/**
 *  Method die aus dem Widget header heraus aufgerufen werden kann.
 *  */
   refreshWidget : function () {
      console.log("refreshWidget");
   },

/**
 * Überprüfen der Widget-Settings auf ihre Gültigkeit
 * */
   checkConfiguration : function () {
      if (this.configuration.demoSetting === undefined || this.configuration.demoSetting === "") {
         this.getLayout().setActiveItem(this.wrongConfigPanel);
      } else {
         this.showContent();
      }
   },
/**
 *  Erzeugen und Anzeigen der Content View
 *  */
   showContent : function () {
      if (this.contentPanel === undefined) {
         this.remove(this.contentPanel);
      }
      this.contentPanel = this.add({
         xtype               : "templateWidgetContentPanel",
         widgetConfiguration : this.configuration,
      });
      this.getLayout().setActiveItem(this.contentPanel);
   },

/**
 * Speichern der Widget konfiguration
 * */
   onSaveConfiguration : function(newConfiguration) {
      /*methode aus dem mixin*/
      this.setWidgetConfiguration(newConfiguration);
      /*das Dashboard bekommt den Hinweis, dass sich etwas an den Settings geändert hat*/
      this.fireEvent("widgetConfigurationChange", this);
      this.checkConfiguration();
   }
});

Inhaltsansicht (ContentPanel)

Hierbei handelt es sich um Komponenten, die im HTML aus dem Setting demoSetting generiert und gerendert werden.

Beispiel ContentPanel :

Ext.define("widget.templateWidget.ContentPanel", {
   extend  : "Ext.panel.Panel",
   html    : "ContentPanel",
   alias   : "widget.templateWidgetContentPanel",
   padding : 10,


   initComponent : function() {
      this.callParent(arguments);
      this.setHtml(`<h1>${ this.widgetConfiguration.demoSetting   }</h1>`);
   }
});

Konfigurationsansicht (ConfigurationPanel)

Hierbei handelt es sich um die Komponente, die für die Widget-Settings eine UI generiert und neue Konfigurationen beim Speichern an die Widget-Hauptklasse hochreicht.

Beispiel Konfigurations-Panel:

Ext.define("widget.templateWidget.ConfigurationPanel", {
   extend  : "Ext.panel.Panel",
   alias   : "widget.templateWidgetConfigurationPanel",
   padding : "10",

   // should be set by parent
   widgetConfiguration : undefined,

   initComponent : function() {
      const me = this;
      me.dockedItems  = {
         xtype           : "toolbar",
         dock            : "bottom",
         ui              : "footer",
         overflowHandler : "scroller",

         items : [
            "->",
            {
               xtype     : "button",
               ui        : "primary",
               localized : {
                  text : "CORE_SAVE"
               },
               iconCls : "fal fa-save",
               handler : me.onSaveConfiguration.bind(me)
            }
         ],
      };
      me.items = [
         {
            xtype : "container",
            items : [
               {
                  xtype      : "bpcTextField",
                  fieldLabel : "Demo Setting",
                  value      : me.widgetConfiguration.demoSetting,
                  listeners  : {
                     change : me.setDemoSetting.bind(me)
                  }
               }
            ]
         }
      ];
      this.callParent(arguments);
   },
   setDemoSetting : function (e, value) {
      const me = this;
      me.widgetConfiguration.demoSetting  = value;
   },
   onSaveConfiguration : function () {
      const me = this;
      me.fireEvent("saveWidgetConfiguration", me.widgetConfiguration);
   }
});

Ungültige Konfigurationsansicht (WrongConfigurationPanel)

Hierbei handelt es sich um die Komponente, die angezeigt wird, wenn die Konfiguration nicht gültig ist. Sie enthält einen Button, mit dem auf die Konfigurationsansicht gewechselt werden kann.

Beispiel Haupt-Widget-Klasse:

Ext.define("widget.templateWidget.WrongConfigurationPanel", {
   alias  : "widget.templateWidgetWrongConfigurationPanel",
   extend : "Ext.panel.Panel",

   layout : {
      type  : "vbox",
      pack  : "center",
      align : "middle"
   },
   padding : 10,

   initComponent : function() {
      const me = this;
      me.items = [
         {
            xtype     : "box",
            localized : {
               html : "CORE_INVALID_WIDGET_CONFIG"
            }
         },
         {
            xtype     : "button",
            localized : {
               text : "CORE_CONFIGURATION_SHOW"
            },
            iconCls : "x-fal fa-cog",
            handler : me.showSettingPanel.bind(me)
         }
      ];
      this.callParent(arguments);
   },

   showSettingPanel : function() {
      const me = this;
      me.fireEvent("showSettingPanel");
   }
});

Keywords: