Formularmanager Widget-Plugins

Plugins können an zwei Orten eingebunden werden. Zum einen im myty Ordner unter /tycon/modules/formmanager/plugins. Dieser Ordner ist für Plugins vorgesehen, die standardmäßig mit dem myty ausgeliefert werden. Zum anderen unter /media/templates/formmanager/plugins. In diesen Ordner können alle zusätzlichen Plugins gespeichert werden.

Das Plugin besteht aus einer PHP-Datei die eine gleichnamige Klasse enthält. Diese Klasse muss von der abstrakten Klasse tyFormmanagerWidgetPlugin erben.

example_text_plugin.php

<?php class example_text_plugin extends tyFormmanagerWidgetPlugin {} ?>

Es gibt zur Zeit 7 Methoden die durch das Plugin implementiert werden können. Die Implementierung ist für alle Methoden optional. Es müssen also nur die Methoden überschrieben werden, die für das Plugin auch notwendig sind. In der nachfolgenden Liste sind auch die Standardwerte für nicht überschriebene Methoden ersichtlich.

Weiterhin steht eine Konstante zur Verfügung um die Version der Plugin-Schnittstelle abzufragen.

const WIDGET_PLUGIN_VERSION = 3;

/**
* Überprüft ob die Mindestanforderungen für dieses Plugin erfüllt sind
* Liefert standardmäßig immer true zurück, muss durch das betreffende Plugin überschrieben werden um eine Prüfung vorzunehmen
*/
public static function checkRequirements()

{
        return true;
}
 
/**
 * Liefert alle zusätzlichen Widgets zurück, die dieses Plugin bereitstellt.
 * Werden keine zusätzlichen Widgets bereitgestellt muss null/false zurückgeliefert werden
 *
 * @param String $tableName Der Name der aktuellen Tabelle
 * @return Array Ein Feld mit allen Widgets, sowie die Datenbankfeldtypen, für die dieses Widget verwendet werden kann
 * Bsp: array('WidgetName1'=>array('text','blob'),'WidgetName2'=>array('enum'));
 */
public static function getAdditionalWidgets($tableName)

{
        return array();
}
 
/**
 * Fügt zusätzliche Einstellungen bei der Formularkonfiguration hinzu
 *
 * @param String $widget Name des Widgets
 * @param Integer $formWidgetId Id des Widgets (= Position im Formularmanager)
 * @param Array $values enthält die aktuellen Einstellungen ($values['plugins'][PLUGINNAME] enthält die Einstellungen für dieses Plugin)
 * @param String $trClass Name der Klasse für die Tabellenzeile
 * @return String HTML Code für den zusätzlichen Formularabschnitt
 */
public static function getAdditionalWidgetSettings($widget,$formWidgetId,$values,$trClass)

{
        return '';
}
 
/**
 * Liefert den HTML Quellcode für das bei $widget angegebene Element zurück
 *
 * @param String $widget Name des Widgets
 * @param String $value Der Wert der Nutzereingabe (wenn z.B. ein alter Datensatz geladen wurde oder ein Fehler im Formular auftrat)
 * @param Array $layoutData Alle Daten die für die Ausgabe benötigt werden könnten (Styles, Ids, Attribute, zusätzliche Einstellungen)
 * @param Array $pluginSettings Alle im Formularmanager vorgenommenen Einstellungen für das aktuelle Element
 * @param String $location viewFrontend wenn das Formular im Frontend angezeigt wird, viewBackend bei Anzeige im Backend
 * @return String Quellcode für das Widget
 */
public static function getWidgetCodeFor($widget,$value,$layoutData,$pluginSettings,$location)

{
        return '';
}
 
