jQuery

Die Funktionen und Objekte in diesem Paket dienen dem Zusammenspiel des Alvine-Frontend-Frameworks mit jQuery. Ein jQuery-Plugin ist ein Objekt, das von Alvine.jQuery.Plugin abgeleitet ist und für das es eine Factory-Methode gibt. Das folgende Beispiel zeigt die Minimalversion eines Plugins.

function Example(options) {
    return new InternalPlugin(options);
}

function InternalPlugin() {
}
InternalPlugin.prototype = new Alvine.jQuery.Plugin();
InternalPlugin.prototype.constructor = InternalPlugin;

In der Anleitung jQuery-Plugin erstellen wird ein vollständiges Beispiel beschrieben.

Zuweisen eines Plugins

Mit Hilfe der jQuery-Methode jQuery.fn.asignAlvineComponent(Example, settings) wird ein jQuery-Plugin einem DOM-Element zugewiesen. Dabei wird von der Methode für jedes zugewiesene Plugin folgende Struktur im DOM-Element angelegt:

Element
   ┣━━ Alvine      
   ┃     ┗━━ <PLUGIN> (vom Typ Extension)
   ┃             ┣━━ objectName            ⤑ Alvine.jQuery.Component
   ┃             ┣━━ settings              ⤑ Optionen (sollten über getSetting() geholt werden)
   ┃             ┣━━ getSetting()          ⤑ Methode um Optionen abzufragen
   ┃             ┣━━ element               ⤑ DOM-Node
   ┃             ┣━━ jQElement             ⤑ jQuery-Element-Collection
   ┃             ┗━━ plugin                ⤑ Plugins
   ┃                   ┣━━ getDefaults()   ⤑ Standardwerte der Optionen
   ┃                   ┣━━ reference       ⤑ Referenz mit jQuery-Collection
   ┃                   ┗━━ component       ⤑ Referenz auf das übergeordnete Componenten-Objekt 

Das eigentlich Plugin-Objekt ist über Element.Alvine.Example.plugin ansprechbar. Darüber können auch im Plugin definierte Methoden Element.Alvine.Example.plugin.doSomething() aufgerufen werden.

Optionen / Settings

Jedes von Alvine.jQuery.Plugin abgeleitete Plugin verfügt über die Methoe getDefaults(). Abgeleitete Plugins müssen diese Methode implementieren und Ihre eigenen Defaults zurückgeben.

Plugin.prototype.getDefaults = function() {
    return {
        key: 'value'
    };
}; 

Auf die Settings des Elements kann über die getSetting-Funktion zugegriffen werden. element ist hierbei jeweils ein DOM-Element.

element.Alvine.myPlugin.getSetting('key')
// -> value
element.Alvine.myPlugin.getSetting('label')
// -> my plugin
element.Alvine.myPlugin.getSetting('undefined')
// -> undefined

Statt im letzten Fall, wenn ein Wert nicht definiert wurde, auf undefined zu prüfen, kann man beim Aufruf der Funktion gleich einen Default-Wert übergeben. Dieser Default-Wert wird im Fall das es den gewünschten Schlüssel nicht gib, zurückgegeben.

Der letzte Aufruf würde mit Default-Parameter den Wert nicht vorhanden zurück geben.

element.Alvine.myPlugin.getSetting('undefined','nicht vorhanden')
// -> nicht vorhanden

Eine weitere Möglichkeit Werte zu definieren besteht in dem notieren von data- Attributen direkt im Element. In unserem Beispiel könnten wir direkt im HTML-Tag das Attribut data-myplugin-label definieren und den gewünschten Wert angeben.

<div id="my" data-myplugin-label="new label"></div>

Ein Aufruf der Settings würde in diesem Fall new label zurück geben.

element.Alvine.myPlugin.getSetting('label');
// -> new label

Die Reihenfolge der Auswertung ist dabei immer gleich. Zuerst wird geprüft, ob im Tag ein Wert definiert ist. Ist kein Wert vorhanden, wurde auch hier kein Wert gesetzt, so wird zum Schluß der Wert aus den Plugin Defaults herangezogen.

Hilfsobjekte

Zur Verwaltung der Plugins werden, wie auch oben in dem Diagramm ersichtlich ist, Hilfsobjekte vom Typ Component, Reference und Extension angelegt.

Component

Die Komponente bündelt die Referenzen auf das DOM-Element, auf die entsprechende jQuery-Collection und auf die Plugin-Daten. Außerdem stellt sie die Methode getSetting() zur Verfügung.

Reference

Die Referenz wird für den Zugriff des Plugins verwendet und stellt einen Zugriff auf das jQuery-Objekt bereit.

Extension

Das Extension-Objekt hat keine weiteren Funktionen und dient als Struktur-Element.