In diesem Tutorial wird Ihnen beschrieben, welche Plugin-Konfigurationen es in Shopware gibt, und wie Diese funktionieren. Es werden alle möglichen Plugin-Konfigurationen erklärt so wie die möglichen Parameter und deren Funktion.

Alle Form-Elemente werden in die install-Methode des Plugins geschrieben. Zunächst muss ein Form-Objekt erstellt werden.

$form = $this->Form();

Mittels der Funktion setElement wird dann ein Element erstellt. Als Parameter werden standardmäßig das Element selbst, ein Name für das Element und weitere Optionen übergeben. Auf Letzteres kommen wir am Ende noch einmal zu sprechen. Anschliessend muss das Element nurnoch gespeichert werden.

$form = $this->Form();
$form->setElement($element, $name, $options);
$form->save();

Aufrufbar sind die dort eingetragenen Daten dann über das Config-Objekt des jeweiligen Plugins.

 
$config = Shopware()->Plugins()->(Frontend()/Backend()/Core())->PluginName()->Config();
 

Es muss natürlich ausgewählt werden, ob das Plugin im Frontend, Backend oder im Core arbeitet.

Würden wir beispielsweise ein Plugin erstellen wollen, das jeden Tag zu einer bestimmten Zeit die Preise senkt, so würden wir mindestens drei Einstellungen in der Plugin-Konfiguration benötigen: Die Zeit, zu der die Preissenkung beginnt, die Dauer der Preissenkung und beispielsweise der prozentuale Rabatt. Zu diesem Zweck müssen wir die Form-Elemente kennen.

Das Textfield ist ein simples Textfeld, in denen kleinere Strings eingegeben werden können. Beispielsweise soll ein Plugin erstellt werden, das nur in Bereichen aktiv sein soll, die der Benutzer im Plugin angibt.

