Plugins

Über von AbstractPlugin abgeleitete Plugins kann die Funktionalität einer Seite erweitert werden. Ein Plugin ist im wesentlichen ein Container für eine Zeichenkette. Die Zeichenkette wird über die Plugin::getInstance()-Methode erstellt und abgelegt.

AuthenticationLogout

Das Plugin \Alvine\Application\Web\Presenter\Page\Plugin\Authentication\Logout rendert einen Logout-Button mit dem Ziel aus der angegebenen Route.

Die Konfiguration erfolgt über das folgende XML-Fragment.

<plugin class="\Alvine\Application\Web\Presenter\Page\Plugin\Authentication\Logout">
    <redirect route="HOME" label="abmelden"/>
</plugin>

Wird keine Route angegeben, so wird nichts gerendert. Das Label ist optional und wird im Standard auf den Wert i18n{logout} gesetzt.

Der Button sendet über den Parameter X_HTTP_METHOD_OVERRIDE den Wert POST. Die Zielroute muss die POST-Methode implementiert haben.

HtmlContent

Das \Alvine\Application\Web\Presenter\Page\Plugin\Html\Content-Plugin erlaubt es HTML-Dateien aus einer Datei oder externen Quelle in die Seite zu integrieren. Dieses Plugin dient als Grundlage für weitere Plugins, die eine Dateiliste bereitstellen.

Abgeleitete Plugins müssen die Methode des Interface \Alvine\Application\Web\Presenter\Page\Plugin\Html\Filenames implementieren.

HtmlFragment

Das \Alvine\Application\Web\Presenter\Page\Plugin\Html\Fragment-Plugin erlaubt es ein HTML-Fragment zu rendern. Für das Template muss mindestens ein templates/template-Tag definiert werden. Das HTML-Template kann entweder direkt angegeben werden, oder über einen Pfad im include-Attribute definiert werden.

Informationen zur Template-Engine finden sich auch in der Dokumentation der HTML-Komponente.

Hinweis

Wird das Template im CML definiert, so muss der Inhalt in einem CDATA-Element eingefasst sein.

Es sind mehrere template-Tags erlaubt.

<plugin class="\Alvine\Application\Web\Presenter\Page\Plugin\Html\Fragment">
    <templates>
        <template><![CDATA[
        <h1>Template-Engine</h1>
    ]]></template>
    <template include="http://example.com/fragment.html" />
        <template><![CDATA[
        <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. 
           Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, 
           when an unknown printer took a galley of type and scrambled it to make a type specimen book.</p>
    ]]></template>
    </templates>
    <datasets />
</plugin>

Das Dateset wird über den datasets/dataset-Tag definiert. In dem folgenden Beispiel wird eine Tabelle mit Städten gerendert.

<plugin class="\Alvine\Application\Web\Presenter\Page\Plugin\Html\Fragment">
    <templates>
        <template><![CDATA[
        <h1>Städte</h1>
    ]]></template>
        <template><![CDATA[
        <table>
        <tr data-repeat="city dataset:list"> 
           <td data-replace="dataset:city | index:name">placeholder</td>   
           <td data-replace="dataset:city | index:einwohner">placeholder</td>   
        </tr>
        </table>
    ]]></template>
    </templates>
    <datasets>
        <dataset>
            <list>
                <name>München</name>
                <einwohner>1365015</einwohner>
            </list>
            <list>
                <name>Frankfurt</name>
                <einwohner>691520</einwohner>
            </list>
        </dataset>
    </datasets>
</plugin>

Das Ergebnis ist das folgende HTML-Fragment

<h1>Städte</h1>
<table>
    <tbody>
        <tr> 
           <td>München</td>   
           <td>1365015</td>   
        </tr><tr> 
           <td>Frankfurt</td>   
           <td>691520</td>   
        </tr>
    </tbody>
</table>     

Die Daten für das Dataset können auch über eine externe Quelle kommen. Hierzu muss über das include-Attribute der Pfad angegeben werden. Wichtig ist der zu verwendende Mime-Type. Vom Plugin unterstützte Werte sind application/json und application/xml.

<datasets>
    <dataset include="http://example.com/data.json" type="application/json" >
    </dataset>
</datasets>

Für den Zugriff auf eine Liste ist ein Hauptschlüssel notwendig. Liegen die Daten in einer flachen Struktur vor, so kann über das Attribute listkey ein Schlüssel definiert werden.

Damit wird die flachen Struktur um eine Ebene ergänzt.

