Download the PHP package futura/contao-dynamic-snippets without Composer

Contao Dynamic Snippets

Wiederverwendbare HTML-Snippets mit Platzhaltern als Inhaltselemente für Contao 5.

Ein Projekt von Futura Web.

Ein Admin legt einmal eine HTML-Vorlage an, z. B. einen Embed-Code, eine Karte oder ein Layout-Fragment, und markiert die veränderlichen Stellen mit Platzhaltern. Redakteure wählen die Vorlage danach als normales Inhaltselement aus und füllen nur noch die Felder aus. HTML-Kenntnisse sind dafür nicht nötig.

Für wiederkehrende, strukturierte Bausteine entfällt damit die langwierige eigene Modulprogrammierung: kein eigener DCA, kein eigener Fragment-Controller, kein eigenes Twig-Template pro Baustein mehr. Die Vorlage im Backend übernimmt diese Arbeit.

Installation

Aus diesem Repository (empfohlen)

In der composer.json der Contao-Installation ein VCS-Repository eintragen:

Als lokales Paket

Für die Entwicklung am Bundle selbst, z. B. in packages/contao-dynamic-snippets der Contao-Installation:

Benutzung

1. Backend → Inhalte → Snippet-Vorlagen → neue Vorlage anlegen.
2. Einen sprechenden Namen vergeben, z. B. "Teaser-Kachel" oder "YouTube-Embed". Unter diesem Namen erscheint die Vorlage später in der Auswahl. Optional eine Beschreibung als Notiz für Redakteure ergänzen.
3. HTML einfügen und Platzhalter setzen.
4. Im Artikel ein Inhaltselement vom Typ Snippet-Element anlegen, im Dropdown die Vorlage nach Namen wählen, Felder befüllen.

Platzhalter-Syntax

Aufbau: [[typ:name.cssklasse|Beschriftung]]

Beispiele. Die Feldnamen darin (slogan, intro, bild usw.) sind frei erfunden, du vergibst eigene.

Namen bestehen aus Kleinbuchstaben, Ziffern und Unterstrich. Derselbe Platzhalter darf mehrfach vorkommen und wird im Backend nur einmal abgefragt. Contao-Insert-Tags wie {{link_url::12}} funktionieren weiterhin, sowohl in der Vorlage als auch in den eingegebenen Werten.

Breite der Backend-Felder

Jeder Feldtyp hat eine sinnvolle Standardbreite: einzeilige Felder wie text, url, number und select nehmen standardmäßig die halbe Zeile ein (w50), mehrzeilige und komplexere Felder wie textarea, rte, html und image die volle Breite.

Diese Standardbreite lässt sich pro Platzhalter überschreiben, indem eine Contao-CSS-Klasse mit einem Punkt an den Namen angehängt wird, z. B. [[text:vorname.w33|Vorname]]. Gängige Klassen:

Mehrere Klassen lassen sich mit + verbinden, z. B. .w33+clr, um ein drittelbreites Feld zu erzeugen, das trotzdem eine eigene Zeile beginnt. Felder mit derselben Breitenklasse, die direkt aufeinanderfolgen, stehen im Backend-Formular nebeneinander, genau wie bei Contaos eigenen Formularen.

Beispiel: Teaser-Kachel

Beispiel: YouTube-Embed

Ausgabe

Werte werden je nach Typ behandelt:

• text, url, number, select, checkbox: HTML-Sonderzeichen werden maskiert.
• textarea: maskiert plus nl2br.
• html, rte: unverändert ausgegeben.
• image: über Contao Image Studio als <figure> mit srcset.

Bildfelder im Inhaltselement

Ein image-Platzhalter erzeugt im Inhaltselement nicht nur die Dateiauswahl, sondern dieselben Begleitfelder wie Contaos eigenes Bild-Inhaltselement. Der Redakteur hat damit bei jedem Bild die volle Kontrolle, ganz ohne Vorlagen-Änderung:

Lässt der Redakteur ein Feld leer, wird die Bildgröße in folgender Reihenfolge ermittelt: eigene Angabe im Platzhalter der Vorlage, sonst die Bildgröße der Vorlage selbst, sonst die Originalgröße der Datei. Alt-Text, Titel und Unterschrift fallen bei leerem Feld auf die Metadaten der Datei zurück.

Eigene Bildgröße im Platzhalter vorbelegen

Hat eine Vorlage mehrere Bilder mit unterschiedlichen Anforderungen, etwa ein großes Hero-Bild und ein kleines Icon, lässt sich für jeden Platzhalter eine eigene Standardgröße vorbelegen: als dritter Teil nach dem zweiten |, genauso wie bei select die Optionen. Das ist nur ein Vorschlag, der Redakteur kann ihn im Inhaltselement jederzeit überschreiben.

Das Twig-Template content_element/snippet_element.html.twig kann wie üblich überschrieben werden. Verfügbare Variablen: html (fertiges Snippet), snippet (id, name, alias) und values (Rohwerte).

Rechte

Das Backend-Modul Snippet-Vorlagen wird über die Benutzergruppen freigegeben. Da Vorlagen beliebiges HTML enthalten, sollte nur Admins oder vertrauenswürdigen Gruppen Zugriff gegeben werden. Redakteure benötigen nur Zugriff auf das Inhaltselement.

Technik

• Vorlagen liegen in tl_snippet_template.
• Das Inhaltselement speichert die Vorlagen-ID in tl_content.snippetTemplate und alle Feldwerte als JSON in tl_content.snippetData. Neue Platzhalter erfordern deshalb keine Datenbankmigration.
• Die Felder werden im config.onload von tl_content dynamisch registriert und per PaletteManipulator eingehängt.
• Die Frontend-Ausgabe wird mit contao.db.tl_snippet_template.<id> getaggt, damit der HTTP-Cache bei Änderungen an der Vorlage invalidiert wird.

Löschschutz

Eine Vorlage, die noch von Inhaltselementen verwendet wird, kann nicht gelöscht werden. Das Löschen-Icon ist dann ausgegraut, und ein Löschversuch über "Mehrere bearbeiten" wird mit einer Fehlermeldung abgebrochen.

Bekannte Grenzen

• Bedingungsblöcke mit [[if:name]] können nicht verschachtelt werden.
• Beim Wechsel der Vorlage bleiben bereits eingegebene Werte gleichnamiger Felder erhalten.