Erweiterungen an einem CMS erfordern normalerweise einen erfahrenen Entwickler, doch mit Magnolias Light-Module ist das Anlegen von neuen Templates auch ohne Java-Kenntnisse möglich. In dieser Anleitung wird zunächst der Aufbau von Magnolia erläutert und anschließend darauf eingegangen, wie damit Content gepflegt und einfache Seiten Templates mit Light-Modules angelegt werden können.

Konfiguration oder Code

Der Begriff Light-Module mag zunächst die Frage aufwerfen, welche anderen Modularten zur Verfügung stehen und was an diesem nun „Light“ ist. Templates und Konfigurationen können bei Magnolia unter anderem über Java Code und Import-Dateien angelegt werden. Diese erfordern ein Java Projekt, eine Entwicklungsumgebung, Programmierkenntnisse und noch einiges mehr. Bei der Arbeit mit einem Light-Module reicht dagegen schon ein Texteditor und Kenntnis von HTML-Elementen, um einfache Webseiten zu erstellen. Bei komplexen Seiten ist es jedoch oft nötig Magnolias vollen Funktionsumfang auszuschöpfen, was mit diesen Modulen nicht möglich ist.

Die Bezeichnung „Light“ ist also passend gewählt, da diese Module besonders für Einsteiger und Webentwickler geeignet sind und sich auf die Entwicklung von einfachen Templates beschränken.

Am Anfang war das Bundle

Bei der Arbeit mit Light-Modules wird ein sogenanntes Bundle verwendet. Dieses schließt einen Tomcat mit vorkonfiguriertem Magnolia und einen Ordner, in dem Light-Modules mit ihren Templates liegen, ein.

Um die weiteren Schritte mitverfolgen zu können, kann dieses Bundle verwendet werden.Es enthält bereits ein Light-Module und einige Templates, an denen man sich orientieren kann, aber auch Magnolia stellt in seinen Tutorials solche Bundles zur Verfügung, die ebenso benutzt werden können.

Das heruntergeladene Bundle muss zunächst entpackt und der Webserver gestartet werden. Dazu navigiert man mit der Konsole in „/magnolia-example-bundle/apache-tomcat-8.5.5/bin“ und führt “magnolia_control.bat” mit dem Parameter “start” aus. Unter http://localhost:8080 kann die Anwendung nun aufgerufen werden, wo man über die nächsten Schritten und das typische Setup informiert wird. Denn das Bundle besteht genau genommen aus 2 Webanwendungen: einer Author Instance und einer Public Instance. Diese unterscheiden sich in ihrer Konfiguration und ihrem Zweck. Die Author Instance dient dem Pflegen von Inhalten und die Public Instance der Bereitstellung dieser Inhalte für Besucher. Muss eine Seite verändert werden, nimmt der Redakteur diese Änderungen auf der Author Instance vor und aktualisiert diese durch Knopfdruck auf allen eingestellten Public Instances. Diesen Vorgang nennt man Publish oder Publizieren.

Durch „Run the Web update on the author instance“ erfolgt die Modulinstallation auf der Author Instance und die Weiterleitung auf http://localhost:8080/magnoliaAuthor/.magnolia/admincentral, wo man sich zunächst mit dem Default Benutzer anmelden kann (Benutzername und Passwort sind “superuser”).

Wie ist das CMS Magnolia aufgebaut?

Wer sich zum ersten Mal mit Magnolia beschäftigt, den mag die grasgrüne Oberfläche erst einmal erschlagen, aber mit ein paar Begrifflichkeiten ist diese schnell in ihre logischen Bestandteile unterteilt und erklärt.

Über den Benutzernamen oben rechts in der Oberfläche kann das Benutzerprofil und unter anderem auch die Sprache eingestellt werden. Da die Magnolia Dokumentation auf Englisch ist, habe ich mich entschieden die Standardsprache beizubehalten und die englischen Begrifflichkeiten zu verwenden.

Admincentral

Dieses Wort hat man bereits in der URL gesehen: Es ist die Oberfläche, in der man sich anmeldet und die alle Möglichkeiten zur Konfiguration und Content Pflege beinhaltet.

Trinity Icons

Die drei Hauptbestandteile der Admincentral werden über die drei Icons im Kopfbereich der Anwendung angesteuert, die sogenannten Trinity Icons. Es handelt sich, von links ausgehend, um AppLauncher, Pulse und Favourites, welche im Folgenden genauer erläutert werden.

AppLauncher

