Konfigurationsdialoge erstellen

Zu Formaten und Funktionen können im eCMS Konfigurationsdialoge (Config-Dialog) hinterlegt werden und so das Einstellen von Komponenten für die User vereinfacht werden. Dieser Artikel schreibt wie diese Konfigurationsdialoge erstellt werden können.

Einleitung

Die Konfigurationsdialoge werden vom eCMS innerhalb des eCMS-Admin ausgeführt. In den Konfigurationsdialogen kann damit auf alle eCMS-Admin-Komponenten (z.B. eCMS-Admim-Inputs) zugriffen werden.

Wird für die Feld-Namen und -Beschreibungen das vorbereitete Übersetzungsverfahren genutzt, sind die i18n-Textbausteine im eCMS-Admin hinterlegt.

Um in einem Konfigurationsdialoge auf die Daten der Site zuzugreifen, müssen die Aufrufe über das Plugin-SiteControl durchgeführt werden, z.B. $this->eCMS->plugin_siteControl->ecms_cdb->category->categoryTree_getList(...).

 

Formate

Für die Konfigurationsdialoge bei Formaten sind in der Format-Base-Class "ecms_formatObj" die folgenden Methoden definiert:

  • protected function configDialog_dataConvertPostValidate($params)
    Callback nach erfolgreicher Input-Validierung, in dem die Format-Parameter vom Speichern geändert / vervollständigt werden können.
  • protected function configDialog_dataConvertPreRender($params)
    Callback vor Dialog-Render, in dem die Format-Parameter an den Dialog angeglichen werden können.
  • protected function configDialog_getFields()
    Callback für die Dialog-Fields.
  • protected function configDialog_getFieldsAndCreateInputs()
    Interne Service-Methode ruft die Dialog-Fields über "configDialog_getFields" ab und erzeugt die Instanzen zu den Fields.
  • public function configDialog_render($params)
    Render-Methode des Dialogs.
  • public function configDialog_routeAjaxAction($params)
    Service-Methode leitet Ajax-Requests an die Dialog-Fields durch.
  • public function configDialog_validate($params)
    Validate-Methode für die User-Eingabe.

Das empfohlene Vorgehen für die Erstellung eines Format-Konfigurationsdialogs ist, die Methode "configDialog_getFields" in dem Format zu überschreiben. Falls erforderlich, können mit den vorbereiteten Callbacks "configDialog_dataConvertPreRender" und "configDialog_dataConvertPostValidate" Struktur-Unterschiede zwischen den Format-Parametern und den Dialog-Field-Inputs angepasst / umgeschrieben werden.

Aus der Methode "configDialog_getFields" muss eine Liste der Fields des Dialogs zurückgeliefert werden.

  1. protected function configDialog_getFields()
  2. {
  3.     return array(
  4.         'status' => true,
  5.          'fields' => array(
  6.              'css_class' => array(
  7.                  'format' => 'ecms_input_text',
  8.                  'params' => array('btfy_trim' => true),
  9.                  'i18n_string' => 'ecms.html_attribute.css_class',
  10.                  'mandatory' => true,
  11.              ),
  12.             'css_style' => array(
  13.                  'format' => 'ecms_input_textarea',
  14.                  'params' => array('rows' => 3),
  15.                  'i18n_string' => 'ecms.html_attribute.css_style',
  16.                  'advanced' => true,
  17.              ),
  18.             ...
  19.          ),
  20.      );
  21.  }

Für verschachtelte Format-Parameter (Array) ist das Input-Format eine vorbereitet Option. Mit dem Field-Parameter "mandatory" gleich "true" wird das Field  als Pflichtfeld deklariert. Über den Field-Parameter "advanced" gleich "true" wird ein Field als erweiterte Option deklariert und wird in einen aufklappbaren verstecken Bereich im Konfigurationsdialoge platziert.

  1. protected function configDialog_getFields()
  2. {
  3.     return array(
  4.         'status' => true,
  5.          'fields' => array(
  6.             'css' => array(
  7.                 'format' => 'ecms_input_fieldCollection',
  8.                 'params' => array(
  9.                     'fields' => array(
  10.                         'class' => array(
  11.                             'format' => 'ecms_input_text',
  12.                              'params' => array('btfy_trim' => true),
  13.                              'i18n_string' => 'ecms.html_attribute.css_class',
  14.                          ),
  15.                         'style' => array(
  16.                             'format' => 'ecms_input_textarea',
  17.                              'params' => array('rows' => 3),
  18.                              'i18n_string' => 'ecms.html_attribute.css_style',
  19.                          )
  20.                     )
  21.                 ),
  22.                 'skip_field_name' => true,
  23.             ),
  24.             ...
  25.          ),
  26.      );
  27.  }

