Willkommen zum dritten Teil unseres Neos Tutorials. Im ersten Teil wurde gezeigt wie sich eine lokale Entwicklungsumgebung für Neos mit Vagrant einfach aufsetzen lässt. Im zweiten Teil haben wir dann ein Site Package für unsere eigene Seite gestartet. In diesem Teil geht es nun um die Struktur und die Konfiguration von eigenen Content Typen.

Inhalt ordentlich strukturiert - Das Neos Content Repository

Um eigene Inhaltstypen zu definieren, ist es zunächst einmal wichtig die Datenstruktur hinter Neos zu verstehen, daher beginnt dieser Teil mit etwas (spannender) Theorie.

Jeglicher Inhalt in Neos wird als Knoten (Node) einer Baumstruktur (Tree) abgelegt.  Man kann sich die Struktur ähnlich dem Dateisystem eines Computers vorstellen. Jede Knoten hat einen eindeutigen Namen und einen Typ - ähnlich dem Typ einer Datei im Dateisystem - welcher die definierten Eigenschaften der Node festlegt.

Die Daten der Node werden in ihren Eigenschaften abgelegt. Natürlich kann jeder Knoten weitere Unterknoten besitzen. Die Wurzel des Baumes ist ein spezieller Knoten namens "Site".

Am besten lässt sich das an einer einfachen Webseite mit einer hierarchischen Menüstruktur veranschaulichen. Jede Seite wird durch eine Node vom Typ "Document" repräsentiert - Unterseiten der zweiten Menüeben sind dabei Kindknoten der ersten Ebene.

Auch der Inhalt der Seite, wie Text- oder Bildelemente sind Nodes, welche als Kindknoten an der jeweiligen Seite hängen. Dabei können auch Inhalte - wie beispielsweise ein 2-Spalten-Container - ihrerseits wieder Kindknoten haben. Die Inhalte lassen sich so beliebig tief verschachteln. Zusätzlich kann jede Node noch beliebige Eigenschaften, hier Properties genannt, besitzen.

Im Bild ist ein solcher Baum mit einer Seite Home und einer Seite "Weine aus aller Welt" zu sehen. Die Seiten können einfache StandardInhalte wie Texte oder Bilder beinhalten oder ein spezielles Contentelement, welches in unserem Beispiel einen Wein repräsentiert. Ein solches Element soll in diesem Teil des Workshops erstellt werden.

Definition eines neuen Inhaltstyps

Jeder neue Inhaltstyp beginnt mit der Definition eines eigenen NodeTypes. Die Datenstrukturen des NodeTypes werden in der Auszeichnungssprache YAML definiert. Hier werden auch MetaInformationen wie Editiermöglichkeiten, Hilfetexte und Beziehungen zu anderen Typen definiert. NodeType-Definitionen können beliebig vererbt werden, wobei auch Mehrfachvererbung möglich ist. Dadurch ist es möglich, einfache wiederverwendbare Datentypen zu defineren, welche sich dann mit ihren Eigenschaften zu größeren Definitionen verbinden lassen.

Neos definiert bereits eine Reihe von abstrakten Basis Typen, welche ein Grundverhalten eines Datenelementes festlegen.

• Neos.Neos:Node: ist die Grundlage aller anderen definierten Typen.
• Neos.Neos:Document: definiert die Grundlage aller Knoten welche sich wie Seiten verhalten.
• Alle Inhalte einer Seite erben von den Typen Neos.Neos:Content oder Neos.Neos:ContentCollection. Während eine ContentCollection zur Strukturierung von Content dient - beispielsweise für einen Mehrspaltencontainer, ist der Content die Basis jedes einfachen Inhalts, wie einer Überschrift oder einem Bild.

Mit diesem Wissen können wir uns daran machen einen eigenen einfachen Inhaltstyp zu erstellen: passend zur Seite soll dies die Präsentation eines Weines mit Titel, Beschreibung, Bild und Rebsorte sein. Alle Dateien welche wir im folgenden anlegen, werden unter dem Verzeichnis des Site Packages angelegt. Der zweite Teil des Workshops veranschaulicht den grundlegenden Aufbau des Site Packages. 

'WL.WeinLaden:Wine':
  superTypes:
    'Neos.Neos:Content': true
  ui:
    label: Wein
    icon: icon-glass
    inspector:
      groups:
        wine:
          label: Wein
  properties:
    title:
      type: string
      ui:
        label: 'Name'
        inlineEditable: true
        aloha:
          placeholder: 'Titel des Weins'
    description:
      type: string
      ui:
        label: 'Beschreibung'
        inlineEditable: true
        aloha:
          placeholder: 'Beschreibung des Weins'

Unter dem Bereich Inspector liegen jeweils Eigenschaften welche die Bedienelemente in der rechten Seitenleiste betreffen. Die Bedienelemente können in Gruppen zusammengefasst werden. Eine solche Gruppe mit dem Label "Wein" wird hier angelegt.

Als nächstes werden die Eigenschaften der Node definiert. Der Inhalt vom Typ "string" kann direkt "inline" auf der Seite bearbeitet werden, was mit der Eigenschaft inlineEditable:true angegeben wird. Aloha ist der Name des Editors, welcher dafür verwendet wird und welcher hier parametrisiert werden kann. Der hier definierte Placeholdertext wird angezeigt, wenn noch kein eigener Text angegeben wurde und unterstützt so den Redakteur beim Bearbeiten der Seite.

{namespace neos=Neos\Neos\ViewHelpers}
<div {attributes -> f:format.raw()}>
	<neos:contentElement.editable property="title" tag="h3" />
	<neos:contentElement.editable property="description" tag="p" />