Der AppLauncher ist der wohl wichtigste Bestandteil, da Konfiguration und Pflege hier stattfinden. Jede Funktion ist in einer eigenen “App” gekapselt und gibt diesem Bereich seinen Namen

 

Pulse

Bei dem Pulse handelt es sich um einen Posteingang innerhalb von Magnolia. Hier landen Systemnachrichten zu Erfolgen oder Fehlschlägen von langlaufenden Prozessen sowie Nachrichten, die unter den Nutzern verschickt werden können.

 

Favourites

Über das letzte Trinity Icon können Lesezeichen je Nutzer gespeichert und in Gruppen sortiert werden. Diese lassen sich am einfachsten anlegen indem man an eine Stelle navigiert, die man häufig benutzt und auf das Favourites Icon klickt. Wenn man nun ein Lesezeichen anlegt, schlägt Magnolia die vorangegangene URL und einen logischen Titel vor.

 

Apps

Navigiert man über das erste Trinity Icon in den AppLauncher, fällt auf, dass die Oberfläche an dieser Stelle in viele kleine Kacheln unterteilt ist. Jede dieser Kacheln ist eine Magnolia App und kapselt eine Funktion in sich. Pages dient der Erstellung von Seiten, Assets der Pflege von Mediendateien, Security der Konfiguration von Benutzern, Rollen und ihren Berechtigungen und Configuration der Einstellung aller möglichen weiteren Parameter. Je nach Bundle, hat man darüber hinaus noch viele weitere Apps.

 

Content Apps

Content Apps sind eine spezielle Form der Apps. Sie folgen einem bestimmtem Aufbau und haben immer eine tabellarische Übersichtsansicht und eine Detailansicht auf ein einzelnes Element. Den Namen haben diese Apps, weil der Aufbau typisch für die Content Pflege ist. Beispiele sind die Apps Pages, Assets, Categories, Contacts und Tours.

AppGroups

Die genannten Apps liegen im AppLauncher nicht lose herum, sondern sind fein säuberlich in Gruppen eingeteilt. Dabei unterscheidet man “permanent groups”, Gruppen die immer sichtbar sind, wie Edit oder Setup, von “non permanent groups”, Gruppen deren Apps ein- und ausgeblendet werden können, wie Tools und Dev.

Wie kann ich damit arbeiten?

Wenn man eine kleine Landingpage bauen will, braucht man vor allem erst einmal Seiten. Um eine Seite anzulegen, wird die Pages App benötigt. In der Übersicht der Pages App, hat man nun eine große Auswahl an Aktionen. Über die Aktion „Add Page“ kann man auch direkt eine Seite anlegen. Wenn bereits Seiten vorhanden sind, kann eine ausgewählt und mit der gleichen Aktion auch einfach eine Unterseite angelegt werden.

Nach dem Klick auf „Add Page“ folgt ein dazugehöriger Dialog, der Name und Template der Page abfragt. Dabei wird der Name zur Identifikation der Seite in einem Pfad gebraucht und sollte daher innerhalb einer Ebene eindeutig sein. Sollte man das einmal nicht beachten, übernimmt  Magnolia dies, indem es dem Seitennamen eine Ziffer anhängt.

Der nächste Dialog ist von der Wahl des Templates abhängig, denn jedes Page Template definiert selbst, welche Metadaten es abfragen will und wie es die eingeholten Informationen verarbeitet. Wenn das Template „Test Template“ gewählt wurde, sind in diesem Dialog die Felder „Title“ und „Description“ auszufüllen. Dabei stehen hinter den Labels der Felder kleine Sprachkürzel, die anzeigen, dass diese Felder mit mehreren Sprachen kompatibel sind. Über das Dropdown-Menü links neben dem Speichern-Button des Dialogs kann die Sprache gewechselt und weiterer Inhalt eingegeben werden. Nach dem Speichern des Dialogs ist die erste Seite auch schon angelegt und kann mit Inhalten gefüllt werden.

In der Bearbeitungsansicht sieht man zunächst viele Balken in unterschiedlichen Grünabstufungen, die die verschiedenen Bereiche oder Areas der Seite abgrenzen. Mögliche Areas sind z.B. Footer und  MainContent wie im folgenden Beispiel, oder auch Header, Sidebar und weitere, die unterschiedliche Anforderungen an ihren Inhalt haben und daher selbst bestimmen, welche Komponenten, also Inhalte wie Text, Teaser und Bilder, sie zulassen. Durch Klick auf eine Area wird diese aktiv und der Balken der Area dunkelgrün. Innerhalb der Area erscheinen dann weitere Balken, die bereits gepflegte Inhaltskomponenten anzeigen und die Möglichkeit bieten, weitere hinzuzufügen. Letzteres ist auch über „Add Component“ in der Actionbar am rechten Seitenrand möglich, dessen Aktionen sich beim Auswählen einer Area oder Komponente ändern.