Mit dem Parametr skip_field_name wird beim Field "css" die Ausgabe des Field-Namen deaktiviert und das Input über die volle Breite ausgegeben.

 

Lib-Komponente Eintrag

Im Lib-Komponente-Eintrag zum Format, wird der Format-Name ("<format-name>.class.php") im Feld "Label" eingetragen.

Die Felder "Eingabe (Typ)" (z.B. "ecs_product", "cdb_record", "cdb_category", etc.) und "Eingabe (Struktur)" (z.B. "erecord", "elist", "etree", etc.) sollten gefüllt werden. Über die Information kann eine passende Daten-Funktion ermittelt werden. Sollte ein Format mehrere Typen oder Strukturen verarbeiten können, können die Optionen durch Komma getrennt (z.B. "elist,etree") eingetragen werden. Durch ein Sternchen "*" kann die Verarbeitung von allen Typen und Strukturen gekennzeichnet werden.

Für ein Format ohne Daten-Funktion kann im Feld "Eingabe (Typ)" der String "__none__" hinterlegt werden, um die Daten-Funktion im Konfigurationsdialog zu deaktivieren.

In den Komponent-Zusatzdaten kann für ein Format Standard/Preset-Daten hinterlegt werden. Dies können Format-Parameter und eine Daten-Funktion mit Parametern sein.

  1. defaults:
  2.   format_params:
  3.     param1: value1
  4.     param2: value2
  5.   function: plugin_ecs__ecs_product_dsf__product_get
  6.   function_params:
  7.     filter:
  8.       xc__label: #ecms_get[xc__label]

 

Funktionen

Die Konfigurationsdialoge zu Funktionen werden in den Zusatzdaten des Lib-Komponent-Eintrags der Funktion hinterlegt.

Das empfohlene Vorgehen ist die Verwendung einer von "eCMS_functionConfigDialog_base" abgeleiteten Klasse. In dieser Klasse können die Konfigurationsdialoge zu mehreren Funktionen hinterlegt werden, z.B. pro Datentyp oder Plugin.

  1. class eCMS_functionConfigDialog_example extends eCMS_functionConfigDialog_base
  2. {
  3.     ...
  4. }

In den Komponent-Zusatedaten der Funktion wird die Klasse als Konfigurationsdialog-Format hinterlegt:

  1. config_dialog:
  2.  format: eCMS_functionConfigDialog_example

In der Konfigurationsdialog-Klasse muss für die Funktion eine Init-Callback-Methode implementiert werden. Der Methodenname des Init-Callbacks ergibt sich aus dem Lib-Komponenten-Label "<lib-componenten-label>__initDialog".

  1. class eCMS_functionConfigDialog_example extends eCMS_functionConfigDialog_base
  2. {
  3.     protected function ecms_plugin_example__example_getlist_initDialog()
  4.     {
  5.         $this->params['fields'] = array(
  6.                 'ex_label' => array(
  7.                     'format' => 'ecms_input_text',
  8.                     'mandatory' => true,
  9.                     'i18n_string' => 'ecms.example.parameter_ex_label',
  10.                 ),
  11.                 ...
  12.             );
  13.  
  14.         return array('status' => true);
  15.     }
  16.     ...
  17. }

Die Base-Klasse "eCMS_functionConfigDialog_base" basiert auf dem Input-Format und bietet dessen Parameter-Optionen für die Funktion-Konfigurationsdialoge.

 

Lib-Komponente Eintrag

Im Lib-Komponente-Eintrag zur Funktion, wird der Funktion-Aufruf vom eCMS als Komponent-Label eingetragen (z.B. "ecms_plugin_example__example_getlist"). 

Die Felder Ergebnis (Typ)" (z.B. "ecs_product", "cdb_record", "cdb_category", etc.) und Ergebnis (Struktur)" (z.B. "erecord", "elist", "etree", etc.) sollten gefüllt werden. Über diese Informationen kann ein passendes Format ermittelt werden.