Tutorial: Ein eigenes Layout in WebRex

Inhaltsverzeichnis

Einleitung

Um ein eigenes Layout für WebRex zu entwickeln, gibt es einige Regeln, an welche man sich halten muss, damit das Layout in das WebRex-System integriert werden kann.

  1. Ein Layout muss über eine main.html verfügen.
  2. Ein Layout muss über eine style.css verfügen.
  3. Ein Layout muss über eine layoutDatas.xml verfügen.
  4. Ein Layout muss über ein Verzeichnis namens templates verfügen, in welchem die Templates abgelegt werden.
  5. Ein Layoutname muss in WebRex individuell sein.
  6. Ein Layout darf nie über zwei oder mehrere Templates mit dem selben Namen oder dem selben Dateinamen verfügen.
  7. Ein Template darf nie über zwei oder mehrere Container mit den selben Namen oder dem selben name-Attribut-Wert verfügen.
  8. Ein Layout muss mindestens über ein Template verfügen.
  9. Ein Template muss mindestens über einen Container verfügen.

Werden diese 9 Regeln befolgt und wird der XML-Code der layoutDatas.xml korrekt geschrieben, wird die Installtion des eigenen Layouts nicht fehlschlagen. Sollte eine dieser Regeln gebrochen werden, dann wird euch WebRex darauf auch aufmerksam machen und aus Sicherheitsgründen die Installation abbrechen.

Was benötige ich?

Diese Frage sollte man sich vor dem entwickeln eines Layouts gründlich überlegen - ein ausgereiftes Layout muss nämlich so gut wie nie angepasst werden bzw. maximal die style.css (-> bei (kleinen) Design-Änderungen).

In WebRex sollte jedes Template sämtlich Container einer möglichen Website zur Verfügung stellen. Wenn von Container die Rede ist, werden HTML-Element gemeint, wie bspw. <div>'s, <header>'s, <article>'s, <section>'s, <footer>'s, <nav>'s.
Für einen Container kann im Prinzip jedes existierende HTML-Element verwendet werden (sofern Sie sich nicht selbst schließen). Innerhalb von Containern muss ein sogenanntes (selbstschließendes) TagLib-Element existieren - dieses verfügt lediglich über ein Attribut: name. TagLibs gehören zum Kern des Adventure PHP Frameworks, auf welchem WebRex aufbaut.
Den jenigen, die mehr über TagLibs erfahren wollen, ist folgendes Tutorial zu empfehlen: APF - TagLibs erstellen

In diesem Tutorial erstellen wir ein Layout mit 3 verschiedenen Templates. Die Templates sollen dabei folgend aufgebaut sein:

Hier noch 3 Skizzen wie die Templates aufgebaut sein sollen:

Template Nr. 1:
Template Nr. 1 		Template Nr. 2:
Template Nr. 2 		Template Nr. 3:
Template Nr. 3

Datei- & Verzeichnisstruktur

Jetzt, wo wir beschlossen haben, welche Templates wir benötigen, können wir die Datei- & Verzeichnisstruktur unseres Layouts festlegen.

Bei der Benennung der Datein muss man sich an die ersten 4 Regeln halten, die am Anfang des Tutorials vorgestellten wurden. Lediglich den Dateinamen der einzelenen Templates kann man selbst entscheiden.

Die Templates

In diesem Kapitel werden wir den Code der drei Templates festlegen. Gestartet wird mit simple.html:

<core:addtaglib namespace="webrex::core::taglib" prefix="webrex" class="container" />
<div id="header">
    <webrex:container name="header" />
</div>
<div id="menu-top">
    <webrex:container name="menuTop" />
</div>
<div id="content">
    <webrex:container name="content" />
</div>
<div id="footer">
    <webrex:container name="footer" />
</footer>