Zunächst wird man nach dem Typ der Komponente gefragt und ob sie am Kopf oder Fuß der Area eingefügt werden soll. Diese Einordnung wird allerdings nur initial benötigt und kann später durch Sortieren per Drag & Drop angepasst werden.Der nächste Dialog ist wiederum abhängig von der gewählten Komponente. Hat man sich für die Komponente Text entschieden, enthält der nächste Dialog die Felder „Headline“ und „Text“, die wiederum mehrsprachig eingegeben werden können. Durch Speichern wird die Komponente eingefügt und kann durch Klick auf seinen grünen Balken und wählen der Aktion wiederum bearbeitet werden.

Ist man mit seiner Seite schon recht zufrieden, hat man die Möglichkeit sich das Ganze noch einmal im Vorschaumodus anzusehen, ohne die grünen Balken in der Seite. Dadurch ist man in der Lage die Seite so zu sehen, wie der Seitenbenutzer sie letztendlich vorfinden wird. Dazu wählt man die Aktion Preview Page, die zusätzlich am oberen Rand die Möglichkeit bietet, das Anzeigegerät und die Sprache zu wechseln, sowie die Seite in einem eigenen Browser Tab  zu öffnen.

Wie kann ich Templates selbst anlegen?

Um ein Template anzulegen, muss man verstehen, dass diese immer aus einer Templatedefinition und einem Templateskript bestehen. Dabei wird mit der Definition Name, Areas, Dialog und Skript des Templates in Form einer Yaml-Datei bestimmt. Mit dem Skript legt man wiederum das Aussehen und die Anordnung der Informationen fest, hier als FTL-Datei. Beide Dateien werden standardmäßig unter „/magnolia-example-bundle/apache-tomcat-8.5.5/webapps/magnoliaAuthor/modules“ im jeweiligen Modulordner angelegt. Möchte man den Ort ändern, muss man in die Datei „magnolia.properties“ unter „/magnolia-example-module/apache-tomcat-8.5.5/webapps/magnoliaAuthor/WEB-INF/config/default“ gehen und den Eintrag für „magnolia.resources.dir“ bearbeiten. Dieser hat üblicherweise den Wert „${magnolia.home}/modules“.

 

Das erste statische Seiten-Template

Um ein Template anzulegen, geht man nun zuerst in ein beliebiges Light-Module, z.B. „example-module“, welches ein Ordner in dem bereits beschriebenen Module Ordner ist. Dort sind die Dateien in Webressourcen, z.B. JS oder CSS Dateien, Dialogdefinitionen für die Bearbeitunsgdialoge und Templates aufgeteilt. Auch die Templates sind wieder in Pages und Components untergliedert.

Für eine neue Seite wird zunächst ein Templateskript unter /example-module/templates/pages benötigt. Dieses ist eine Datei vom Dateitypen „ftl“, und kann in diesem Schritt statisches HTML enthalten. Im Anschluss wird eine neue Yaml Datei neben dem Skript abgelegt, die die wichtigsten Informationen enthalten sollte. Zu diesen gehört der „renderType“, der die verwendete Templatesprache definiert, in diesem Fall „ftl“, der Pfad zu dem dazugehörigen Templateskript und der Titel des Templates. Das Test-Template kann hierzu als Beispiel herangezogen werden, denn es ist zu  beachten, dass YAML-Dateien keine Tabs enthalten dürfen und mit Leerzeichen eingerückt werden müssen. Nun sollte das neue Template bereits im Auswahldialog zur Verfügung stehen und die statische Seite ausgeben.

 

Das Template wird dynamisch

Um Informationen beim Anlegen der Seite entgegenzunehmen brauchen wir zunächst einen Dialog. Dieser wird in /dialogs/pages als Yaml Datei abgelegt und bestimmt die abzufragenden Felder und die Aktionen, die ausgelöst werden können. Auch mehrere Tabs sind durch diese Art der Konfiguration möglich. Ist der bestehende Dialog kopiert und nach individuellen Wünschen angepasst, muss dieser, wie im Folgenden zu sehen ist, über eine ID  in der Definition des Seitentemplates, die zuvor als Yaml Datei unter /templates/pages/ angelegt wurde, referenziert werden.