</div>

In der ersten Zeile importieren wir die ViewHelper aus dem neos-Namespace, welche wir zur Anzeige der bearbeitbaren Elemente benötigen. Mit dem "contentElement.editable"-ViewHelper legen wir für die zuvor definierten Properties, bearbeitbare HTML Elemente an. Die Überschrift wird dabei mit dem H3-Tag gerendert und der Text mit einem Paragraph.

Fertig ist das erste eigene Inhaltselement, welches nun auch auf der Seite integriert werden kann.

    grape:
      type: string
      ui:
        label: Rebsorte
        help:
          message: Hier bitte die Rebsorte wählen
        reloadIfChanged: true
        inspector:
          group: wine
          editor: Neos.Neos/Inspector/Editors/SelectBoxEditor
          editorOptions:
            values:
              Merlot:
                label: Merlot
              Syrah:
                label: Syrah
              Chardonnay:
                label: Chardonnay
    image:
      type: Neos\Media\Domain\Model\ImageInterface
      ui:
        label: Bild
        reloadIfChanged: true
        inspector:
          group: wine
          editorOptions:
            crop:
              aspectRatio:
                locked:
                  width: 3
                  height: 2

Das Rendern des Bildelements im Template gelingt in diesem Fall am einfachsten mit dem Neos Image-Partial. Um dieses zu benutzen, muss per Fusion der PartialRootPath auf das richtige Verzeichnis gesetzt werden. Dazu legen wir unter Resources/Private/Fusion/NodeTypes/ eine neue Datei Wine.fusion an und fügen die folgenden Zeilen ein:

prototype(WL.WeinLaden:Wine) < prototype(Neos.Neos:Content) {
    partialRootPath = 'resource://Neos.NodeTypes/Private/Templates/NodeTypes/Partials'
}

Damit definieren wir einen neuen Fusion Prototyp für unser Content Element, welcher zum Rendern herangezogen wird. Durch das Erben vom Basistyp "Content" übernehmen wir einige Basiseinstellungen zur Darstellung eines Content Elements, welche wir für unser eigenes Element nun überschreiben oder erweitern können.

Diese Datei (sowie alle anderen Dateien im Verzeichnis NodeTypes) binden wir mit der folgenden Zeile am Ende der Datei Root.fusion ein

include: NodeTypes/*

Daraufhin kann das Template unseres Content Elements um die zusätzlichen Daten erweitert werden. Um das Bild anzuzeigen, verwenden wir nun das Image Partial. Dieses verlangt als minimale Anzahl an Argumente das Image Objekt sowie ein Text für den alt-Tag.

{namespace neos=Neos\Neos\ViewHelpers}
<div {attributes -> f:format.raw()}>
    <div class="thumbnail">
        <f:render partial="Image" arguments="{image:node.properties.image, alt:node.properties.title, maximumWidth:1600}" />
        <div class="caption">
            <neos:contentElement.editable property="title" tag="h3" />
            <neos:contentElement.editable property="description" tag="p" />
            <div class="row">
                <div class="col-md-6">Rebsorte:</div><div class="col-md-6"><b>{node.properties.grape}</b></div>
            </div>
        </div>
    </div>
</div>

Die Bilder in unserem Content Element werden so erst einmal in der vollen Originalauflösung ausgegeben. Die Auflösung lässt sich aber mit den zusätzlichen Argumenten maximumWidth und maximumHeight an das Image partial auf ein sinnvolles Maß für unseren Anwendungsfall einschränken.

Vorhande NodeTypes anpassen - Mehrspaltencontainer mit Bootstrap Markup

Unser neues Content Element würde sich wunderbar in einer Spalte eines Mehrspaltencontainers machen. Neos bringt standardmäßig bereits Container für 2, 3 und 4 Spalten mit. Damit diese aber so gerendert werden, dass das Markup und die verwendeten CSS Klassen zum hier eingesetzten Bootstrap Framework passen, müssen ein paar kleinere Anpassungen vorgenommen werden. 
Die Anpassungen eignen sich überdies gut, um ein wenig mehr von der Funktionalität von Eel und FlowQuery kennen zu lernen.

'Neos.NodeTypes:TwoColumn':
  properties:
    'layout':
      defaultValue: '9-3'
      ui:
        inspector:
          editorOptions:
            values:
              '50-50': ~
              '75-25': ~
              '25-75': ~
              '66-33': ~
              '33-66': ~
              '9-3':
                label: '75% / 25%'
              '6-6':
                label: '50% / 50%'
              '3-9':
                label: '25% / 75%'

'Neos.NodeTypes:ThreeColumn':
  properties:
    layout:
      defaultValue: '4-4-4'
      ui:
        reloadIfChanged: true
        label: ''
        inspector:
          editorOptions:
            values:
              '33-33-33': ~
              '50-25-25': ~
              '25-50-25': ~
              '25-25-50': ~
              '4-4-4':
                label: '33% / 34% / 33%'

prototype(Neos.NodeTypes:MultiColumn) {
    attributes.class = 'row'
    columns.iterationName = 'multiColumnIteration'
}

prototype(Neos.NodeTypes:MultiColumnItem) {
    attributes.class = ${'col-md-' + String.split(q(node).parent().property('layout'), '-')[multiColumnIteration.index]}
}

In diesem Workshopteil haben wir gesehen, wie eigene NodeTypes in YAML definiert und mit Fusion und Fluid gerendert, sowie wie vorhandene NodeTypes einfach erweitert und angepasst werden können. Den Kompletten Stand des Site Packages kann im GitHub Repository zum Workshop nachvollzogen werden.