In der ersten Codezeile findet Ihr ein APF-TagLib-Element - dieses stellt dem Template die WebRex-Container-TagLib zur Verfügung, welche die von einer Seite definierten Module läd. Das WebRex-Container-Taglib-Element findet Ihr in jedem HTML-Element-Container wieder. Dieses TagLib-Element verfügt nur über das name-Attribut, dessen Wert Ihr selbst bestimmen könnt - achtet aber darauf, diesen Wert in englisch und CamelCase-Schreibweise zu verfassen.


Nun fahren wir mit dem 2. Template fort, der sidebar_right.html:

<core:addtaglib namespace="webrex::core::taglib" prefix="webrex" class="container" />
<div id="header">
    <webrex:container name="header" />
</div>
<div id="menu-top">
    <webrex:container name="menuTop" />
</div>
<div id="content-left">
    <webrex:container name="contentLeft" />
</div>
<div id="sidebar-right">
    <webrex:container name="sidebarRight" />
</div>
<div id="footer">
    <webrex:container name="footer" />
</footer>

In diesem Template ändert sich vom Code her wenig. Das id-Attribut vom Content-Div erhält content-left anstatt content. nach dem content-left-Div wurde noch ein weitere Div mit der id sidebar-right eingefügt.


Und nun schließlich das 3. und somit letzte Template unseres Layouts - complex.html:

<core:addtaglib namespace="webrex::core::taglib" prefix="webrex" class="container" />
<div id="header">
    <webrex:container name="header" />
</div>
<div id="menu-top">
    <webrex:container name="menuTop" />
</div>
<div id="content">
    <webrex:container name="content" />
</div>
<div id="left-col">
    <webrex:container name="leftCol" />
</div>
<div id="right-col">
    <webrex:container name="rightCol" />
</div>
<div id="footer">
    <webrex:container name="footer" />
</footer>

main.html

Jetzt, wo wir mit allen Templates fertig sind, können wir mit der main.html fortfahren:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    <core:addtaglib namespace="webrex::core::taglib" prefix="webrex" class="website" />
    <head>
        <webrex:website section="head" />   
    </head>
    <body>
       <div id="wrapper">
           <webrex:website section="body" /> 
       </div>
    </body>
</html>

Jedes Layout kann immer nur über eine main.html-Datei verfügen - diese ist eine Art Bootstrap-Datei für ein Layout. Diese benötigt, wie man sehen kann, nicht wirklich viel Code. Ziemlich am Anfang wird wieder mittels APF-TagLib eine WebRex-TagLib eingebunden. Mit <webrex:website section="body" /> wird später das Template eingebunden, welches die aktuelle Seite für sich gewählt hat. Sprich, befinde ich mich auf der Seite "Home" und habe ich für diese Seite über das Admin Control Panel das Template complex.html ausgewählt, dann erscheint dieses Template anstatt dem <webrex:website section="body" />-Tag. Im header der main.html deklarieren wir den selben Tag, nur übergeben wir beim section-Attribut head. Dies veranlasst WebRex beim Aufbau der Website Meta-Informationen (Titel, Description, Keywords, Meta-Robots, Http-Equiv), die style.css, functions.js sowie weitere Datein (welche z.B. von Modulen benötigt werden) einzubinden.
In der main.html befindet sich lediglich ein div mit der id wrapper. Da sich der <webrex:website section="body" />-Tag innerhalb dieses Elementes befindet, wird dieser Div jeglichen im Browserfenster sichtbaren Inhalt umschließen.

Spätestens jetzt sollte man die Flexibilität des CMS bemerkt haben: für jede Seite lässt sich ein Layout auswählen und von diesem Layout wiederum ein Template. Eine Seite kann (über das Admin Control Panel) jeden Container des ausgewählten Template mit beliebig vielen Modulen in beliebiger Reihenfolge füllen.

style.css

* {
    margin: 0;
    padding: 0;
}

body {
    font-family: Arial;
}

#wrapper {
    width: 950px;
    margin: 0 auto;
}

#header {
    width: 950px;
    height: 100px;
    background: red;
}

#menu-top {
    background: blue;
}

#menu-top ul li {
    float: left;
    list-style: none;
}