/**
 * Verarbeitet die Daten des Widgets
 * Im einfachsten Fall besteht diese Funktion nur aus der Zeile "return $value;"
 * In diesem Fall wird genau der im Formular angegebene Wert in die Datenbank geschrieben
 *
 * @param String $widget Name des Widgets
 * @param String $value Der Wert der Nutzereingabe
 * @param String $inputName Name des Felds, in dem der Wert übertragen wurde
 * @param String $dbColumn Name der Spalte in der Datenbank, in die der Wert geschrieben wird
 * @param Array $pluginSettings Alle im Formularmanager vorgenommenen Einstellungen für das aktuelle Element
 * @return String aufbereitete Daten für die Tabelle
 */
public static function processWidgetData($widget,$value,$inputName,$dbColumn,$pluginSettings)

{
        return $value;
}
 
/**
 * Verarbeitet die Daten des Widgets und prüft diese auf eventuelle Fehleingaben
 * Sind alle Eingaben in Ordnung muss false zurückgeliefert werden
 *
 * @param String $widget Name des Widgets
 * @param String $value Der zu prüfende Wert der Nutzereingabe
 * @param String $inputName Name des Inputfelds, in dem der Wert übertragen wurde
 * @param String $dbColumn Name der Spalte in der Datenbank, in die der Wert geschrieben wird
 * @param Array $pluginSettings Alle im Formularmanager vorgenommenen Einstellungen für das aktuelle Element
 * @return Boolean true wenn ein Fehler auftrat, false wenn nicht
 */
public static function processWidgetDataError($widget,$value,$inputName,$dbColumn,$pluginSettings)

{
        return false;
}
 
/**
 * Speichert zusätzliche Daten für das Widget
 * Diese Funktion kann genutzt werden um Siterolesdaten und Nutzereinstellungen zu speichern, Mails zu versenden oder ähnliches
 * Es wird kein return-Wert erwartet
 *
 * @param Array $dbData Die kompletten Daten aller Felder des Formulars
 * @param Array $processedWidgets Alle Eingabefelder die von diesem Plugin mittels processWidgetData() verarbeitet wurden
 * @param Integer $subjectId SiterolesId des Nutzers - Falls die Daten an einem Siterolesnutzer gespeichert werden sollen
 * @param Array $allPluginSettings Alle im Formularmanager vorgenommenen Einstellungen für ALLE Elemente
 */
public static function saveAdditionalData($dbData,$processedWidgets,$subjectId,$allPluginSettings)

{
}

Neben den öffentlichen Methoden, die durch den Formularmanager aufgerufen werden, steht noch eine Reihe von hilfreichen, internen Funktionen zur Verfügung. Diese dienen zur Darstellung von HTML Komponenten im Stil des Formularmanagers. Dabei gibt es zwei Bereiche:

Die Anwendung dieser Methoden ist im Beispiel in der Methode getAdditionalWidgetSettings zu sehen.

/**
* Packt den übergebenen HTML Quellcode in eine Einstellungskategorie mit dem übergebenen Namen
* @param String $settingsName Der Name der Einstellungskategorie
* @param String $settingsHTML Der HTML Quelltext für alle Elemente in dieser Kategorie
* @return String HTML Quelltext, der nun von einer Einstellungskategorie mit Namen umgeben ist
*/
protected static function settingsMainHTML($settingsName,$settingsHTML);

 
/**
* Packt den übergebenen HTML Quellcode in eine Box mit einem Label
* @param String $labelText Der Text für das Label (wird übersetzt)
* @param String $inputElementHTML Der HTML Quelltext für das Eingabefeld (input, select, etc.)
* @return String HTML Quelltext der Box mit dem übergebenen Namen und dem übergebenen Element
*/
protected static function settingsBoxHTML($labelText,$inputElementHTML);
 
/**
* Stellt eine Selectbox anhand der übergebenen Daten zusammen
* @param String $formWidgetId Die eindeutige ID innerhalb des Formulars für dieses Element
* @param Array $pluginSettings Alle Einstellungen für das Widget Plugin
* @param String $selectName Der Name für das select Feld
* @param Array $selectData Die Daten für das select
* @param Boolean $multiSelect true falls das select eine mehrfache Auswahl zulassen soll, false wenn nicht (Defaultwert: false)
*/