[
  {
    "country": "AD",
    "name": "Sant Julià de Lòria",
    "lat": "42.46372",
    "lng": "1.49129"
  },
  {
    "country": "AD",
    "name": "Pas de la Casa",
    "lat": "42.54277",
    "lng": "1.73361"
  },

Mit dem Attribute listkey="countries" wird daraus folgende Struktur:

{
  countries: [
    {
      "country": "AD",
      "name": "Sant Julià de Lòria",
      "lat": "42.46372",
      "lng": "1.49129"
    },
    {
      "country": "AD",
      "name": "Pas de la Casa",
      "lat": "42.54277",
      "lng": "1.73361"
    },

Definition des Plugins:

<plugin class="\Alvine\Application\Web\Presenter\Page\Plugin\Html\Fragment">
    <templates>
        <template><![CDATA[
        <h1>Städte</h1>
    ]]></template>
        <template><![CDATA[
        <table>
        <tr data-repeat="list dataset:countries"> 
           <td data-replace="dataset:list | index:name">placeholder</td>   
           <td data-replace="dataset:list | index:country">placeholder</td>   
        </tr>
        </table>
    ]]></template>
    </templates>
    <datasets>
        <dataset listkey="countries" 
                 type="application/json" 
                 include="https://raw.githubusercontent.com/lutangar/cities.json/master/cities.json" />
    </datasets>
</plugin>

Hinweis

Für dieses Plugin ist die alvine.markup.html Komponente erforderlich.

I18nPropertyText

Das Alvine\Application\Web\Presenter\Page\Plugin\I18n\PropertyText-Plugin stellt Schlüssel als Variable in Javascript zur Verfügung. In der Route kann das Plugin über folgende Struktur definiert werden:

<plugin class="\Alvine\Application\Web\Presenter\Page\Plugin\I18n\PropertyText">
  <locale include="/path/navigation.properties" variable="i18nLocale">
    key=Schlüssel
    value=Wert
    <de>
       key=Schlüssel
       value=Wert
    </de>
    <de-CH>
       key=Schlüssel
       value=Wert
    </de-CH>
    <de-DE>
       key=Schlüssel
       value=Wert
    </de-DE>
    <en>
       key=key
       value=value
    </en>
  </locale>
</plugin>

Über das include-Attribute kann eine externe Eigenschaftsdatei eingebunden werden. Über variable wird der Name der Javascript-Variable definiert. Das Ergebnis hängt von der im Header übergebenen Localen ab und ist im wesentlichen folgender Javascript Code.

<script>;try{$('body').alvineI18nLocale('setLocaleStringDefaults', {key:"Schlüssel",value:"Wert"});} catch (e) {};</script>

Hinweis

Für dieses Plugin wird das entsprechende jQuery-Plugin benötigt.

NavigationTree

Das Alvine\Application\Web\Presenter\Page\Plugin\Navigation\Tree-Plugin erstellt aus der Definition einen Navigationsbaum.

Die Navigation kann entweder direkt in der Route

<plugin class="\Alvine\Application\Web\Presenter\Page\Plugin\Navigation\Tree">
    <navigation>
        group.headline=Main
        group.url=/a/a
        group.label=A1
        group.1.headline=Sub
        group.1.url=/a/a
        group.1.label=A11
        group.2.url=/a/b
        group.2.label=A12
        group.3.url=/a/a
        group.3.label=A13
        group.4.url=/a/b
        group.4.label=A14
    </navigation>
</plugin>

oder über eine Property-Datei definiert werden.

<plugin class="\Alvine\Application\Web\Presenter\Page\Plugin\Navigation\Tree">
    <navigation include="/var/alvine/nav.properties" />
</plugin>

Über das Attribute ui-class kann die zu verwendende UI-Klasse definiert werden. Wurde der Tag nicht angegeben erfolgt das Rendering über die Klasse \Alvine\UI\Widget\Navigation\Tree.

UIElement

Über das \Alvine\Application\Web\Presenter\Page\Plugin\UI\Element-Plugin lassen sich HTML-Tags direkt integrieren. Über dieses Plugin können die Tags ohne CDATA definiert werden. Verfügbare Typen sind: Anchor, Blockquote , Button , ButtonGroup, H1-H6, Image, Input, InputGroup, Paragraph und Text.

<plugin class="\Alvine\Application\Web\Presenter\Page\Plugin\UI\Element">
    <h1>Headline</h1>
    <paragraph>Lorem Ipsum is simply dummy text of the printing and typesetting industry.</paragraph>
    <anchor href="http://alvine.io">alvine.io</anchor>
</plugin>

Hinweis

Dieses Plugin ist nicht für komplexe HTML-Dokumente gedacht, sondern für den Fall, das man eine Überschrift, einen Link oder ein Bild ins Template einfügen will.

UIForm

Das \Alvine\Application\Web\Presenter\Page\Plugin\UI\Form-Plugin erlauibt es ein HTML-Formular zu rendern. Das Ziel des Formulars wird über das Route-Attribute im Form-Tag definiert route="MY-ROUTE-ID".

<plugin class="\Alvine\Application\Web\Presenter\Page\Plugin\UI\Form">
    <form method="post" accept-charset="utf-8" route="MY-ROUTE-ID" enctype="application/x-www-form-urlencoded">
        <inputgroup name="name" label="Name" value="Mustermann" />
        <inputgroup name="surname" label="Vorname" value="Hans" />
        <inputgroup name="job" label="Beruf" value="" />
        <buttongroup type="submit" name="submit">absenden</buttongroup>
    </form>
</plugin>