#menu-top ul li a {
    padding: 5px 15px;
    display: block;
    color: #fff;
}

#content {
    padding: 15px;
    width: auto;
}

#content-left {
    width: 700px;
    padding: 15px;
    float: left;
}

#sidebar-right {
    width: 200px;
    float: right;
}

#left-col {
    width: 400px;
    float: left;
    padding: 15px;
}

#right-col {
    width: 400px;
    float: right;
    padding: 15px;
}

#footer {
    clear: both;
    height: 30px;
    width: 950px;
    background: green;
}

Wie im CSS-Code ersichtlich, definiere ich, wie eine ungeordnete Liste (<ul>), deren Listelemente (<li>) und Anchor-Elemente (<a>) im menu-top-Div auszusehen haben. Wieso? Na weil man annehmen kann, dass in einem Menu-Container ein Menu-Modul einfügt wird. Das Menu-Modul, welches von WebRex standardmäßig mitgeliefert wird, generiert ein Menu in folgender, semantischer Struktur:

<ul>
    <li><a href="URL-der-Seite" title="Seitenname">Seitenname</a></li>
    <li><a href="URL-der-Seite" title="Seitenname">Seitenname</a></li>
    <li><a href="URL-der-Seite" title="Seitenname">Seitenname</a></li>
</ul>

layoutDatas.xml

Nun bin ich bei der letzten und wohl wichtigsten Layout-Datei angelangt, der layoutDatas.xml. Diese Datei schildert dem WebRex-CMS, wie das Layout aufgebaut ist. In dieser Datei werden sämtliche Templates und Container definiert. Anhand der Datein in diesem Tutorial muss die layoutDatas.xml folgendermaßen aufgebaut sein:

<?xml version="1.0" encoding="UTF-8"?>
<layout>
    <name>My Layout</name>
    <author>Nicolas Pecher<author>
    <templates>
        <template>
            <name>Simple</name>
            <file>simple</file>
            <description>Ein einfaches Template, welches einen header-, einen menu- und einen footer-Container bereit stellt.
            </description>
            <containers>
                <container name="header">Header</container>
                <container name="menuTop">Menü</container>
                <container name="content">Inhalt</container>
                <container name="footer">Footer</container>
            </containers>
        </template>
        <template>
            <name>Sidebar Rechts</name>
            <file>sidebar_right</file>
            <description>Beinhaltet die gleichen Container wie das Simple-Template, nur
            besitzt es rechts, neben dem Content-Bereich eine Sidebar</description>
            <containers>
                <container name="header">Header</container>
                <container name="menuTop">Menü</container>
                <container name="contentLeft">Inhalt (links)</container>
                <container name="sidebarRight">Sidebar (rechts)</container>
                <container name="footer">Footer</container>
            </containers>
        </template>
        <template>
            <name>Komplex</name>
            <file>complex</file>
            <description>
                Komplex beinhaltet die gleichen Container wie das Simple-Template, nur existieren in diesem Template 3 Content Bereiche. Der Erste streckt sich über die gesamte Bereit, unter diesem befinden sich die beiden andern,
                welche sich die Breite der Website teilen.
            </description>
            <containers>
                <container name="header">Header</container>
                <container name="menuTop">Menü</container>
                <container name="content">Hauptinhalt (volle Breite)</container>
                <container name="leftCol">Linke Spalte</container>
                <container name="rightCol">Rechte Spalte</container>
                <container name="footer">Footer</container>
            </containers>
        </template>
    </templates>
</layout>

Die layoutDatas.xml muss innerhalb des templates-Elementes alle Templates definieren. Ein Template wird mit dem <template>-Tag eingeleitet. Jedes Template verfügt über ein name-Element (beinhaltet den Namen vom Template), über ein description-Element (Beschreibung vom Template - Achtung: max. 300 Zeichen), über ein file-Element (der Dateiname vom Template - Achtung: ohne Dateiendung (=.html)) und über ein containers-Element. Im containers-Element müssen die im Template deklarierten Container definiert werden. Dafür gibt es das container-Element, welches als einziges Element über ein Attribut verfügt: name. Der Inhalt vom name-Attribut muss der selbe sein, wie der Inhalt des name-Attributes des <webrex:container />-TagLib-Elementes. Beispiel:
Deklariere ich in einem Template folgenden Container...