Wir geben also als ersten Parameter das Element an. In diesem Fall ist dies text. In den zweiten Parameter schreiben wir den Namen, über den wir das Element ansprechen können. In unserem Beispiel nennen wir das Textfeld einfach einmal availableControllers. Der Name sollte, wenn möglich, kurz und erklärend sein. Als letzten Parameter übergeben wir ein Array mit weiteren Einstellungen, wie beispielsweise einem Label für das Textfeld, einem Standard-Value und den Scope.

 
$form = $this->Form();
$form->setElement('text', 'availableControllers', array('label'=>'Auflistung der Controller', 'value'=>'index,listing,detail','scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->save();
 

Beispiel eines Textfeldes zur Eingabe eines kurzen Textes

Sollte uns das Textfeld nicht ausreichen, da einfach längere Texte eingegeben werden müssen, so bietet sich die Textarea bzw. der Textbereich ideal dafür an. Die Textarea ist prinzipiell das Selbe, wie das Textfeld, nur ist dort mehr Platz gewährleistet. Die Einbindung verläuft ähnlich.

 
$form = $this->Form();
$form->setElement('textarea', 'availableControllers', array('label'=>'Auflistung der Controller', 'value'=>'index,listing,detail','scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->save();
 

Beispiel eines Textbereiches zur Eingabe eines längeren Textes

Nun kommen wir zur Checkbox. Diese kann beispielsweise dem Zweck dienen, dass der Benutzer bestimmte Einstellungen des Plugins selbst festlegen kann. Angenommen wir schreiben ein Plugin, welches den Login erzwingt, bevor man den Shop sehen kann, so muss es eine Einstellung geben, die bei wiederholter falscher Passworteingabe den Login für diese ID für x Minuten sperrt. Da nicht jeder Kunde eine solche Einstellung wünscht, sollte sie leicht ausschaltbar sein.

 
$form = $this->Form();
$form->setElement('checkbox', 'preventLogin', array('label'=>'Login bei Falscheingabe sperren', 'value'=>'0','scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->save();
 

Beispiel einer Checkbox für simple Ja/Nein-Fragen

Wir bleiben bei dem oben genannten Beispiel. Nun kann der Nutzer zwar einstellen, ob eine Sperre erscheint, allerdings nicht wann und wie lange. Dafür bräuchte das Plugin zwei weitere Felder, einmal für die Zeit der Sperre und einmal für die Anzahl der möglichen Versuche. Da beide Felder ausschließlich Zahlen enthalten, nutzen wir hier das Numberfield. Dieses wird wie alle bisher vorgestellten Elemente eingebunden.

 
$form = $this->Form();
$form->setElement('checkbox', 'preventLogin', array('label'=>'Login bei Falscheingabe sperren', 'value'=>'0','scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->setElement('numberfield', 'availableTries', array('label'=>'Anzahl Versuche', 'value'=>'3','scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->setElement('numberfield', 'disabledTime', array('label'=>'Zeit der Sperre(in Minuten)', 'value'=>'15','scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->save();
 

Beispiel eines Nummernfeldes zur Beschränkung der Eingabe auf Zahlen

Das Timefield ist zunächst ein simples Dropdown-Menü mit allen möglichen Zeiten. Ein Plugin, welches eine Art Happy Hour erstellt, würde dieses benötigen. Sie bräuchten ein Feld zur Eingabe der Startzeit und ein Feld zur Eingabe der Dauer, beispielsweise 30 Minuten. Ein weiteres optionales Feld wäre z.B. der prozentuale Rabatt. Für Ersteres empfiehlt sich das Timefield.

 
$form = $this->Form();
$form->setElement('timefield', 'startHappyHour', array('label'=>'Anfang der Happyhour', 'value'=>'','scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->setElement('text', 'time', array('label'=>'Dauer der Happy Hour', 'value'=>'15','scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->save();

Beispiel eines Zeitfeldes zur Auswahl der Zeit

Zusätzlich zu dem Timefield, bietet Shopware das Datefield. Der Unterschied ist, wie der Name schon sagt, dass beim Datefield ein Datum auswählbar ist. Dies bietet zum Beispiel die Möglichkeit an bestimmten Tagen einen bestimmten Inhalt anzeigen zu lassen, z.B. zu Weihnachten ein entsprechender Gruß.

 
$form = $this->Form();
$form->setElement('datefield', 'date', array('label'=>'Datum der Ausführung','value'=>'', 'scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->save();
 

Beispiel eines Datumfeldes zur Auswahl des Datums

Wollen wir jetzt den Weihnachtsgruß formatieren, so dient uns die Textarea bzw. der Textbereich auch nicht mehr so gut. Hierfür hat Shopware den sogenannten "WYSIWYG-Editor".

Dieses steht für "What You See Is What You Get", also "Was du siehst ist, was du kriegst". Der WYSIWYG-Editor hat den Vorteil, dass alle Textformatierungen, die gewünscht sind, direkt angezeigt werden. Weiterhin ist es möglich HTML-Code einzubinden.

 
$form = $this->Form();
$form->setElement('htmleditor', 'myHTMLCode', array('label'=>'Anzuzeigender Text','value'=>'', 'scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->save();
 

Beispiel eines WYSIWYG-Editors zur Eingabe eines formatierten Textes.

Angenommen wir wollen unseren Text als Snippet speichern, um diesen dann auch übersetzen zu können. Da macht es Sinn den neuen Benutzer, der sich noch nicht sehr gut mit Shopware auskennt, direkt auf den Controller zu verlinken. Dies ermöglich der Controller-Button. Unter den übergebenen Parametern muss dafür der entsprechende Controller angegeben werden.

 
$form = $this->Form();
$form->setElement('htmleditor', 'myHTMLCode', array('label'=>'Anzuzeigender Text','value'=>'', 'scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->setElement('controllerbutton', 'snippetController', array('label'=>'Textbausteine aufrufen','value'=>'','attributes'=>array('controller'=>'snippet','action'=>'skeleton'), 'scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->save();
 

Beispiel eines Controller-Buttons zum Aufruf eines Controllers direkt aus dem Plugin

Nun kommen wir zu einem etwas komplexeren Form-Element. Es soll nun auch möglich sein, den Weihnachtsgruß ab dem angegeben Datum drei Tage lang anzuzeigen. Dies würde sich über ein Textfield oder ein Numberfield realisieren lassen. Eine weitere Möglichkeit ist die Combobox, die ein Dropdown-Menü erstellt.

Die anzuzeigenden Daten werden per ExtJS übergeben.

 
$form->setElement('combo', 'timeToDisplay', array('label'=>'Anzeige in Tagen','value'=>'2','attributes'=>array(
		'valueField'=>'myId','displayField'=>'displayText',
		'mode' => 'local',
		'triggerAction' => 'all',
		'store' => '
		new Ext.data.ArrayStore({
        id: 0,
        fields: [
            "myId",
            "displayText"
        ],
        // Hier kommen die wichtigen Informationen rein
        data: [[1, "1"], [2, "2"], [3, "3"], [4, "5"], [5, "10"], [6, "15"]]
    	})
		'
		),'scope'=>Shopware_Components_Form::SCOPE_SHOP));
 

Beispiel einer Combobox zur Erstellung eines Dropdown-Menüs mit eigenen Daten

Was ist nun aber, wenn wir einen bestimmten Inhalt aus dem Shop lesen wollen, und dieser per Dropdown auswählbar sein soll? Die Remote Combo-Box bietet die Möglichkeit ein dynamisches Dropdown-Menü zu erstellen. Hierfür wird die Action eines Controllers aufgerufen. Dafür muss natürlich, je nach Wunsch, eine entsprechende Action in einem entsprechenden Controller erstellt werden.

Testweise laden wir alle Benutzer, die im Backend angelegt sind.

 
$form->setElement('comboremote', 'usersBackend', array('label'=>'Backend-Benutzer','value'=>'','attributes'=>array(
		'valueField'=>'id','displayField'=>'username',
		'mode' => 'remote',
		'triggerAction' => 'all',
		'controller' => 'widgets',
		'action' => 'getUsers',
		'root' => 'data',
		'totalProperty' => 'count',
		'fields' => array('id','username')
		)));
 

Wichtig ist hier, dass

a) der Controller angegeben wird

b) die Action angegeben wird

c) der Name des Roots, meistens data, angegeben wird.

Beispiel einer Remotecombo-Box zur Erstellung eines Dropdown-Menüs mit dynamischen Daten

In diesem Teil geht es ausschliesslich um den letzten übergebenen Parameter $options. Dieser ist der dritte Parameter, nach $element, also dem Element-Typ, und $name, also dem Namen. In den Beispielen haben wir bereits mögliche Einstellungen des $option-Parameters kennengelernt. In den meisten Fällen ist der übergebene Parameter ein Array.

Das Label ist immer eine Art Kurzbeschreibung, die vor oder auf dem Form-Element steht. Über Dieses soll der Benutzer die Funktionalität des Form-Elements verstehen.

 
$form = $this->Form();
$form->setElement('text', 'ourTextfield', array('label'=>'Unser Textfeld'));
$form->save();
 

Beispiel - Label (rot markiert)

Das Value steht für den Standard-Wert. Bei fast allen Elementen ist es möglich einen Value zu setzen. Dieser wird direkt in dem entsprechenden Element angezeigt. Haben wir beispielsweise ein Plugin, welches nur bei bestimmten Controllern reagieren soll und die Controller nahezu immer die Gleichen sind, so macht es Sinn diese direkt anzugeben. Das Value lässt sich ebenfalls gut als Beispielvorlage nutzen, um dem Benutzer zu zeigen, wie eine Eingabe in dem Element aussehen kann.

 
$form = $this->Form();
$form->setElement('text', 'availableControllers', array('label'=>'Auflistung der Controller', 'value'=>'index,listing,detail'));
$form->save();
 

Beispiel - Value (rot markiert)

Mittels des Scopes ist es möglich, die Plugin-Konfiguration pro Subshop anders zu gestalten. Lässt man den Scope weg, so wird eine Konfiguration für alle Subshops gewählt.

$form = $this->Form();
$form->setElement('text', 'availableControllers', array('label'=>'Auflistung der Controller', 'value'=>'index,listing,detail','scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->save();

Beispiel - Scope (rot markiert)

Es lässt sich auch eine Beschreibung für die Form-Elemente hinterlegen. Dies geschieht ebenfalls über den $options-Parameter.

 
$form = $this->Form();
$form->setElement('text', 'availableControllers', array('label'=>'Auflistung der Controller', 'description'=>'Auflistung der Controller, bei denen das Plugin ausgeführt wird.', 'value'=>'index,listing,detail','scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->save();
 

Es gibt Fälle, in denen will man die Eingabe des Benutzers erzwingen. Ein Beispiel dafür sind diverse Schnittstellen, die eine ID des Benutzers verlangen. Dafür wird required genutzt.

 
$form = $this->Form();
$form->setElement('text', 'availableControllers', array('label'=>'Auflistung der Controller','required'=>true, 'value'=>'index,listing,detail','scope'=>Shopware_Components_Form::SCOPE_SHOP));
$form->save();
 

Beispiel - Required

Als Letztes kommen wir zu den Attributen. In den Attributen lassen sich, wie man sich denken kann, Eigenschaften bzw. Attribute eines Elements hinterlegen. Dort kann man dann beispielsweise bestimmte Werte speichern, die man wieder aufrufen will. Auch ExtJS Code und Funktionen lassen sich über das Attribut aufrufen.

Dafür folgendes Beispiel, in dem ein Wert auf seine Richtigkeit überprüft wird, mittels des Attributs. Dort wird eine UniqueID, also eine einzigartige ID, gespeichert, über die das Element bzw. der Wert des Elements ausgelesen werden kann.

 
$form = $this->Form();
$form->setElement('text', 'configkey', array('label'=>'Ihr Konfigurationsschlüssel', 'value'=>'xyz','attributes'=>array("uniqueId"=>'configkey')));
$form->setElement('button', 'test10', array('label'=>'Zugangsdaten prüfen','attributes'=>array(
'handler'=>'function (){
	// The plugin form details does not support the button element by default
	// We could use the support of custom attributes to fix this
	// In order to use custom attributes with embedded javascript, we have to
	// define one of the keywords (new or store) at this place. See plugin\detail.tpl for more details
 
	// Get reference to textfield by custom attribute uniqueId
	// Could not use elements id cause of multiple subshop configuration
	var configTextfieldObject = this.ownerCt.find(\'uniqueId\',\'configkey\')[0];
 
	// Get value from this field
	var configKey = configTextfieldObject.getValue();
 
	// Only proceed if input available
	if (!configKey){
		Ext.MessageBox.alert(\'Ups\',\'Bitte geben Sie einen Konfigurationsschlüssel ein!\');
		configTextfieldObject.getEl().setStyle(\'background\',\'red\');
		return;
	}
 
	// Doing ajax request to a custom controller
	// We cannot use shopware build in {url syntax - this part get not parsed by smarty
	// Instead we get host and path information via javascript and attached our custom controller
	Ext.Ajax.request({
	   scope:this,
	   url: window.location.protocol+\'//\'+window.location.host+window.location.pathname.replace(/plugin/,\'\')+\'?controller=widgets&action=getUsers\',
	   success: function(result,request) {
	   		// If request succeeded, decode json response (Sample code)
	   		/*var jsonData = Ext.util.JSON.decode(result.responseText);
            var resultMessage = jsonData.data.result;
            if (resultMessage == "success"){}
            */
 
			Ext.MessageBox.alert(\'Success\',\'Valid data!\');
			configTextfieldObject.getEl().setStyle(\'background\',\'green\');
	   },
	   failure: function() {
	   		configTextfieldObject.getEl().setStyle(\'background\',\'red\');
			Ext.MessageBox.alert(\'Ups\',\'Url not reachable\');
	   },
	   // Pass all needed parameters
	   params: { testVariable: configKey }
	});
 }',
'text' => 'Start',
'xtype' => 'button'
)));
$form->save();
 

Beispiel eines Attributs zur Einbindung von eigenem Javascript-Code