protected static function settingsSelectHTML($formWidgetId,$pluginSettings,$pluginName,$selectName,$selectData,$multiSelect=false);

 
/**
* Stellt eine Inputbox anhand der übergebenen Daten zusammen
* @param String $formWidgetId Die eindeutige ID innerhalb des Formulars für dieses Element
* @param Array $pluginSettings Alle Einstellungen für das Widget Plugin
* @param String $inputName Der Name für das input Feld
* @param Boolean $password true für ein Passwort Feld, false für ein normales Eingabefeld (Defaultwert: false)
* @param String $defaultText Standardtext der angezeigt wird, wenn noch kein Text eingegeben wurde (optional)
*/
protected static function settingsInputHTML($formWidgetId,$pluginSettings,$pluginName,$inputName,$password=false,$defaultText='');

 
/**
* Stellt eine Checkbox anhand der übergebenen Daten zusammen
* @param String $formWidgetId Die eindeutige ID innerhalb des Formulars für dieses Element
* @param Array $pluginSettings Alle Einstellungen für das Widget Plugin
* @param String $checkboxName Der Name für das input Feld
* @param String $description Beschreibung für die Checkbox (optional)
*/
protected static function settingsCheckboxHTML($formWidgetId,$pluginSettings,$pluginName,$checkboxName,$description='');

Die Anwendung dieser Methoden ist im Beispiel in der Methode getWidgetCodeFor zu sehen.

/**
 * Liefert die zusätzlich für ein Element gesetzten Attribute zurück
 * @param Array $layoutData Enthält alle Attribute die gesetzt werden sollen
 * @param String $nameAdditional Zusatz für das Attribut 'name'
 * @return String Alle Attribute außer id in der HTML Schreibweise
 */
protected static function formAttributesHTML($layoutData,$nameAdditional='',$idAdditional='');

 
/**
* Gibt den HTML Code für die Labels im Formularmanager Style aus
* @param Array $layoutData Enthält alle Attribute die gesetzt werden sollen
* @param String $idAdditional Zusatz für alle ID Attribute
* @param String $customText Angepasster Text für das Label
* @return HTML Code für das Label
*/
protected static function formLabelHTML($layoutData,$idAdditional='',$customText=null);

 
/**
* Gibt den HTML Code für die Fehlermeldung im Formularmanager Style aus
* @param Array $layoutData Enthält alle Attribute die gesetzt werden sollen
* @param String $idAdditional Zusatz für alle ID Attribute
* @param String $customErrorText Angepasster Fehlertext für das Label
* @return HTML Code für die Fehlermeldung
*/
protected static function formErrorMessageHTML($layoutData,$idAdditional='',$customErrorText=null);

 
/**
* Gibt den HTML Code für die Beschreibung im Formularmanager Style aus
* @param Array $layoutData Enthält alle Attribute die gesetzt werden sollen
* @return HTML Code für die Beschreibung
*/
protected static function formDescriptionHTML($layoutData);
 
/**
* Packt den übergebenen String in einen standard div-Container des Formularmanagers
* @param Array $layoutData Enthält alle Attribute die gesetzt werden sollen
* @param String $content Der Inhalt für den div-Container
* @param Boolean $containsSelectBox true falls der Inhalt eine SelectBox ist, false falls nicht (beeinflusst die verwendete CSS-Klasse)
* @return HTML Code der nun vom standard div-Container umgeben ist
*/
protected static function formDivContainerHTML($layoutData,$content,$containsSelectBox=false);