Die ID einer Definition setzt sich immer aus dem Modulnamen, gefolgt von einem Doppelpunkt, dem Pfad zur Definition und dem Dateinamen zusammen. Die ID des bestehenden „Test Template“ lautet also „example-module:pages/testPage“, weil bei einem Template der Pfad ausgehend vom „templates“ Ordner angegeben wird. Analog dazu wird bei der ID einer Dialogdefinition der Pfad ausgehend vom „dialogs“ Ordner angegeben und lautet für den Dialog des Test Template „example-module:pages/testPageDialog“.

Nun muss das Skript um die Zeile „[@cms.page /]“ erweitert werden, um die Seite für den Page Editor zu initialisieren. Anschließend sollten die Informationen aus dem Dialog natürlich auch in irgendeiner Form angezeigt werden, was in diesem Tutorial mit Magnolias Standard-Templatesprache Freemarker, bewerkstelligt wird.  Dazu wird zunächst der Seiteninhalt benötigt, der unter „content“ im Template zur Verfügung steht. Über „content“ können nun alle Felder abgefragt werden, die im dazugehörigen Dialog definiert wurden. Im folgenden Beispiel ist zu sehen, wie man das Feld mit dem Namen „text“ auslesen und anzeigen kann. Dies geschieht in diesem Fall nur, wenn der Text auch wirklich ausgefüllt wurde, was mit einem sogenannten „Built in“ erreicht wird. Die Zeilen darüber enthalten zudem einen Kommentar, der weitere Erklärungen enthält. Da eine komplette Einleitung in Freemarker zu weit führen würde, empfiehlt es sich die kommentierten Beispiele in dem „example-module“ oder die Freemarker Dokumentation zu Rate zu ziehen.

 

Hat man alle Felder ausgewertet und gegen fehlende Eingaben abgesichert, erhält man bereits beim Anlegen den konfigurierten Dialog.

 

Das Template erlaubt Komponenten

Eingaben über das Seitentemplate reichen allerdings selten aus, denn meistens hat man Bausteine, die man immer wieder verwenden will. Diese kann man nun genau wie die Seite als Template in dem Light-Module anlegen. Der einzige Unterschied ist, dass man die Template- und Dialogdefinitionen nicht im Ordner „pages“ sondern in „components“ anlegt und dass das Skript nicht das HTML einer kompletten Seite enthält. Um die Komponenten seiner Wahl in der Seite verfügbar zu machen, fehlt allerdings noch die Area. Diese kann in der Templatedefinition der Seite hinzugefügt und mit einer Reihe Komponenten versehen werden. Wichtig ist auch hier die korrekte Vergabe der IDs und der Name der Area. Diese wird nun nämlich unter dem vergebenen Namen mit der Zeile „[@cms.area name=“main“/]“ in das Templateskript der Seite eingefügt und schon erhält die angelegte Seite einen grünen Balken für die Area, über die die Seite weitere Inhalte erhalten kann.

Warum eigentlich Module?

Die Anleitung sieht in diesem Fall vor, dass man das bestehende Modul „example-module“ erweitert, aber natürlich kann man ebenso ein eigenes Light-Module verwenden, indem man einfach einen neuen Ordner anlegt. Diese Unterteilung der Module dient vor allem dazu, die geschriebenen Templates in logische Bestandteile zu gliedern, um sie an anderer Stelle eventuell wiederzuverwenden. An dieser Stelle kann man beispielhaft die Module „forms“ für Formulare und „shop“ für e-commerce Funktionen aufführen, welche von Magnolia bereits und in den eigenen Projekten als Library eingefügt werden können. Weitere Informationen zu Modulen von Magnolia und wie sie einzubinden sind findet man in deren Dokumentation oder im Magnolia Marketplace.

Wir suchen einen Java Developer (m/w)!
Du sprichst und schreibst fließend Java? Gewissenhaft und mit hohem Qualitätsanspruch arbeitest du an cleveren Lösungen und bist erst dann zufrieden, wenn auch wirklich alles zuverlässig funktioniert? Die Entwicklung automatisierter Tests ist für dich keineswegs eine lästige Pflicht, sondern lässt dein Herz höher schlagen? Dann nichts wie auf zu queo!

 

1 Kommentar

  • […] verbesserte Backend-Suche, Erweiterungen des Magnolia CLI (Command Line Interface) zum einfacheren Arbeiten mit Light Modules und ein Instrumentation Modul, das das Monitoring der Anwendung auf Basis von Prometheus erlaubt. […]

Diskutieren Sie mit!

Alle mit einem markierten Felder sind Pflichtfelder und müssen ausgefüllt werden