<webrex:container name="header" />

...dann muss dieser Container in der layoutDatas.xml folgendermaßen definiert werden:

<container name="header">Der header-Container</container>

Der Inhalt, der zwischen <container> und </container> steht kann dabei frei gewählt werden. Er sollte aber natürlich möglichst gut den Container beschreiben.

Um den Aufbau der xml-Datei noch einmal besser zu beschreiben, habe ich einen Element-Baum anhand der XML-Datei erstellt. Dieser soll verdeutlichen, wie unser Layout aufgebaut ist:

Layout-Tree

Die meiste Arbeit ist nun getan. Jetzt geht Ihr in das Verzeichnis, wo eure Layout-Dateien angelegt sind, wählt Sie alle aus und verpackt sie zu einer ZIP-Datei.

pack to zip

Anschließend loggt Ihr euch in eurem WebRex-Admin Control Panel ein, klickt auf Layouts >> Neues Layout installieren und durchsucht euren Desktop nach der Layout-ZIP-Datei. Nach einem Klick auf den "Installieren"-Button extrahiert WebRex die ZIP-Datei und versucht anhand der layoutDatas.xml das Layout in WebRex zu integrieren. Solltet Ihr keine Fehler eingebaut haben, werdet Ihr zur Layout-Übersicht weitergeleitet, wo Ihr dann schon euer Layout in der Tabelle vorfindet.

Advanced Layouts

Ab und zu kann es vorkommen, dass in einem Layout noch weitere Datein benötigt werden. WebRex sind daher 3 optionale Datein bekannt:

  1. functions.js
    Benötigt man eventuell einmal in seinem Layout JavaScript-Code und man möchte diesen aber nicht in den head-Bereich der main.html mischen, dann kann die optionale Datei function.js mit in das Layout gelegt werden. Findet WebRex diese Datei während der Layout-Installation, dann wird diese Datei ebenfalls mit hochgeladen und im Frontend mittels dem <webrex:website section="head" />-Tag (= in der main.html) automatisch eingebunden. Zudem wird vor dieser functions.js die jQuery-Framework-Datei eingebunden - somit kann in der functions.js auf jede jQuery-Funktion zugegriffen werden.
  2. print.css
    Die meisten Websites lassen sich nicht weiters auf ein Papier übertragen. Was aber, wenn ein Besucher das Layout bzw. den Inhalt eurer Website ausdrucken möchte? Manche lesen vorallem längere Texte lieber auf Papier. Aus diesem Grund gibt es die optionale Datei print.css - dort kann man ein für das Papier optimale Layout entwerfen. Findet WebRex die print.css in eurem Layout-Paket, wird dese, wie die functions.js mit hochgeladen. Sie wird ebenfalls mittels dem <webrex:website section="head" />-Tag in Form eines link-Elementes eingebunden. Das link-Element erhält dabei das Attribut media mit dem Wert print.
  3. images
    In einem Layout werden meist Grafiken benötigt. Entwickelt man für sich ein persönliches Layout, dann kann man diese Grafiken einfach über den Dateimanager im Admin Control Panel hochladen. Doch was, wenn man das Layout publizieren möchte, so dass auch andere Personen das Layout für Ihre Website einsetzten können - wo verstaut man dann die Layout-Bilder? Dafür gibt es das optionale Verzeichnis images, in welchem beliebig viele Bilder untergebracht werden können. Und wieder gilt: findet WebRex dieses Verzeichnis während der Layout-Installation, dann wird dieser auch hochgeladen.

Möchte man alle 3 optionalen Layout-Features verwenden, sollte die Dateistruktur folgendermaßen aussehen (rot sind die optionalen Datein):