Das Beispiel Plugin gibt lediglich ein Eingabefeld aus. Dabei kann eingestellt werden ob es sich um ein Passwortfeld mit nicht sichtbarer Eingabe handelt oder um ein normales Textfeld. Weiterhin kann der Text beim Speichern auf 10 Zeichen begrenzt werden. Der Wert „test“ bei einer Eingabe wird als Fehler behandelt, alle anderen Werte sind gültig. Weiterhin wird für jedes Formular in dem das Element verwendet wird eine Nachricht in die Logdatei ausgegeben.

Das Beispiel kann nachfolgend heruntergeladen werden. Wird die Datei in eines der beiden Plugin-Verzeichnisse gelegt, erscheint das Plugin im Formularmanager unter dem Namen Example Text für alle Felder vom Typ varchar bzw. char.

example_text_plugin.php

<?php
 
/**
 * Beispiel Plugin für den Formularmanager
 *
 */ 
class example_text_plugin extends tyFormmanagerWidgetPlugin
{
        const PLUGINNAME = 'Example Text';

        // Version der Widget Plugin Schnittstelle die vom Plugin mindestens benötigt wird
        const REQUIRED_WIDGET_PLUGIN_VERSION = 2;
 
        /**
        * Überprüft ob die Mindestanforderungen für dieses Plugin erfüllt sind
        * Kann zum Überprüfen von vorhandenen Modulen oder Versionsnummern genutzt werden
        * In diesem Fall wird die Versionsnummer des Widget-Plugin-Systems des Formularmanagers abgefragt
        */
        public static function checkRequirements()

        {
                if (self::WIDGET_PLUGIN_VERSION >= self::REQUIRED_WIDGET_PLUGIN_VERSION) return true;

                trigger_error('Formmanager plugin "'.self::PLUGINNAME.'" needs a higher version of the plugin interface. Plugin skipped.');
                return false;

        }
 
        /**
         * Liefert die in diesem Plugin implementierten Formularelemente zurück
         *
         * @param String $tableName Name der angebundenen Tabelle
         * @return Array Feld mit allen zusätzlichen Formularelementen, sowie für welche Datenbankfelder diese verwendet werden können
         */
        public static function getAdditionalWidgets($tableName)
        {

                $widget = array(self::PLUGINNAME=>array('varchar','char'));
                return $widget;

        }
 
        /**
         * Liefert die zusätzlichen Einstellungen für das angegebene Element zurück
         * Diese werden beim Konfigurieren des Formulars beim jeweiligen Element angezeigt (zusätzlich zu den Standardattributen)
         *
         * @param String $widget Name des Widgets
         * @param Integer $formWidgetId Id des Widgets (richtet sich nach der Reihenfolge im Formular)
         * @param Array $pluginSettings Alle Einstellungen für das Plugin
         * @param String $trClass Klasse die für die Tabellenzeile verwendet werden sollte
         * @return String HTML Code der zusätzlichen Einstellungen
         */
        public static function getAdditionalWidgetSettings($widget,$formWidgetId,$pluginSettings,$trClass)

        {
                $htmlCode = '';
                // Auswahl Typ
                $options = array('text' => 'Text', 'password' => 'Passwort');

                $selectCode = self::settingsSelectHTML($formWidgetId,$pluginSettings,self::PLUGINNAME,'pw',$options);

                $htmlCode.= self::settingsBoxHTML('Typ',$selectCode);                            
                $checkboxCode = self::settingsCheckboxHTML($formWidgetId,$pluginSettings,self::PLUGINNAME,'textLimit','Text auf 10 Zeichen begrenzen');

                $htmlCode.= self::settingsBoxHTML('Limit',$checkboxCode);                                
                return self::settingsMainHTML('Beispiel Einstellungen',$htmlCode);

        }
 
