Im ersten Teil des Neos Workshops haben wir uns bereits eine virtuelle Umgebung für das CMS geschaffen und uns mit der Funktionsweise des Backends vertraut gemacht. Mit diesem Teil wollen wir nun beginnen, ein eigenes Projekt in Neos umzusetzen. Als Beispielprojekt soll uns die Präsenz eines lokalen Weinladens dienen.

Ein neues SitePackage erstellen

Jede neue Seite in Neos startet mit dem Anlegen eines neuen Site Packages. Das Site Package beinhaltet alle Teile, welche das Aussehen und die Grundfunktionen der Seite ausmachen. Um frisch starten zu können, entfernen wir sowohl den Content als auch das Site Package der bereits installierten Demo Seite. Das geht am bequemsten über das Kommandozeilen-Interface von Flow - Flow ist das Applikationsframework hinter Neos.

./flow site:prune
composer remove neos/demo

./flow kickstart:site WL.WeinLaden weinladen.local
./flow site:import WL.WeinLaden

Der Kickstarter legt uns im Verzeichnis Packages/Sites/WL.WeinLaden eine Reihe von Verzeichnissen und Dateien an, deren Bedeutung ich kurz beschreiben möchte.

.
|-- Classes
|-- Configuration
|   `-- NodeTypes.yaml
|-- Resources
|   `-- Private
|       |-- Content
|       |   `-- Sites.xml
|       |-- Templates
|       |   `-- Page
|       |       `-- Default.html
|       `-- Fusion
|           `-- Root.fusion
|-- Tests
|   |-- Functional
|   `-- Unit
`-- composer.json

Werden PHP Klassen für die Umsetzung der Seite benötigt, werden diese unter Classes abgelegt und von dort automatisch geladen. Das Verzeichnis Configuration enthällt bereits eine Datei "NodeTypes.yaml" welche für die Definition eigener Inhaltstypen verwendet werden kann. 
Unter Resources/Private liegen Dateien, welche für das Projekt benötigt werden, aber nicht von aussen zugänglich sein sollen. Unter anderem wurden hier schon eine rudimentäre Template Datei sowie eine Datei für Fusion Code angelegt.

Entwicklungsumgebung vorbereiten

Um komfortabel an unserer Seite entwickeln zu können, ist die Verwendung einer IDE, welche zumindest ein Syntax Highlighting der gängigen Websprachen beherrscht, zu empfehlen. Das kann beispielsweise das leichtgewichtige SublimeText oder das mächtige PHPStorm sein.

Um mit einer IDE an unserer Seite arbeiten zu können, kopieren wir uns die Dateien am besten in einen lokalen Ordner. Dazu wechseln wir in das vagrant Verzeichnis (~/vagrant-neosbox) und führen den folgenden, etwas sperrigen Befehl aus, welcher die Dateien in den Ordner neos-workshop in unserem Home Verzeichnis kopiert:

rsync -avP --rsh="ssh -i "$(vagrant ssh-config | grep IdentityFile | awk  '{print $2}')"" vagrant@172.17.28.28:/var/www/Packages/Sites/ ~/neos-workshop

Änderungen, welche wir im Laufe des Workshops an dem SitePackage vornehmen, sollen am Besten automatisch zurück in die Box kopiert werden. Vagrant bringt dafür eine elegante Lösung mit. Um diese zu nutzen, bearbeiten wir die Datei Vagrantfile in unserem Vagrant Ordner (~/vagrant-neosbox) und fügen die unten markierten Zeilen 5 und 6 hinzu.

Die neuen Zeilen führen dazu, dass Änderungen im Ordner neos-workshop von Vagrant automatisch erkannt werden und per rsync an die richtige Stelle in die Box kopiert werden.

Vagrant.configure("2") do |config|
  config.vm.box = 'punktde/workshop'
  config.vm.box_url = "https://punkt.de/Download/workshop.box"
  config.vm.synced_folder '.', '/vagrant', id: 'vagrant-root', disabled: true
  config.vm.synced_folder "~/neos-workshop/", "/var/www/Packages/Sites/", type: "rsync",
    rsync__exclude: ".git/"
  config.vm.network 'private_network', ip: '172.17.28.28'
  config.ssh.forward_agent = true
  config.vm.provider 'virtualbox' do |vb|
    vb.memory = '4096'
    vb.cpus = '1'
    vb.name = 'workshopbox'
  end
end

Nach der Änderung muss die Box einmal neu gestartet werden. Das geschieht mit dem Befehl:

vagrant reload

Die automatische Synchronisation steht nun bereit und kann mit folgendem Befehl gestartet werden:

vagrant rsync-auto

Erstes Templating mit Fusion und Fluid

Zur Einbindung der Datei ist bereits eine Section im HEAD-Bereich der generierten ./Resources/Private/Templates/Page/Default.html vorgesehen. Der Fluid Resource ViewHelper generiert uns den Pfad zu den Dateien unter Resources/Public.

<head>
	<f:section name="stylesheets">
		<link rel="stylesheet" href="{f:uri.resource(path: 'Styles/Main.css', package: 'WL.WeinLaden')}" />
	</f:section>
	<f:section name="headScripts">
	<!-- Put your scripts inclusions for the head here, they will be included in your website by Fusion -->
	</f:section>
</head>

Welche Sections aus der Template Datei gerendert werden, wird in der TypoScript Datei ./Resources/Private/TypoScript/Datei Root.ts2 definiert.
Hier wird auch das Menü mit dem einfachen Konstrukt "menu = Menu" aus dem TypoScript-Objekt Menu instanziiert und in den Variablen menu bereit gestellt. Die Erstellung des Menüs können wir mit diversen Parametern anpassen. In unserem Beispiel benötigen wir weitere CSS Klassen, damit das CSS von Bootstrap Wirkung zeigt. Die Zeile wird also folgendermaßen erweitert:

menu = Menu {
	attributes.class = 'nav navbar-nav pull-right'
}

Viele weitere Parameter des Menüs und seiner Elemente können hiermit angepasst werden. Eine komplette Liste findet sich in der Fusion Referenz.

Als letztes erweitern wir das Markup der Default.html um das Menü und ein Logo für unsere Seite.

<f:section name="body">
    <nav class="navbar navbar-default">
        <div class="container">
            <a class="navbar-brand" href="/">Wein<span>Laden</span></a>
            {parts.menu -> f:format.raw()}
        </div>
    </nav>

	<div class="container">
		{content.main -> f:format.raw()}
	</div>
</f:section>

Ein Footerbereich für alle Seiten

Nun fehlt der Seite noch ein frei gestaltbarer Footer Bereich. Dazu reichen kleine Erweiterungen in der Seitenkonfiguration, im Fusion und dem Template, die im Folgenden Schritt für Schritt erklärt werden. Die genaueren Hintergründe, wie Neos die Daten speichert und in welcher Weise wir darauf zugreifen können, soll aber erst Inhalt des dritten Teils des Workshops sein.

Zunächst legen wir in der NodeTypes.yaml, welche wir im Verzeichnis Configuration finden, mit den folgenden Zeilen einen neuen Bereich mit dem Namen footer an:

'Neos.NodeTypes:Page':
  childNodes:
    'footer':
      type: 'Neos.Neos:ContentCollection'

Damit erhalten alle neu angelegten Seiten einen weiteren Content-Bereich für den Footer. Dieser Bereich muss nun auch allen bereits angelegten Seiten hinzugefügt werden. Dazu verwenden wir den Befehl node:repair des flow Kommandos auf der Console, welcher die bestehenden Seiten an die neue Konfiguration anpasst und den Footer Bereich auch dort anlegt:

./flow node:repair

In der Fusion Datei Root.fusion können wir nun den Footer (Zeile 7-9) ähnlich dem Hauptbereich selektieren und an das Template übergeben ...

content {
// The default content section
	main = PrimaryContent {
		nodePath = 'main'
	}

	footer = PrimaryContent {
		nodePath = 'footer'
	}
}

... und dort im Template "Resources/Private/Templates/Page/Default.html" anzeigen:

<footer>
	<div class="container">
		{content.footer -> f:format.raw()}
	</div>
</footer>

Sollen alle Seiten den gleichen Footer erhalten, reicht es, die obige Zuweisung in Fusion durch die Folgende zu ersetzen. Durch die folgenden Zeilen wird nicht der Footer der jeweils gewählten Seite selektiert und bearbeitet, sondern stets der Footer der Root-Seite. 

footer = ContentCollection {
	nodePath = ${q(site).children('footer').property('_path')}
	collection = ${q(site).children('footer').children()}
}

Somit ist unsere erste Seite mit zwei Inhaltsbereichen und dem Menü fertig und kann mit Inhalten gefüllt werden. Der Stand des Sitepackages nach diesem Teil des Workshops kann auch noch einmal auf dem dazugehörigen Repository auf github nachvollzogen werden.