Verwendung

View this page in English: jQueryAdminUsage

jQueryAdmin erlaubt es Ihnen, aus den mitgelieferten oder einer wachsenden Liste bereits vorbereiteter Komponenten diejenigen zusammen zu stellen, die Sie für Ihre Webseite benötigen. Hierzu steht Ihnen ein komfortables Admin Tool zur Verfügung.

Außerdem installiert jQueryAdmin zwei Droplets, mit deren Hilfe Sie die so erzeugten Presets verwenden können, ohne daß Sie dafür das Template oder andere Dateien verändern müssen.

Das Konzept

jQueryAdmin ermöglicht es, eine beliebige Anzahl verschiedener Presets zu erstellen und in Ihre Seiten einzubinden. Ein Preset ist eine Kombination aus jQuery Plugins und/oder UI Komponenten, die benötigt werden, um einen bestimmten Effekt zu erreichen, einen Dialog zu öffnen, das Menü aufzupeppen, oder was auch immer.

Um ein Preset zu verwenden, muß dieses in die Seite eingebunden werden. Hier kommen die Droplets ins Spiel.

Es gibt zwei Droplets, die mit jQueryAdmin mitgeliefert werden und die Verwendung auf zwei unterschiedliche Arten erlauben:

  • Um Presets automagisch seitenbasiert zu verwenden, binden Sie das Droplet [[jQueryLoader]] in Ihren Footer ein. ("Fußzeile" im Backend.)
  • Um ein bestimmtes Preset (überall oder auf einer bestimmten Seite) einzubinden, verwenden Sie das Droplet [[jQueryInclude]].

Wenn Ihnen der Unterschied noch nicht ganz klar ist, lesen Sie bitte weiter, ich komme noch zu den Details. ;)

Das heißt, der einfachste Weg, jQueryAdmin mit all seiner Magie zu verwenden, ist der, beide Droplets in den Seitenfuß einzubinden.

Dies hat folgenden Effekt:

  • Auf allen Seiten wird das Preset default.jquery eingebunden.
  • Existiert zur aktuell angezeigten Seite ein spezielles Preset (siehe unten), wird dieses automatisch mit eingebunden.

Um nun das Plugin oder den Effekt zu verwenden, das/den Sie gerade einem Preset hinzugefügt haben, müssen Sie in den allermeisten Fällen ein bestimmtes Markup verwenden. Wie dieses aussieht, hängt vom jeweiligen Plugin oder Effekt ab. Das bedeutet, Sie müssen sich mit der Dokumentation der Komponente auseinander setzen, die Sie verwenden möchten.

Die meisten Plugins (es sollten alle sein, aber das kann ich nicht garantieren) bringen eine kleine Einführung und Links auf die Homepage des Autors mit. Klicken Sie auf das kleine Lampensymbol neben dem Plugin, um dieses Dokument aufzurufen.

Beispiel: Um den "Highlight" UI Effekt zu verwenden, müssen Sie id="highlight" einem <div> oder anderem Blockelement auf Ihrer Seite hinzufügen.

Quickstart - einfacher geht's nicht

Komponenten zur Verwendung in allen Seiten zusammenstellen

Diese Variante ist die passende, wenn Sie aus den vorhandenen Komponenten eine Konfiguration zusammenstellen wollen, die für alle - oder doch die meisten - Seiten Ihres Webauftritts gelten soll.

  1. Rufen Sie in Ihrem WebsiteBaker Backend unter [Admin Tools] -> [jQueryAdmin] auf
  2. Auf der linken Seite finden Sie unter der Überschrift "Presets" - "jQueryAdmin Verzeichnis" die Liste der vorhandenen Presets. Klicken Sie auf das Bearbeiten-Symbol neben dem Eintrag default.jquery
  3. Stellen Sie die gewünschten Komponenten zusammen, indem Sie sie in der Liste markieren, und klicken Sie auf [Speichern]
  4. Binden Sie das Droplet [[jQueryInclude]] (ohne Parameter) in den Seitenfuß ein (WB Backend -> Optionen -> Fußzeile)