        /**
         * Liefert den HTML Code für die unterstützten Eingabefelder
         *
         * @param String $widget Bezeichnung des Widgets
         * @param String $value Der Wert der Nutzereingabe (wenn z.B. ein alter Datensatz geladen wurde oder ein Fehler im Formular auftrat)
         * @param Array $layoutData Alle Einstellungen die im Formularmanager für das Feld vorgenommen werden können
         * @param Array $pluginSettings Alle im Formularmanager vorgenommenen Einstellungen für das aktuelle Element
         * @return String HTML Code für die Eingabe
         */
        public static function getWidgetCodeFor($widget,$value,$layoutData,$pluginSettings)

        {
                $htmlCode = '';
                // Typ des Eingabefelds abfragen
                $type = $pluginSettings['plugins'][self::PLUGINNAME]['pw'];

                $widgetCode = '';
                $widgetCode .= self::formLabelHTML($layoutData); // Label für das Eingabefeld

                $widgetCode .= '<input type="'.$type.'" '.self::formAttributesHTML($layoutData).'/>';

                $widgetCode .= self::formErrorMessageHTML($layoutData); // Fehlermeldung
                $widgetCode .= self::formDescriptionHTML($layoutData); // Beschreibung des Felds

                $htmlCode .= self::formDivContainerHTML($layoutData,$widgetCode); // Standard Formularmanager Container der die Elemente umschließt
                return $htmlCode;

        }
 
        /**
         * Verarbeitet die Daten, die per Request gesendet wurden und wandelt sie für die Datenbank um
         *
         * @param String $widget Bezeichnung des Widgets
         * @param String $value Der Wert der Nutzereingabe
         * @param String $inputName Name des Inputfelds in dem die Daten übermittelt wurden
         * @param String $dbColumn Name der Tabellenspalte, in der die Daten gespeichert werden sollen
         * @param Array $pluginSettings Alle im Formularmanager vorgenommenen Einstellungen für das aktuelle Element
         * @return String aufbereitete Daten für die Tabelle
         */
        public static function processWidgetData($widget,$value,$inputName,$dbColumn,$pluginSettings)

        {
                // Text auf 10 Zeichen begrenzen, wenn die entsprechende Option aktiviert ist
                if ($pluginSettings['plugins'][self::PLUGINNAME]['textLimit'] == 1) return substr($value,0,10);

                else return $value;
        }
 
        /**
         * Prüft die Eingaben auf Fehler
         *
         * @param String $widget Bezeichnung des Widgets
         * @param String $value Der Wert der Nutzereingabe
         * @param String $inputName Name des Inputfelds in dem die Daten übermittelt wurden
         * @param String $dbColumn Name der Tabellenspalte, in der die Daten gespeichert werden sollen
         * @param Array $pluginSettings Alle im Formularmanager vorgenommenen Einstellungen für das aktuelle Element
         * @return Boolean true bei einem Fehler, false/null bei keinem Fehler
         */
        public static function processWidgetDataError($widget,$value,$inputName,$dbColumn,$pluginSettings)

        {
                // Der Wert "test" ist nicht zulässig
                if ($value == 'test') return true;

                else return false;
        }
 
        /**
         * Ermöglicht zusützliches Speichern der Daten, z.B. als Nutzereinstellung oder in einer seperaten Tabelle
         * sowie das Durchführen weiterer Aktionen (Mail verschicken, etc.)
         *
         * @param Array $dbData Die kompletten Daten aller Felder des Formulars
         * @param Array $processedWidgets Alle Eingabefelder die von diesem Plugin mittels processWidgetData() verarbeitet wurden
         * @param Integer $subjectId SiterolesId des Nutzers (falls dieses Formular mit der Siteroles Tabelle verknüpft ist)
         * @param Array $allPluginSettings Alle im Formularmanager vorgenommenen Einstellungen für ALLE Elemente
         */
        public static function saveAdditionalData($dbData,$processedWidgets,$subjectId,$allPluginSettings)

        {
                if (!is_array($processedWidgets)) return; // Es wurden keinerlei Eingabefelder von diesem Plugin verarbeitet
                trigger_error('A form containing the example plugin was processed');

        }
}
?>