Plugins für jQuery – Grundlagen

Zunächst gilt es, eine Grundlage für das Plugin zu schaffen. Plugins sind Methoden, die das Objekt jQuery.fn erweitern. Dazu gibt es mehrere Möglichkeiten. Eine davon ist, dass man dem Objekt direkt eine anonyme Methode zuweist.

1: jQuery.fn.meinPlugin = function() { alert(„Steve Holt!“)};

In diesem Artikel wird jQuery.fn.extend verwendet, diese Methode erweitert das „fn“-Objekt um alle Methoden, die das Parameter Objekt enthält.

1: var paramObj = {
2:    meinPlugin: function() {alert(„Steve Holt!“);}
3: };
4: jQuery.fn.extend(paramObj);

Die Verwendung dieser Methode ist besonders dann sehr effizient, wenn man mehrere Plugins in einem Rutsch zuweisen will.

In beiden Beispielen ist das Plugin anschließend über

jQuery(“#beispiel“).meinPlugin();

ansprechbar.

Der nachfolgende Codeblock kann – abgesehen vom Plugin-Namen – als generelles Muster für jQuery- Plugins angesehen werden:

1: (function($){
2: 	$.fn.extend({
3: 	    virtualPages:function(params){
4: 	        var conf = {};
5:		  $.extend(conf, params);
6:		  return $(this).each(function(){
7:                // Die eigentliche Funktionalität
8:             });
9:	    }
10:	});
11: })(jQuery);

Die Zeilen 1 und 11 geben einen Rahmen vor, in dem man sicher sein kann, dass selbst wenn jemand den Kompatibilitätsmodus verwendet, der Zugriff auf das jQuery-Objekt über das Alias „$“ möglich ist. Dies gilt nur innerhalb des Rahmens, das Programmierkonzept dahinter heißt Closure.

In den Zeilen 2 und 10 wird jQuery.fn.extend benutzt um das jQuery-Objekt um die Methoden die das übergebene Objekt enthält, zu erweitern.

Die Zeilen 3 bis 9 enthalten die anonyme Funktion, die das eigentliche Plugin darstellt. Die Methodensignatur enthält einen Parameter, der aber per Sprachdefinition optional ist.

In den Zeilen 6 bis 8 wird für jedes Element der aktuellen Auswahl nun Code ausgeführt, der den eigentlichen Plugin darstellt.

Jeder längere Text enthält in der Regel Absätze. Diese Tatsache kann man nutzen, um den Text in mehrere Blöcke zu teilen, die nacheinander angezeigt werden, damit der User nicht weit scrollen muss.

Als Algorithmus sieht das in etwa wie folgt aus:

Für jeden Absatz: Prüfe, ob die aktuelle Seite genug Platz dafür hat. Wenn ja: Füge den Absatz in die Seite ein. Wenn nein: Erstelle eine neue Seite und füge den Text dort ein. Solange wiederholen, bis alle Absätze einer virtuellen Seite zugewiesen sind.

Für dieses Beispiel gehe ich von folgender Situation aus: Der Text steckt in einem Rahmen (<div>) und jeder Absatz ist ein Paragraph, d.h. der Text wird umrahmt von <p>-Elementen.

<div id=“text“>
  <p>erster Absatz […]</p>
  <p>zweiter Absatz […]</p>
</div>

Das Plugin soll auf den Text angewandt werden.

$(function(){
    $(“#text“).virtualPages();
});

Dabei sollen jeweils so viele Paragraphen in ein <div>-Element eingefügt werden, dass diese einen vorher festgelegten Rahmen nicht überschreiten.

Die virtuellen Seiten werden im Plugin selbst durch die Variable page vertreten. Die Variable page zeigt auf die virtuelle Seite, die zuletzt erstellt worden ist. Zusätzlich zur Variable page gibt es noch visPage, dies ist der Verweis auf die aktuell sichtbare Seite.

Zunächst werden alle Kinder des Elements, das bearbeitet werden soll, gesucht. Dies wird durch

$(this).children()

ausgeführt. Auf diesen Elementen kann erneut eine for each-Schleife ausgeführt werden, welche jQuery durch die Methode each und die Übergabe einer Callback-Methode realisiert. Der Vorteil dieser Vorgehensweise ist, dass man den Objektkontext this für den Zugriff auf das aktuelle Element der Schleife nutzen kann.

1:$(this).children().each(function(){
2:    if (!page || ($(this).height() + page.height() > conf.height))
3:        createPage();
4:    page.append(this);
5:});

In der each Callback-Methode wird zunächst geprüft, ob es überhaupt eine Seite gibt (Zeile 2). Wenn es eine Seite gibt, wird geprüft, ob die Höhe der Seite plus der Höhe des aktuellen Kind-Elements die maximal zulässige Höhe überschreiten. Wenn dies der Fall ist, wird eine neue Seite erstellt.

In der letzten Zeile der Callback-Methode wird das aktuelle Kind-Element der aktuellen Seite hinzugefügt.

Dieses Beispiel zeigt zwei externe Referenzen. Die Variable page muss im darüber liegenden Kontext (also innerhalb des Plugin-Rumpfs und vor dem $(this).children().each() Aufruf) definiert werden. Die Methode createPage muss dafür sorgen, dass im selben Kontext ein Seitenelement erzeugt wird.

1: function createPage(){
2:    var elem = $('<div></div<').addClass(conf.pageClass)
3:        .data('pageNr',++pageNum);
4:    if (typeof(page) == 'undefined') {
5:	  visPage = elem.prependTo($this).show();
6:    } else elem.insertAfter(page).hide();
7:    page = elem;
8:}

In Zeile 2 der Methode createPage wird das Seitenelement erstellt. In Zeile 3 wird der laufende Index der Seite im Datenattribut „pageNr“ gespeichert. In Zeile 4 wird geprüft, ob es bereits ein Seitenelement gibt. Falls nicht, wird das gerade erstellte Element in Zeile 5 durch die Zuweisung zur Variable visPage zur ersten sichtbaren Seite hinzugefügt, nachdem es dem Element hinzugefügt wurde, das durch das Plugin verarbeitet wird. Falls es bereits ein Seitenelement gibt, wird das Element in Zeile 6 hinter die letzte Seite angehängt. In Zeile 7 wird schließlich das neu erstellte Element durch Zuweisung zur Variable page als aktuelle Seite gekennzeichnet.

$.fn.extend({
    myPlugin: function(){
        var $this = $(this), page, visPage, pages = [];
    }
});

Die Variable $this ist keine jQuery-Besonderheit, sondern wird im Plugin-Kontext für den Schnellzugriff definiert. Dies erspart unnötige Suchen und man kann es in allen Funktionen benutzen, die innerhalb des Plugins erstellt werden.

Das Plugin hat nun alles, was es benötigt, um die gefundenen Elemente in mehrere virtuelle Seiten einzuteilen. Lediglich der Zugriff auf die Seiten fehlt noch. Dafür muss eine Navigation erstellt werden. Der Einfachheit halber soll für jede virtuelle Seite ein Link generiert werden, der die entsprechende virtuelle Seite öffnet.

01: function createPageLinks(){
02:	if (pages.length < 2) return;
03:	var box = $('<div class="virtual_pages_links"></div>');
04:	$(pages).each(function(){
05:	    	var elem = $(this);
06:		var text = conf.linkText.replace('%', elem.data("pageNr"));
07:		$('<a>' + text + '</a>')
08:			.attr('href', document.location.href).click(function(e){
09:			if (elem.is(':hidden')){
10:				visPage.slideUp();
11:				visPage = elem.slideDown();
12:			}
13:			e.preventDefault(); // Link soll nicht geöffnet werden
14:		}).appendTo(box).after(' ');
15:	});
16:	return box;
17:}

Diese Methode generiert Seitenlinks. Zunächst wird geprüft, ob mehr als eine Seite vorhanden ist. Sollte nur eine Seite vorhanden sein, wird angenommen, dass diese bereits sichtbar ist und die Links nicht generiert werden müssen. In den Zeilen 4 bis 15 wird für jedes Seitenelement ein Link erstellt und direkt mit einem Event Handler für den Event Click versehen. Der Index jedes Elements ist im Datenattribut pageNr gespeichert und wird dort abgerufen, um den Text des Links zu bilden. Als Text wird der Konfigurationswert linkText benutzt, wobei hier das Prozentzeichen als Platzhalter für die Seitenzahl verwendet wird. In Zeile 9 wird geprüft, ob die zu dem Link zugehörige Seite unsichtbar ist. Nur in diesem Fall wird dann veranlasst, dass die aktuell sichtbare Seite versteckt und die dem Link zugehörige Seite angezeigt wird. In derselben Zeile wird die nun „geöffnete“ Seite als sichtbare Seite zwischengespeichert.

Der Aufruf der Methode preventDefault auf dem Event Objekt sorgt dafür, dass der vorher erstellte Link nicht aktiviert wird.

Wenn man an diesem Punkt angekommen ist, ist das Plugin fertig und kann noch beliebig erweitert werden. Denkbar wäre es beispielsweise, die Methode zum Generieren der Links austauschbar zu machen oder aber mit mehr Konfigurationsmöglichkeiten flexibler zu gestalten.

Basierend auf dem Code aus dem vierten Code-Beispiel können beliebig Plugins erstellt werden. Das Beispiel stellt dabei den kleinsten gemeinsamen Nenner dar.

Andreas Vdovkin ist Software-Entwickler und Autor des bei O’Reilly erschienenen „jQuery – kurz & gut“. Darin vermittelt er dem Leser zu Beginn die notwendigen Grundlagen von JavaScript, dem W3C-Dokumentenmodell und die grundlegende Arbeitsweise mit jQuery. „Suchen“ und „Ändern“ stellen die Kernkapitel der Befehlsreferenz dar und beschreiben die Navigation und Manipulation von DOM-Elementen.

Wer noch mehr über jQuery erfahren möchte, kann eines von drei Ausgaben von „jQuery kurz & gut“ gewinnen. Hinterlasst dazu einfach hier einen Kommentar. Wir verlosen am Mittwoch, 14. April, 12 Uhr unter allen Kommentaren. Da wir die Gewinner per E-Mail informieren, gebt unbedingt eine korrekte Adresse an. Viel Glück!