Sie können die ausgewählten Komponenten nun in Ihren Seiten verwenden, ohne sich darum kümmern zu müssen, wie diese geladen werden müssen. Beachten Sie die Dokumentation der einzelnen Komponenten, um herauszufinden, was Sie tun müssen, um das Plugin oder den Effekt zu verwenden. (siehe oben)

Komponenten für die Verwendung in einer bestimmten Seite zusammenstellen

Diese Variante ermöglicht es Ihnen, ohne großen Aufwand jQuery Komponenten und Plugins zusammen zu stellen, die nur auf einer ganz bestimmten Seite Ihres Webauftritts geladen werden sollen.

  1. Rufen Sie in Ihrem WebsiteBaker Backend unter [Admin Tools] -> [jQueryAdmin] auf; Sie erhalten automatisch ein Formular zur Erzeugung eines neuen Presets
  2. Geben Sie als Namen die ID der Seite an, in die das Preset eingebunden werden soll, z. B. 19; Sie finden diese ID unter [Seiten] in der Spalte mit der Überschrift "ID:"
  3. ab v2.1: Klicken Sie auf das kleine Icon neben dem Eingabefeld für den Presetnamen. Sie erhalten einen Dialog, aus dem Sie die Seite auswählen können, für die Sie das Preset zusammenstellen möchten. Die ID dieser Seite wird dann automatisch in das Eingabefeld übernommen.
  4. Stellen Sie die gewünschten Komponenten zusammen, und klicken Sie auf [Speichern]
  5. Binden Sie das Droplet [[jQueryLoader]] (ohne Parameter) in den Seitenfuß ein (WB Backend -> Optionen -> Fußzeile)

Wenn Sie nun die entsprechende Seite aufrufen, wird das so erzeugte Preset geladen; auf allen anderen Seiten dagegen nicht!

Selbstverständlich können Sie die beiden obigen Varianten auch kombinieren!

Ein bestimmtes Preset einbinden

Neben der Änderung der mitgelieferten default.jquery Vorlage (siehe oben), können Sie natürlich beliebige weitere Presets anlegen und verwenden. Gehen Sie dabei vor, wie oben unter Komponenten für die Verwendung in einer bestimmten Seite zusammenstellen beschrieben, und speichern Sie das Preset unter einem beliebigen Namen. Wobei "beliebig" heißt, daß Sie möglichst keine Zahl und natürlich keine "komischen Zeichen" verwenden sollten. ;o) Bei einer Zahl würde das Droplet "denken", es sei eine Seitennummer, und bei "komischen Zeichen" kann es zu Problemen beim Speichern des Presets oder beim späteren Einbinden desselben kommen.

Anschließend binden Sie es auf der entsprechenden Seite ein, indem Sie das Droplet jQueryInclude verwenden. Den Aufruf schreiben Sie einfach in eine WYSIWYG-Sektion auf der gewünschten Seite.

    [[jQueryInclude?preset=<Presetname>]]

<Presetname> ersetzen Sie hierbei durch den Namen, den Sie vergeben haben. (Inklusive der <>!)

Beispiel: Wenn sie ein Preset mit dem Namen "meinPreset" angelegt haben, binden Sie es folgendermaßen ein:

    [[jQueryInclude?preset=meinPreset]]

Achten Sie auf die korrekte Schreibweise! (Groß-/Kleinschreibung!)

Ein bestimmtes jQuery Plugin einbinden, ohne ein Preset erstellen zu müssen

Wenn Sie z. B. ein Plugin mal eben ausprobieren möchten, ist es sehr lästig, wenn man dafür erst ein Preset erstellen muß. Daher bietet das jQueryInclude Droplet die Möglichkeit, das Plugin direkt einzubinden.

    [[jQueryInclude?plugin=<Pluginname>]]

<Pluginname> ist dabei der Name des Verzeichnisses unterhalb von ./modules/jqueryadmin/plugins. Achten Sie dabei genau auf die Schreibweise (Groß-/Kleinschreibung, Striche, Punkte, ...)! Wenn das Verzeichnis also etwa "cluetip-1.0.6" heißt, müssen sie

    [[jQueryInclude?plugin=cluetip-1.0.6]]

