Websitegestaltung mit Forrest

Bevor man Anpassungen an Forrest machen kann, sollte man folgende Schritte durchführen, damit die Änderungen zusammen mit der eigenen Website gespeichert werden und nicht mit den Sourcen von Forrest vermischt werden.

Mit forrest seed baut man sich ein Rohgerüst für die eigene Site auf. Diese ist voll funktionsfähig und kann schrittweise den eigenen Bedürfnissen angepasst werden. Unter src/documentation/content/xdocs legt man seine eigenen Dokumente ab. Dort befinden sich auch die Beispiel-Files des Seed-Prozesses. Das Default-Verzeichnis für eigene Skins ist src/documentation/skins. Ein Skin definiert das Aussehen der Website. Forrest kommt mit einem Satz von verschiedenen Skins, aus denen man sich eines herausfischen kann, das einem zusagt. Die Auswahl des Skins wird in dem File forrest.properties mit dem Eintrag project.skin gemacht. Wenn man sich für ein Skin entschieden hat, legt man das Verzeichnis src/documentation/skin an, um dort sein eigenes aufzubauen. Die Kopierbasis befinden sich im Forrest-Installationsverzeichnis unter folgendem Pfad: forrest-0.6/src/core/context/skins. Von dort kopiert man das Verzeichnis mit dem ausgewählten Skin und das Verzeichnis common in das lokale Skin-Verzeichnis, benennt das Skin nach myskin um und trägt in forrest.properties das eigene Skin ein: project.skin=myskin. Danach sollten die Seiten im Browser noch genauso aussehen wie vorher.

Nun kann man beginnen, eigenen Veränderungen einzubauen.

Die Arbeit wird in den folgenden Files erledigt:

• src/documentation/skins/myskin/xslt/html/document-to-html.xsl
  Dieses XSL beschreibt die Transformationen der XML-Struktur in HTML.
• src/documentation/skins/myskin/xslt/html/tab-to-menu.xsl
  Dieses XSL baut die HTML für die Tabs (Reiter) der Website auf.
• src/documentation/skins/myskin/xslt/html/book-to-menu.xsl
  Dieses XSL baut das Menüs für die einzelnen Seiten auf.
• src/documentation/skins/myskin/xslt/html/site-to-xhtml.xsl
  Dieses XSL fügt die Ergebnisse der anderen Transformationen zu einer HTML-Seite zusammen.

Alle Dokumente verweisen auf die Basis-Dokumente aus dem Verzeichnis common. Es lohnt sich, dort einmal hineinzuschauen, um zu verstehen, wie eine HTML-Seite zusammengefügt wird. Für meine Beispiele reicht es, Anpassungen in document-to-html.xsl zu machen. Änderungen der anderen Seiten sind nach dem gleichen Schema möglich.

Wie schon in der Einleitung angeführt, ist es für Photos sinnvoll, eine Bildunterschrift darzustellen. Ansonsten muss man den Bildinhalt entweder aus dem dazugehörenden Text erläutern lassen, oder die Maus über das Bild fahren, damit die QuickInfo angezeigt wird.

Der Aufwand beim Schreiben soll aber nicht größer sein als bei einem <img>. Wir haben uns für folgendes Tag entschieden:

				
<photo src="..." class="..."
 width="..." height="..." label="..." />
			

Die Bedeutung der Attribute:

• src ist die URI des Bildes
• class ist eine CSS-class, um die Ausrichtung des Photos bestimmen zu können
• width/height sind die Breite und Höhe des Photos, um es dem Browser beim Rendern leichter zu machen
• label ist die Bildunterschrift

Ich bevorzuge es, zuerst die Lösung vorzustellen, und danach zu erläutern. Hier alse zunächst die zusätzlichen Zeilen aus meiner document-to-html.xsl:

				
<!--
  Tag für die einfache Erstellung von Photos mit Untertitel
