Hier wird beschrieben, wie ein Seiten-Template aufgebaut ist: eine XML-Datei in config/templates/pages und eine Twig-Datei, auf die <view> zeigt. Twig bekommt content, view, extension, resource und localizations; andere Seiten lädt sulu_page_load mit einer Liste der gewünschten Eigenschaften.
Reihe 5: Sulu für Entwickler Kapitel 3 von 16
Seiten-Templates: XML und Twig
Kurz zusammengefasst
Die XML-Datei beschreibt die Felder für den Admin, die Twig-Datei zeigt die Inhalte auf der Website. Die Beispiele stammen aus den Templates der Website bertrams-media.
Vorher hilfreich: 5.2 Ein Projekt aufsetzen und der Webspace
Die XML-Datei
Das Template liegt in config/templates/pages/. Der Dateiname ist frei, entscheidend ist das Element <key>. Dazu kommen die Twig-Datei (<view>), der Controller, die Cache-Dauer, ein Titel für den Admin und die Felder. Das Template default der Beispiel-Website bindet ihre Felder aus page-default.xml und includes/default.xml ein. Hier steht ein Gerüst mit nur zwei Feldern, gekürzt aus page-default.xml:
<?xml version="1.0" encoding="utf-8"?>
<template xmlns="http://schemas.sulu.io/template/template"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.sulu.io/template/template http://schemas.sulu.io/template/template-1.0.xsd">
<key>simple</key>
<view>pages/simple</view>
<controller>Sulu\Content\UserInterface\Controller\Website\ContentController::indexAction</controller>
<cacheLifetime>604800</cacheLifetime>
<meta>
<title lang="en">Simple</title>
<title lang="de">Einfach</title>
</meta>
<properties>
<property name="title" type="text_line" mandatory="true">
<meta>
<title lang="en">Title</title>
<title lang="de">Titel</title>
</meta>
<params>
<param name="headline" value="true"/>
</params>
<tag name="sulu.rlp.part"/>
</property>
<property name="url" type="route" mandatory="true">
<meta>
<title lang="en">Resource Locator</title>
<title lang="de">Adresse</title>
</meta>
<tag name="sulu.rlp"/>
</property>
</properties>
</template>
<view>ist der Twig-Pfad ohne Endung:pages/simplemeinttemplates/pages/simple.html.twig. Der Controller hängt.html.twigselbst an.<controller>ist in allen Templates der Beispiel-WebsiteContentController::indexActionaus dem Paketcontent.<cacheLifetime>steuert, wie lange die Antwort im HTTP-Cache bleibt. Die Seiten-Templates der Beispiel-Website nehmen 604800 (sieben Tage), die Handbuch-Kapitel 2400.- Das Tag
sulu.rlp.partam Titel sagt dem Admin, aus welchen Feldern er die Adresse vorschlägt. Das Tagsulu.rlpmarkiert das Feld, in dem die Adresse steht. Ohne beide gibt es keinen Vorschlag.
Die Twig-Datei
Die Twig-Datei erweitert ein Layout und füllt dessen Blöcke. In der Beispiel-Website ist das layouts/page.html.twig, das Kopf, Banner, Brotkrumen und Fußzeile mitbringt und den Block content anbietet. Das Template default besteht im Kern aus zwei Zeilen:
{% extends "layouts/page.html.twig" %}
{% block content %}
<h1>{{ content.title }}</h1>
{% include 'blocks/blocks.html.twig' with { blocks: content.blocks, view_blocks: view.blocks } %}
{% endblock %}
Die zweite Zeile im Block setzt eine Blockliste namens blocks im XML-Template voraus, wie sie includes/default.xml liefert. Wie Blöcke aufgebaut sind, steht in „Blöcke, Includes und Atome“.
Was Twig bekommt
Der Controller reicht das Ergebnis des Content-Resolvers an Twig weiter. Die Struktur steht im Kopf von ContentResolver::resolve(): resource (die Entität), content (die Felder des Templates), view (Zusatzdaten parallel zu den Feldern, etwa die UUIDs gewählter Seiten) und extension (Auszug und SEO). Dazu kommt localizations mit Adresse, Sprache und alternate je Sprache, in der die Seite existiert.
Die Blöcke laufen deshalb in zwei Listen mit: content.blocks[i] hat die Feldwerte, view.blocks[i] die Zusatzdaten desselben Blocks. Das blocks.html.twig der Beispiel-Website verbindet beide und bindet für jeden Block die passende Datei ein:
{% for block in blocks %}
{% set block = block|merge({'position': loop.index, 'view': view_blocks[loop.index0]}) %}
{# Block "main-text" -> blocks/main/text.html.twig #}
{% include 'blocks/main/' ~ block.type[5:] ~ '.html.twig' with block %}
{% endfor %}
Seiten und Navigation laden
Andere Seiten werden mit sulu_page_load(uuid, properties, locale) geladen. Der Parameter properties ist seit Sulu 3 Pflicht und bildet Ausgabenamen auf Pfade im Resolver ab. Das Ergebnis enthält die Werte auf oberster Ebene, also page.title und nicht page.content.title.
{% set page = sulu_page_load(link.href, {
'title': 'title',
}) %}
{% set title = page.title|default(null) %}
Für Menüs gibt es sulu_page_navigation_tree, sulu_page_navigation_flat, sulu_page_navigation_root_tree und sulu_page_navigation_root_flat. Die Fußzeile der Beispiel-Website liest damit den Navigationskontext links bis zur zweiten Ebene:
{% set footerNavigation = sulu_page_navigation_root_flat('links', 2, {
'uuid': 'object.resource.id',
'title': 'title',
'url': 'url',
'webspaceKey': 'object.resource.webspaceKey'
}) %}
Der Admin liest die Felder aus der XML-Datei und zeigt nach einer Änderung so lange das alte Formular, bis der Cache beider Kontexte geleert ist.
Mehr dazu
- 5.4Blöcke, globale Blöcke, Includes und Atome
- 5.12SEO und schema.org im Twig Gilt für: Template der Beispiel-Website
Offizielle Dokumentation
- Creating a Page Template (Externe Seite, öffnet in einem neuen Fenster)
- Rendering Pages with Twig (Externe Seite, öffnet in einem neuen Fenster)
- Property Type Reference (Externe Seite, öffnet in einem neuen Fenster)
- Twig Extensions (Externe Seite, öffnet in einem neuen Fenster)
- PageBundle (Externe Seite, öffnet in einem neuen Fenster)