schreiben, nicht etwa

    [[jQueryInclude?plugin=cluetip]] *falsch*

oder

    [[jQueryInclude?plugin=ClueTip-1.0.6]] *falsch*

oder irgendetwas anderes.

Fortgeschrittene Optionen

jQueryAdmin Presets und Templates (jQueryAdmin für Template-Designer)

Die jQueryAdmin Droplets suchen automatisch nach einer Datei default.preset im Verzeichnis des aktuell benutzten Templates. Sie können diese Datei ebenfalls über das Admin Tool bearbeiten.

Wenn Sie Template-Designer sind und Ihr Template mit jQuery-Komponenten "aufhübschen" wollen, kann dies der Weg Ihrer Wahl sein. :)

jQueryAdmin Presets und Module (jQueryAdmin für Modulentwickler)

Sie können jQueryAdmin Presets auch in einem Modulverzeichnis hinterlegen. (Oder, anders ausgedrückt, ein Modulentwickler kann ein solches Preset mitliefern.) Um dieses zu verwenden, müssen zwei Bedingungen erfüllt sein:

  1. Das Preset muß im Modulverzeichnis im Unterverzeichnis /presets oder /jquery/presets hinterlegt sein
  2. Der Name des Moduls (genauer, des Modulverzeichnisses) muß dem jQueryInclude Droplet mitgeteilt werden.
    [[jQueryInclude?preset=<Presetname>&module=<Modulverzeichnis>]]

Der Parameter preset kann auch weggelassen werden, sofern das Preset den Dateinamen default.jquery hat.

    [[jQueryInclude?module=<Modulverzeichnis>]]

Position in der Seite bestimmen

jQuery Komponenten müssen manchmal im Seitenkopf (<head>), manchmal aber auch am Ende der Seite (vor </body>) eingebunden werden. Die jQueryAdmin Droplets gehen standardmäßig davon aus, daß die Einbindung im Seitenkopf erfolgt. Dies kann man jedoch ändern.

Position in der Vorlage eines Plugins festlegen

Jedes Plugin muß eine Datei default.preset mitbringen, in der hinterlegt ist, welche JavaScript- und ggfs. CSS-Dateien geladen werden sollen. (Siehe auch Plugins einbinden)

In dieser Datei kann per HTML-Kommentar festgelegt werden, daß bestimmte Teile statt dessen in den Seitenfuß geladen werden sollen. Hierzu verwendet man folgenden Kommentar:

    <!-- position: body -->

Alles, was nach dieser Zeile aufgeführt ist, wird in den Seitenfuß geladen. Alles, was vor dieser Zeile aufgeführt ist, wird dagegen in den Seitenkopf geladen.

Um die Angabe wieder zurück zu setzen, kann das Markup

    <!-- position: head -->

verwendet werden. (Üblicherweise schreibt man aber einfach alles, was in den Header soll, vor die body-Angabe.)

Beispiel:

<script src="{WB_URL}/modules/jqueryadmin/jquery-core/jquery-core.min.js" type="text/javascript" charset="utf-8"></script>
<link rel="stylesheet" href="{WB_URL}/modules/jqueryadmin/plugins/prettyPhoto-2.5.6/css/prettyPhoto.css" type="text/css" media="screen" charset="utf-8" />
<script src="{WB_URL}/modules/jqueryadmin/plugins/prettyPhoto-2.5.6/js/jquery.prettyPhoto.js" type="text/javascript" charset="utf-8"></script>
<!-- position: body -->
<script type="text/javascript" charset="utf-8">
    $(document).ready(function(){
        $("a[rel^='prettyPhoto']").prettyPhoto();
    });
</script>

Position im Droplet festlegen

Auch im Droplet selbst kann man festlegen, wo die Inhalte des Presets hingehören. Dazu fügt man dem Aufruf den Parameter position=body hinzu. Beispiel:

    [[jQueryInclude?position=body]]

Da aber normalerweise in den Komponenten selbst schon festgelegt ist, was wo hin gehört, ist diese Angabe normalerweise überflüssig. Sie ist nur der Vollständigkeit halber enthalten.