-->
<xsl:template match="photo">
  <table cellpadding="0" cellspacing="0" class="{@class} photo" style="width: {@width}px;">
  <tr>
    <td class="photoimg">
      <img src="{@src}" width="{@width}"
           height="{@height}" alt="{@label}" title="{@label}" />
    </td>
  </tr>
  <tr>
    <td class="photolabel">
      <xsl:value-of select="@label" />
    </td>
  </tr>
  </table>
</xsl:template>
			

Ich möchte hier keinen vollständigen XSLT-Lehrgang machen, aber ein paar Erläuterungen sind doch notwendig:

• <xsl:template match="photo">
  weist den XSL-Transformator an, diese Schablone immer dann auszuführen, wenn ein Tag mit dem Namen photo geparst wird. Nur dann wird der in der Schablone enthaltene Text eingefügt. Wie hier ersichtlich handelt es sich um eine HTML-Table, die in der oberen Tabellenzelle das Bild und in der unteren Tabellenzeile die Beschriftung enthält.
• HTML-Attribut="{@photo-Attribut}"
  dient der Abbildung des Attributes aus dem eigenen Tag in die Schablone.
• <xsl:value-of select="@label" />>
  Fügt den Text der Beschriftung an der angegebenen Stelle ein. Diese Schreibweise wird benötigt, wenn Text zwischen Tags eingefügt werden soll und nicht in ein Tag-Attribut.

Ab jetzt versteht der Transformationsprozess von Forrest das Tag photo. . Nun zu den weiteren Anpassungen, damit die Geschichte auch wirklich funktioniert.

Die DTD dient einerseits der Prüfung von XML-Dokumenten und andererseits der Unterstützung des XML-Editors. Man muss also der DTD die neuen Tags hinzufügen, damit der Editor diese auch kennt. Die ausgelieferten DTD sind unter forrest-0.6/src/core/context/resources/schema/dtd zu finden. Dort muss das File document-v20.mod erweitert werden, um das neue Tag bekannt zu machen. Weiterhin muss man den XML-Editor so konfigurieren, dass er die DTD in dem angegebenen Verzeichnis sucht.

Die notwendigen Erweiterungen sind:

				
<!ENTITY % special-inline "br|img|icon|acronym|photo">

<!ELEMENT photo EMPTY>
<!ATTLIST photo
  src CDATA #REQUIRED
  height CDATA #REQUIRED
  width CDATA #REQUIRED
  label CDATA #REQUIRED
  %common.att; 
>
			

Die erste Zeile nimmt das Tag photo in die gleiche Kategorie wie img oder icon auf. Der folgende Abschnitt definiert photo als leeres Element mit 4 vorgeschriebenen Attributen. Danach sollte der XML-Editor glücklich ein.

Die letzte Hürde, die genommen werden muss, ist die Darstellung des neuen Tags. HTML-Tables sind von ihrer Natur Block-Elemente, d.h. sie füllen eine ganze Zeile aus und bieten sich nicht für die Integration in Text an.

Hier nun die passenden CSS-Definitionen

				
.photoleft {
  float: left;
}
.photoright {
  float: right;
}
.photo {
  margin: 10px;
}
.photoimg {
}
.photolabel {
  padding-top: 2px;
  text-align: center;
  font-size: 7pt;
  white-space: normal;
}
			

Erläuterungen:

• photoleft/photoright geben an, ob das Photo an den linken oder den rechten Rand verschoben werden soll. Der Text fließt automatisch um die Tabelle herum.
• photo gibt der gesammten Tabelle etwas Rand, damit der Text nicht direkt an den Bildern klebt.
• photoimg dient der Formatierung der Tabellenzelle mit dem Bild. Ich habe keine zusätzlichen Angaben benötigt.
• photolabel gibt ein bisschen Platz zwischen Bild und Beschriftung und definiert ihre Größe und Ausrichtung

Das wär's. Ich hoffe, dass dies als Einstieg in die Welt der eigenen Tags mit Apache Forrest dient. Viel Spaß beim eigenen Versuch.