Exponential Layouts #

Lesen Sie diese Seite, wenn Sie in Exponential 6.0 Seitenlayouts bauen oder bearbeiten oder Blocktypen, View-Typen oder Abfragetypen dafür entwickeln. Exponential Layouts bringt das Konzept der Upstream-Layouts-Pakete auf den Legacy-Stack von Exponential: Ein Layout ist eine gespeicherte Anordnung von Blöcken in Zonen, und eine Regel entscheidet, welche Seiten es erhalten, sodass Redakteure Seiten umgestalten, ohne Templates anzufassen. Die erste Hälfte dieser Seite erklärt die Ideen und den Editor; die zweite Hälfte ist Referenzmaterial und Erweiterungsarbeit. Kennen Sie das System bereits, sind die Referenztabellen am Ende der Teil, zu dem Sie immer wieder zurückkehren werden.

Kurz gesagt #

Inhalt #

1. Warum es das Subsystem gibt
2. Die fünf Ideen, die Sie brauchen
3. In den Editor gelangen
4. Layouts
5. Zonen
6. Blöcke
7. Container und Verschachtelung
8. Blockparameter
9. Collections: einem Block seine Inhalte geben
10. Abfragetypen und ihre Parameter
11. Anheften: ausgewählte und dynamische Inhalte mischen
12. Regeln: entscheiden, welches Layout eine Seite erhält
13. Entwürfe, Veröffentlichen und Versionen
14. Gemeinsame Layouts und verknüpfte Zonen
15. Import, Export und Freigabelinks
16. Durchgang A: das Standarddesign anpassen
17. Durchgang B: ein neues Layout von Grund auf bauen
18. Wie das Rendern tatsächlich funktioniert
19. Das System erweitern
20. Architektur und Datenmodell
21. Fehlerbehebung
22. Referenztabellen

Warum es das Subsystem gibt #

In einer klassischen Exponential-Website ohne Layouts entscheiden Templates darüber, wie eine Seite aussieht. Die Reihenfolge der Dinge auf der Startseite zu ändern, einen Werbestreifen über der Artikelliste einzufügen oder einem Bereich der Website eine andere Seitenleiste zu geben, bedeutet jedes Mal, eine .tpl-Datei zu bearbeiten, und das bedeutet einen Entwickler, ein Deployment und ein Release.

Exponential Layouts verlagert diese Entscheidungen in die Datenbank und stellt sie hinter einen Editor. Ein Layout ist eine gespeicherte Anordnung von Inhalten; eine Regel sagt, welche Seiten es erhalten. Redakteure gestalten Seiten um, ohne Templates anzufassen, und Entwickler behalten die Kontrolle darüber, wie jedes einzelne Teil gerendert wird.

Auf die Arbeitsteilung kommt es an, und es lohnt sich, sie klar auszusprechen, weil sie alles Folgende bestimmt:

• Entwicklern gehören die Block-Templates. Wie eine „Card“ aussieht, ist eine .tpl-Datei in einem Design.
• Redakteuren gehört die Anordnung. Welche Blöcke es gibt, in welcher Reihenfolge, in welchen Zonen, mit welchen Inhalten, sind Daten.

Wenn Sie ein Template bearbeiten möchten, um etwas zu verschieben, möchten Sie wahrscheinlich eine Änderung am Layout. Wenn ein Layout etwas in einer Form rendern soll, die es noch nicht gibt, brauchen Sie einen neuen View-Typ oder Blocktyp, und das ist Entwicklerarbeit — siehe Das System erweitern.

Die fünf Ideen, die Sie brauchen #

Alles im Editor ist aus fünf Konzepten gebaut. Lernen Sie diese, und die Oberfläche erklärt sich von selbst.

Layout — eine benannte Anordnung, die auf einem Layouttyp beruht, der festlegt, wie viele Bereiche sie hat. 2 columns hat einen linken und einen rechten; Header / Main / Footer hat fünf. Der Layouttyp wird beim Anlegen gewählt und kann danach nicht geändert werden, weil die Zonen das sind, woran Blöcke hängen.

Zone — ein benannter Bereich innerhalb eines Layouts: main, sidebar, footer. Zonen kommen aus dem Layouttyp, daher legen Sie sie nie an oder löschen sie. Sie füllen sie, oder Sie verknüpfen sie mit einem anderen Layout (siehe gemeinsame Layouts).

Block — ein Element innerhalb einer Zone: ein Stück Text, ein Bild, eine Liste von Artikeln, ein Hero-Banner. Die Definition des Blocks sagt, was für eine Art Ding er ist; sein View-Typ sagt, in welcher von mehreren Formen er gerendert wird; seine Parameter konfigurieren ihn.

Collection — die Inhalte, die ein Block anzeigt, wenn er zu der Art gehört, die Inhalte anzeigt. Eine Collection ist entweder manuell (Sie wählen die Elemente aus) oder dynamisch (eine Abfrage holt sie). Nur manche Blocktypen haben eine; der Blockkatalog kennzeichnet, welche.

Regel — die Zuordnung von einer Anfrage zu einem Layout. Eine Regel zeigt auf ein Layout und trägt Ziele (für welche Anfragen sie gilt) und Bedingungen (zusätzliche Einschränkungen). Regeln haben eine Priorität; der erste Treffer gewinnt.

Ein Satz, an dem Sie sich festhalten können:

Eine Regel entscheidet, dass diese Anfrage jenes Layout erhält; die Zonen des Layouts enthalten Blöcke; ein Block kann eine Collection besitzen, die seine Inhalte liefert.

In den Editor gelangen #

Es gibt zwei Administrationsoberflächen. Sie arbeiten mit denselben Daten, daher können Sie frei zwischen ihnen wechseln.

Der SPA-Editor — der moderne, und Gegenstand des größten Teils dieses Dokuments:

/explayouts_ui_api/app

Seine JSON-API liegt darunter unter /explayouts_ui_api/app/api/.... Normalerweise rufen Sie die API nicht von Hand auf, aber zu wissen, dass es sie gibt, macht das Verhalten des Editors viel leichter nachvollziehbar, und so skripten Sie Massenänderungen.

Der ältere, formularbasierte Editor — schlichter, für ein einzelnes Feld manchmal schneller, und der Ort einiger Verwaltungsseiten, die die SPA nicht hat:

/explayouts_ui/dashboard

Er bietet: layout_list, layout_create, layout_edit, block_edit, rule_list, rule_edit, preview, components, shared_layouts_list, template_editor, transfer_import, setup.

Berechtigungen #

Beide Oberflächen prüfen die Richtlinien des Moduls explayouts über den üblichen Rolleneditor. Ein Benutzer braucht mindestens explayouts / read, um das Dashboard zu öffnen, und die Bearbeitungsfunktionen, um etwas zu ändern. Die Schlüssel für Modul und Richtlinien sind in extension/explayouts/settings/module.ini.append.php deklariert.

Lädt der Editor, aber jede Liste ist leer, prüfen Sie die Richtlinien, bevor Sie die Daten verdächtigen.

Prüfen, ob es läuft #

curl -s -o /dev/null -w '%{http_code}\n' https://<your-admin-host>/explayouts_ui_api/app
curl -s https://<your-admin-host>/explayouts_ui_api/app/api/config

Der Endpunkt config gibt das CSRF-Token zurück, das die SPA verwendet, die Editionsbezeichnung und ob das automatische Leeren des Caches eingeschaltet ist. Ein 200 von beiden bedeutet, dass Modul, Erweiterung und Datenbank in Ordnung sind.

Layouts #

Eines anlegen #

In der SPA Layouts → Create. Sie geben drei Dinge an:

Die Kennung ist wichtiger, als sie aussieht. Mit ihr fragt ein Template nach einem bestimmten Layout, und mit ihr übersteht ein Layout, dass es exportiert und anderswo wieder importiert wird. Behandeln Sie sie als dauerhaft, auch wenn sich das Feld bearbeiten lässt.

Die Layouttypen #

Zwölf werden standardmäßig mitgeliefert. Die Zonennamen in der dritten Spalte sind genau die Namen, die Sie im Editor und in Templates sehen.

layout_1, layout_2 und layout_4 sind die richtigen, wenn Sie einen ganzen Seitenrahmen bauen, weil sie Bereiche für Kopf und Fuß enthalten. Die nummerierten Spaltentypen eignen sich besser für ein Layout, das einen Inhaltsbereich füllt.

Die Wahl zwischen 1_column und layout_1 — beide haben eine einzige Zone main — hängt davon ab, welches Template sie rendert; siehe Wie das Rendern tatsächlich funktioniert.

Aktionen auf Ebene des Layouts #

Zonen #

Zonen sind durch den Layouttyp festgelegt, daher bietet der Editor keine Möglichkeit, welche hinzuzufügen oder zu entfernen. Jede Zone ist im Editor ein Ablagebereich mit der Kennung der Zone als Überschrift.

Eine Zone tut eines von zwei Dingen:

1. Sie enthält eigene Blöcke — der Normalfall. Fügen Sie ihr Blöcke hinzu, ordnen Sie sie, fertig.
2. Sie ist mit einer Zone eines gemeinsamen Layouts verknüpft — die Zone zeigt statt ihrer eigenen die Blöcke eines anderen Layouts an. Siehe Gemeinsame Layouts und verknüpfte Zonen.

Die Reihenfolge der Blöcke in einer Zone ist eine Ganzzahl position. Im Editor ziehen Sie; der Editor nummeriert neu und speichert.

Blöcke #

Ein Block wird hinzugefügt, indem Sie das Menü zum Hinzufügen einer Zone öffnen und einen Blocktyp wählen. Sechsundvierzig werden standardmäßig mitgeliefert. Statt sie alphabetisch aufzuführen, stehen sie hier danach geordnet, wofür Sie zu ihnen greifen würden.

Blockkatalog #

Text und Markup

Medien

Auflistung von Inhalten — das sind die Blöcke, die Inhalte aus der Website holen

list ist das Arbeitspferd. Mit seinen sechs View-Typen deckt ein Blocktyp die meisten Auflistungen ab; ändern Sie lieber den View-Typ, als einen anderen Block zu wählen.

full_view ist besonders: Er rendert das aktuelle Inhaltselement in seiner normalen vollständigen Ansicht. So betten Sie den eigentlichen Inhalt der Seite in ein Layout ein, und die meisten Layouts für einen Seitenrahmen brauchen genau einen davon.

Layout und Struktur

Bedienelemente

Seitenabschnitte — vorgefertigte Marketing-Abschnitte

Gestaltete Komponenten — dieselben Abschnitte mit mehreren fertigen visuellen Varianten

Die Familie ibexa_component_* gibt es, damit eine Marketing-Seite ohne Entwickler aus vorgestalteten Abschnitten zusammengesetzt werden kann. Deshalb haben sie so viele View-Typen: Wählen Sie die Stilnummer, die zur Seite passt. Die Seite Components der älteren Administration führt auf, wo jede davon in allen Layouts verwendet wird; so finden Sie jede Seite, die einen Stil verwendet, bevor Sie ihn ändern.

Templates

tpl_block rendert ein benanntes Template, das über seinen Parameter block_name gewählt wird. Es ist der Notausgang: Braucht eine Seite etwas, das kein Blocktyp abdeckt, schreibt ein Entwickler ein Template, und der Redakteur platziert es überall. Bevorzugen Sie für alles, was mehr als ein- oder zweimal verwendet wird, einen richtigen Blocktyp.

Aktionen auf Ebene des Blocks #

Jeder Block bietet im Editor:

• Edit — sein Parameterfeld öffnen
• Move — innerhalb einer Zone oder in eine andere Zone ziehen
• Duplicate — ihn kopieren, eingefügt nach dem Original
• Delete — ihn entfernen

Duplizieren ist meist schneller, als einen zweiten konfigurierten Block von Grund auf zu bauen, und es kopiert Parameter und Einstellungen der Collection mit.

Container und Verschachtelung #

Vier Blocktypen sind Container: Sie enthalten andere Blöcke, statt selbst Inhalte zu rendern. So erhalten Sie einen zweispaltigen Streifen in einer einspaltigen Zone, ohne einen neuen Layouttyp zu erfinden.

Ein Platzhalter ist für einen Container, was eine Zone für ein Layout ist: ein benannter Platz, der eine geordnete Liste von Blöcken enthält. Im Editor wird ein Container als Block mit eigenen Ablagebereichen darin dargestellt.

two_columns hat zwei View-Typen, two_columns_66_33 und two_columns_33_66, die die Aufteilung der Breite festlegen. Die Platzhalter sind in beiden Fällen dieselben — ein Wechsel des View-Typs ordnet neu an, ohne Blöcke zu verschieben.

Container lassen sich verschachteln. In der Praxis sind sie auch der wichtigste Weg, ein Layout responsiv zu machen, da die Spalten-Templates die responsiven Klassen tragen.

Eine Warnung: Tiefe Verschachtelung ist schwer zu bearbeiten und für die nächste Person schwer zu verstehen. Sind Sie drei Container tief, ist ein eigens gebauter Layouttyp oder Blocktyp meist die bessere Antwort.

Blockparameter #

Die Auswahl eines Blocks öffnet sein Parameterfeld. Parameter werden vom Handler des Blocks deklariert, daher zeigt jeder Blocktyp einen anderen Satz. Ein Block button deklariert zum Beispiel:

In den Standard-Handlern gibt es sechs Parametertypen, und das sind die einzigen Widgets, die der Editor zeichnen kann:

Neben den eigenen Parametern des Handlers trägt jeder Block:

• View-Typ — in welcher Template-Form gerendert wird, aus der Liste dieses Blocktyps
• Name — eine Beschriftung für Redakteure, um zwei ähnliche Blöcke im Baum zu unterscheiden
• CSS ID und CSS class — werden auf das umschließende Element des Blocks geschrieben

Das Feld CSS class ist die Nahtstelle zwischen Redaktions- und Designarbeit, und es ist das nützlichste Feld für Anpassungen überhaupt: Ein Entwickler liefert Utility-Klassen im Theme aus, ein Redakteur wendet sie pro Block an, und niemand muss ein Template anfassen, um einen Hintergrund oder einen Abstand zu ändern.

Collections: einem Block seine Inhalte geben #

Blöcke, die im Katalog mit Collection gekennzeichnet sind, zeigen Inhalte aus der Website an, und eine Collection sagt ihnen, welche Inhalte.

Eine Collection ist von einer von zwei Arten:

Manuell — Sie wählen jedes Element von Hand über den Inhaltsbrowser. Richtig, wenn die Inhalte bestimmt sind und sich nicht ändern: drei benannte Produkte, eine kuratierte Auswahl von fünf Artikeln.

Dynamisch — eine Abfrage holt die Elemente zur Zeit des Renderns. Richtig, wenn die Inhalte sich selbst aktuell halten sollen: die neuesten fünf Artikel in diesem Bereich, die Unterelemente dieses Knotens, alles mit diesem Thema verschlagwortete.

Beide Arten unterstützen zwei weitere Einstellungen, die nach der Abfrage gelten:

Mit dem Offset können zwei Blöcke verschiedene Ausschnitte derselben Abfrage zeigen. Ein Block „featured“ mit Limit 1 und darunter ein Block „more stories“ mit Offset 1 und Limit 6 ergeben zusammen das vertraute Muster aus Aufmacher und Liste aus einer einzigen Sortierung.

Abfragetypen und ihre Parameter #

Zwölf Abfragetypen werden standardmäßig mitgeliefert.

Das Parameterfeld lesen #

Die Parameter einer Abfrage sind gruppiert, und die Gruppierung ist Absicht. Vier Parameter gelten als grundlegend und werden zuerst gezeigt, weil fast jede Abfrage sie braucht:

• use_topic_from_current_content
• use_current_location
• sort_type
• sort_direction

Alles andere ist erweitert und eingeklappt.

Manche Parameter sind zusammengesetzt: ein Kontrollkästchen, das die Felder aufdeckt, die es steuert. Das hält das Feld kurz und, noch wichtiger, macht die Abhängigkeit sichtbar — die untergeordneten Felder bedeuten nichts, solange das übergeordnete nicht gesetzt ist.

Bei den beiden umgekehrten lohnt es sich zu verweilen, denn sie sind die Funktion, die ein Layout wiederverwendbar macht. „Use current location as parent“ bedeutet: keinen Ablageort fest eintragen — die Seite verwenden, die gerade gerendert wird. Ein einziges Layout mit einer Abfrage children und angehaktem Kästchen bedient jeden Bereich der Website: Unter /recipes führt es Rezepte auf, unter /fitness Fitness-Artikel. Entfernen Sie den Haken, erscheint ein Feld für den Ablageort, das den Block an einen Ort heftet.

Diese Unterscheidung — an die aktuelle Seite gebunden oder an eine feste geheftet — ist der Unterschied zwischen einem Layout, das Sie einmal schreiben, und einem, das Sie zwanzigmal kopieren.

Die Inhaltssuche von Exponential #

exponential_content_search ist die Abfrage für alle Zwecke, und dort liegen die Filter. Zu ihren Parametern gehören der übergeordnete Ablageort, die Sortierung und die drei zusammengesetzten Filter von oben:

• Inhaltstyp — auf gewählte Klassen beschränken, mit einem Filtermodus
• Sektion — auf gewählte Sektionen beschränken
• Objektzustand — auf gewählte Zustände beschränken

Verwenden Sie sie, wenn die einfacheren Abfragen nicht passen. Verwenden Sie children oder subtree, wenn sie passen — sie sind sechs Monate später leichter zu lesen.

Anheften: ausgewählte und dynamische Inhalte mischen #

Manuelle Elemente können einer dynamischen Collection hinzugefügt werden, und dann werden sie zu angehefteten Überschreibungen: Jedes belegt seine gespeicherte Position, und die Abfrage füllt die Plätze darum herum.

Das löst das alltägliche redaktionelle Problem, dass eine Liste sich meist selbst pflegen soll, aber ein Element diese Woche auf Position eins stehen muss. Ohne Anheften müssten Sie den ganzen Block auf manuell umstellen und daran denken, ihn später zurückzustellen.

Die Mechanik:

• Angeheftete Positionen sind innerhalb der Collection absolut, nicht relativ zu den Ergebnissen der Abfrage.
• Ein auf Position 0 angeheftetes Element steht zuerst, was immer die Abfrage zurückgibt.
• Die Ergebnisse der Abfrage überspringen die angehefteten Positionen und füllen den Rest der Reihe nach.

Ein praktischer Rat: Heften Sie so wenig wie möglich an, und schreiben Sie in das Feld Name des Blocks eine Notiz, warum, sonst versteht der nächste Redakteur nicht, warum sich Position 3 nie ändert.

Regeln: entscheiden, welches Layout eine Seite erhält #

Ein Layout tut nichts, bis eine Regel Anfragen darauf lenkt. Regeln stehen in der SPA unter Mappings und in der älteren Oberfläche unter rule_list.

Eine Regel hat:

• Ein Layout — was gezeigt wird
• Ziele — für welche Anfragen sie gilt
• Bedingungen — zusätzliche Einschränkungen, die ebenfalls erfüllt sein müssen
• Priorität — die höhere gewinnt, wenn mehrere Regeln passen
• Aktiviert — ein Schalter, damit eine Regel geparkt werden kann, ohne sie zu löschen

Regeln werden in der Reihenfolge der Priorität ausgewertet, und der erste Treffer gewinnt. Das ist die häufigste Ursache für Verwirrung überhaupt: Erscheint ein Layout nicht, gibt es sehr oft eine allgemeinere Regel mit höherer Priorität, die die Anfrage zuerst abfängt.

Ziele #

Es gibt außerdem einen Zieltyp route, deklariert, aber nicht implementiert — er passt nie. Bauen Sie nicht darauf.

subtree ist meist das, was Sie für „diesen ganzen Bereich der Website“ möchten, weil er Verschiebungen von Inhalten folgt. Ein path_prefix bricht in dem Moment, in dem ein Redakteur einen Ordner umbenennt.

Bedingungen #

Diese Verhaltensweisen sollten Sie kennen, weil man sie leicht falsch liest:

• Bei query_parameter und route_parameter bedeutet die Angabe keiner Werte: „Der Parameter muss nur vorhanden sein“. Die Angabe von Werten bedeutet, dass einer davon passen muss.
• Bei time passt ein leerer Bereich immer. Er ist für Kampagnen-Layouts gedacht, die sich selbst ein- und ausschalten.
• Ein unbekannter Bedingungstyp passt, statt fehlzuschlagen. Ein Tippfehler in einer Bedingung erweitert die Regel daher stillschweigend, statt sie auszuschalten.

Durchgearbeitetes Beispiel #

Um jedem Artikel unter /recipes ein besonderes Layout zu geben, aber nur im öffentlichen Siteaccess und nur während einer Aktion:

Regeln lassen sich auch kopieren, was der schnellste Weg ist, eine Familie fast gleicher Zuordnungen zu bauen.

Entwürfe, Veröffentlichen und Versionen #

Jedes Layout, jede Zone und jeder Block trägt einen status:

Der Editor arbeitet immer an einem Entwurf. Das Veröffentlichen kopiert die Zeilen des Entwurfs über die veröffentlichten Zeilen; die Website liest immer nur veröffentlichte Zeilen, daher ist unfertige Arbeit für Besucher nie sichtbar.

Der Ablauf:

1. Create draft aus dem veröffentlichten Layout (der Editor tut das, wenn Sie mit dem Bearbeiten beginnen).
2. Nehmen Sie Änderungen vor. Sie werden fortlaufend im Entwurf gespeichert — es gibt keinen eigenen Speicherschritt.
3. Publish, oder Discard draft, um die Änderungen zu verwerfen und die veröffentlichte Version unberührt zu lassen.

Die Ansicht Versions führt die veröffentlichten und die Entwurfsversionen eines Layouts mit ihren Zeitstempeln auf; so prüfen Sie, ob ein Entwurf aussteht, bevor Sie Arbeit übergeben.

Da Entwürfe pro Layout und nicht pro Benutzer bestehen, überschreiben sich zwei Personen gegenseitig, die gleichzeitig dasselbe Layout bearbeiten. Stimmen Sie sich ab, oder kopieren Sie das Layout und führen Sie von Hand zusammen.

Gemeinsame Layouts und verknüpfte Zonen #

Ein Layout kann als gemeinsam gekennzeichnet werden. Ein gemeinsames Layout wird keiner Anfrage über eine Regel zugeordnet; es existiert, um ausgeliehen zu werden. Jede Zone jedes anderen Layouts kann mit einer seiner Zonen verknüpft werden und rendert dann statt ihrer eigenen die Blöcke dieses Layouts.

So erhält eine Website einen Fußbereich, der einmal definiert ist. Bauen Sie ein gemeinsames Layout mit den Blöcken des Fußbereichs und verknüpfen Sie dann die Zone footer jedes Seitenlayouts damit. Ändern Sie das gemeinsame Layout, veröffentlichen Sie, und jede Seite folgt.

Regeln, die Sie kennen sollten:

• Nur veröffentlichte gemeinsame Layouts können verknüpft werden. Eine Zone zeigt nie auf den unveröffentlichten Entwurf von jemandem.
• Eine verknüpfte Zone ignoriert ihre eigenen Blöcke, solange die Verknüpfung besteht. Das Entfernen der Verknüpfung stellt sie wieder her.
• Die Seite Shared layouts der älteren Administration führt gemeinsame Layouts mit der Zahl der Zonen auf, die mit jedem verknüpft sind — prüfen Sie sie, bevor Sie eines ändern oder löschen.

Ein gemeinsames Layout ohne Verknüpfungen ist trotzdem völlig gültig; es hat nur noch niemand übernommen.

Import, Export und Freigabelinks #

Der Export erzeugt ein JSON-Dokument, das ein Layout mit seinen Zonen, Blöcken, Parametern und Collections beschreibt. Der Import nimmt dieses Dokument und legt daraus ein Layout an.

Das ist der unterstützte Weg, ein Layout zwischen Umgebungen zu bewegen — auf Staging bauen, exportieren, auf der Produktion importieren — und der vernünftige Weg, vor einer großen Umstrukturierung eine Sicherung zu behalten. So funktioniert auch die Portierung aus den Upstream-Layouts-Paketen, da die Form der Daten absichtlich nah gehalten wurde.

Kennungen reisen mit dem Export, daher braucht ein Import in eine Umgebung, die diese Kennung bereits hat, Sorgfalt.

Freigabelinks sind eine eigene Funktion. Ein Freigabelink ist ein Token, das eine Vorschau eines Layouts ohne Anmeldung an der Administration gewährt, um Arbeit jemandem zu zeigen, der kein Konto hat. Tokens werden pro Layout angelegt, aufgeführt und widerrufen.

Bei MongoDB-Installationen braucht der Freigabe-Endpunkt die Tabelle explayouts_share, die er bei der ersten Verwendung anlegt. Das funktioniert ab explayouts_ui_api v1.2.3 auf MySQL, SQLite und MongoDB; frühere Versionen erzeugten DDL nur für MySQL und meldeten Erfolg für Tokens, die sie nicht gespeichert hatten.

Durchgang A: das Standarddesign anpassen #

Das Ziel: einen Werbestreifen oben auf jeder Seite eines Bereichs hinzufügen, ohne ein Template anzufassen.

1. Finden Sie das Layout, das der Bereich bereits verwendet. Öffnen Sie Mappings und suchen Sie die Regel, deren Ziel den Bereich abdeckt. Notieren Sie das Layout, auf das sie zeigt.

2. Entscheiden Sie, ob Sie bearbeiten oder abzweigen. Bedient das Layout nur diesen Bereich, bearbeiten Sie es. Bedient es mehrere, kopieren Sie es, geben Sie der Kopie eine klare Kennung wie section_recipes und legen Sie für den Bereich eine neue Regel mit höherer Priorität an. Das Abzweigen vermeidet den klassischen Unfall, zwanzig Seiten zu ändern, während man auf drei zielt.

3. Öffnen Sie das Layout und legen Sie einen Entwurf an.

4. Fügen Sie den Streifen hinzu. Fügen Sie in der obersten Zone einen Container two_columns mit dem View-Typ two_columns_66_33 hinzu. In left fügen Sie einen Block rich_text für die Botschaft hinzu, in right einen Block button. Setzen Sie Text, Link und Ziel der Schaltfläche.

5. Gestalten Sie ihn ohne Änderung am Template. Tragen Sie eine Utility-Klasse des Themes in das Feld CSS class des Containers ein. Diesen Schritt übersehen viele — hier zu einem Template zu greifen, macht aus einer Bearbeitung von fünf Minuten ein Deployment.

6. Positionieren Sie ihn. Ziehen Sie den Container an den Anfang der Zone.

7. Vorschau ansehen, dann veröffentlichen.

8. Im Frontend prüfen. Laden Sie eine Seite des Bereichs und prüfen Sie, dass der Streifen gerendert wird und der Link funktioniert.

Soll der Streifen später auf der ganzen Website erscheinen, verschieben Sie ihn in ein gemeinsames Layout und verknüpfen Sie die Zone, statt ihn zu wiederholen.

Durchgang B: ein neues Layout von Grund auf bauen #

Das Ziel: ein Layout für eine Landingpage, einem Ablageort zugeordnet, mit einer Mischung aus kuratierten und automatischen Inhalten.

1. Legen Sie das Layout an. Layouts → Create. Typ layout_2 (Header / Main / Footer), Kennung campaign_landing, Name „Campaign landing“.

2. Kopfbereich. Verknüpfen Sie die Zone header mit Ihrem gemeinsamen Layout für den Kopfbereich, statt ihn neu zu bauen. Gibt es noch keines, ist jetzt der Moment, eines zu bauen.

3. Hero. Fügen Sie in post_header ibexa_component_hero hinzu und wählen Sie hero_style_2. Füllen Sie seine Parameter aus.

4. Kuratierte Höhepunkte. Fügen Sie in main einen Block list mit dem View-Typ grid_featured hinzu. Geben Sie ihm eine manuelle Collection und wählen Sie drei Elemente über den Inhaltsbrowser. Manuell ist hier richtig, weil die Höhepunkte einer Kampagne ausgewählt und nicht berechnet werden.

5. Automatische ergänzende Inhalte. Fügen Sie darunter eine zweite list mit dem View-Typ list hinzu. Geben Sie ihr eine dynamische Collection mit exponential_content_search:

• Entfernen Sie den Haken bei use current location und wählen Sie den Ordner der Kampagne, oder lassen Sie ihn gesetzt, wenn das Layout der Seite folgen soll, auf der es gerade ist.
• Setzen Sie den Haken bei filter by content type und wählen Sie Ihre Artikelklasse.
• Setzen Sie sort_type auf das Veröffentlichungsdatum, sort_direction absteigend.
• Setzen Sie limit auf 6.

6. Doppelungen vermeiden. Können dieselben Elemente in beiden Blöcken erscheinen, setzen Sie den Offset des zweiten Blocks so, dass er nach den Höhepunkten beginnt.

7. Ein Element anheften. Muss ein Artikel unabhängig vom Datum die automatische Liste anführen, fügen Sie ihn als manuelles Element auf Position 0 hinzu — er wird zu einer angehefteten Überschreibung, und die Abfrage füllt den Rest.

8. Fußbereich. Verknüpfen Sie pre_footer oder footer mit dem gemeinsamen Layout für den Fußbereich.

9. Ordnen Sie es zu. Legen Sie unter Mappings eine Regel an, die auf campaign_landing zeigt, mit einem Ziel node für die Landingpage der Kampagne. Fügen Sie eine Bedingung siteaccess hinzu, wenn die Website mehrere Siteaccesses hat. Geben Sie ihr eine Priorität über jeder allgemeineren Regel, die die Seite sonst abfangen würde.

10. Veröffentlichen Sie beides, das Layout und die Regel, und laden Sie dann die Seite.

Ändert sich nichts, arbeiten Sie die Fehlerbehebung durch — die übliche Antwort ist eine Regel mit höherer Priorität, die zuerst passt.

Wie das Rendern tatsächlich funktioniert #

Wer die Kette versteht, sucht Fehler viel schneller.

1. Eine Anfrage kommt an. pagelayout.tpl fragt den Resolver nach einem Layout.
2. expLayoutsResolver::resolve($path) durchläuft die aktivierten Regeln in der Reihenfolge der Priorität, prüft zuerst die Ziele, dann die Bedingungen, und gibt das erste veröffentlichte Layout zurück, das passt.
3. layout.tpl rendert den Rahmen des Layouts und wählt das Unter-Template für den Layouttyp.
4. zone.tpl rendert die Blöcke jeder Zone in der Reihenfolge ihrer Position — oder bei einer verknüpften Zone die Blöcke des gemeinsamen Layouts.
5. Jeder Block wird über das Template gerendert, das zu seiner Definition und seinem View-Typ passt.
6. Bei einem Block mit einer Collection wird diese zuerst aufgelöst: Eine dynamische Collection führt ihre Abfrage über expLayoutsDynamicCollection aus, angeheftete Elemente werden eingefügt, Offset und Limit angewendet.

Die Templates liegen in extension/explayouts/design/standard/templates/explayouts/:

• layout.tpl — äußerer Rahmen
• zone.tpl — Blöcke einer Zone, der Reihe nach
• block/*.tpl — eines pro Blockdefinition und View-Typ
• layouts/*.tpl — eines pro Layouttyp

Ein Frontend-pagelayout.tpl tut typischerweise Folgendes:

{def $layout=fetch( 'explayouts', 'resolve_layout', hash() )}
{if $layout}
    {include uri='design:explayouts/layout.tpl' layout=$layout}
{else}
    {$module_result.content}
{/if}

Der Zweig else ist wichtig: Eine Website soll auch rendern, wenn keine Regel passt.

Verfügbare Fetch-Funktionen #

Zu rules_for_node greifen Sie, wenn eine Seite das falsche Layout erhält: Es sagt Ihnen, was gepasst hat, statt Sie raten zu lassen.

Caching des Resolvers #

Der Resolver cacht die aufgelöste Regel und die Layout-ID pro Anfragepfad unter var/<VarDir>/cache/explayouts/resolver/, mit einer TTL aus explayouts.ini:

[ResolverSettings]
DefaultLayout=homepage
CacheTTL=3600

Rufen Sie expLayoutsResolver::clearCache() auf, wenn sich Regeln oder Layouts ändern. Mit eingeschaltetem automatic_cache_clear — die SPA meldet es in /api/config — erledigt das Veröffentlichen das für Sie. Ändern Sie Regeln direkt in der Datenbank, leeren Sie ihn selbst.

Das System erweitern #

Ein neuer Blocktyp #

1. Schreiben Sie eine Handler-Klasse, die getParameters() deklariert und die Felder zurückgibt, die der Editor zeichnen soll. Verwenden Sie nur die sechs unterstützten Typen.
2. Registrieren Sie ihn in explayouts.ini.append.php:

[BlockDefinition_testimonial]
Name=Testimonial
Handler=expLayoutsTestimonialBlockHandler
ViewTypes[]=default
ViewTypes[]=compact

3. Fügen Sie unter block/ ein Template pro View-Typ hinzu.
4. Erzeugen Sie die Autoloads neu und leeren Sie die Caches:

php bin/php/ezpgenerateautoloads.php -e
php bin/php/ezcache.php --clear-all --allow-root-user
systemctl restart php-fpm

Fügen Sie HasCollection=1 hinzu, wenn der Block Inhalte der Website anzeigen soll, und der Editor bietet ihm eine Collection an.

Ein neuer View-Typ für einen vorhandenen Block #

Oft ist nur eine andere Form gewünscht. Fügen Sie den View-Typ zu den ViewTypes[] des Blocks hinzu und schreiben Sie das Template. Kein PHP. Das ist viel günstiger als ein neuer Blocktyp und sollte die Standardantwort auf „Kann es auch wie X aussehen?“ sein.

Ein Container-Block #

Deklarieren Sie Platzhalter:

[BlockDefinition_split]
Name=Split
Handler=expLayoutsContainerBlockHandler
IsContainer=1
Placeholders[]=left
Placeholders[]=right
ViewTypes[]=default

Der mitgelieferte expLayoutsContainerBlockHandler reicht meist aus — Container brauchen selten eigene Logik.

Ein neuer Abfragetyp #

1. Schreiben Sie einen Handler, der die Abfrageschnittstelle implementiert, mit getParameters() für das Feld im Editor.
2. Registrieren Sie ihn:

[QueryType_most_read]
Name=Most read
Handler=expLayoutsMostReadQueryHandler

3. Erzeugen Sie die Autoloads neu und leeren Sie die Caches.

Fügen Sie einen Parameter hinzu, der nur sinnvoll ist, wenn ein anderer gesetzt ist, folgen Sie dem Muster des zusammengesetzten Kontrollkästchens, damit das Feld lesbar bleibt.

Hinweis zur Engine. Abfrage-Handler laufen auf der Datenbank, die die Website verwendet. MongoDB hat kein JOIN und kein GROUP BY, und der Treiber gibt für SQL, das er nicht übersetzen kann, ein leeres Ergebnis zurück, statt einen Fehler auszulösen. Ein mit einem Join geschriebener Handler gibt auf MongoDB daher stillschweigend nichts zurück und sieht genauso aus wie eine Abfrage ohne Treffer. Kann Ihre Website auf MongoDB laufen, verzweigen Sie nach eZDB::instance()->databaseName() === 'mongo' und lesen Sie die Collections getrennt. Mehrere mitgelieferte Handler tun genau das.

Architektur und Datenmodell #

Die Implementierung ist bewusst modular:

Tabellen #

Schemas werden für MySQL, SQLite, PostgreSQL und Oracle unter extension/explayouts/sql/<engine>/schema.sql mitgeliefert. Oracle verwendet NUMBER(11,0), CLOB und eine Sequenz plus Trigger pro Tabelle, um Auto-Increment nachzubilden.

Die JSON-API #

Die SPA spricht mit expLayoutsUIApplicationApi unter /explayouts_ui_api/app/api/. Wer die Ressourcen kennt, kann Änderungen einfach skripten:

Fehlerbehebung #

Das Layout erscheint nicht auf der Website. Prüfen Sie in dieser Reihenfolge: Ist das Layout veröffentlicht; ist die Regel aktiviert; passt eine Regel mit höherer Priorität zuerst; sind alle Bedingungen erfüllt. fetch( 'explayouts', 'rules_for_node', ... ) beantwortet das direkt. Denken Sie daran, dass ein unbekannter Bedingungstyp passt, statt fehlzuschlagen.

Änderungen im Editor sind nicht sichtbar. Wahrscheinlich sehen Sie die veröffentlichte Ausgabe an, während Sie einen Entwurf bearbeiten. Veröffentlichen Sie, oder verwenden Sie die Vorschau. Hat das Veröffentlichen nicht geholfen, leeren Sie die Caches und starten Sie PHP-FPM neu.

Ein dynamischer Block zeigt nichts. Spielen Sie die Absicht der Abfrage von Hand durch. Prüfen Sie, dass der Offset nicht hinter dem Ende der Ergebnisse liegt, dass der Filter für Inhaltstypen Klassen nennt, die existieren, und dass „use current location“ so gesetzt ist, wie Sie es beabsichtigen — ein Layout, das an einen Ablageort ohne Unterelemente geheftet ist, bleibt dauerhaft leer. Lesen Sie bei MongoDB außerdem den Hinweis zur Engine unter Das System erweitern: Eine nicht übersetzbare Abfrage gibt ein leeres Ergebnis zurück, statt einen Fehler zu melden.

Eine Liste steht in der falschen Reihenfolge. Prüfen Sie zuerst sort_type und sort_direction, suchen Sie dann nach angehefteten Elementen, die absolute Positionen halten.

Eine verknüpfte Zone zeigt nichts. Das gemeinsame Layout muss veröffentlicht sein. Ein gemeinsames Layout, das nur als Entwurf existiert, verknüpft mit nichts.

Der Editor lädt, aber jede Liste ist leer. Prüfen Sie die Richtlinien von explayouts in der Rolle des Benutzers, bevor Sie die Daten verdächtigen.

Ein Block wird ungestaltet oder roh gerendert. Wahrscheinlich fehlt das Template für diese Kombination aus Definition und View-Typ. Prüfen Sie block/ im aktiven Design, und denken Sie daran, dass Designs in der Reihenfolge von ActiveAccessExtensions durchsucht werden.

Referenztabellen #

Layouttypen #

Siehe Die Layouttypen — 12 Typen.

Blocktypen #

Siehe Blockkatalog — 46 Definitionen. Blöcke mit Collections: list, grid, gallery, slider, thumb_gallery, grid_gallery, sushi_bar, list_zigzag, list_accordion, carousel, logos.

Abfragetypen #

Siehe Abfragetypen und ihre Parameter — 12 Typen.

Regelziele #

path_prefix, path_info_prefix, path, path_regex, node, subtree. (route ist deklariert, aber nicht implementiert.)

Regelbedingungen #

siteaccess, content_type / class, query_parameter, route_parameter, time.

Widget-Typen für Parameter #

text, textarea, select, multiselect, checkbox, browse.

Wichtige Dateien #

Checkliste für die Installation #

1. Installieren Sie die Tabellen aus der SQL-Datei, die zu Ihrer Datenbank passt.
2. Aktivieren Sie explayouts und die zugehörigen Erweiterungen.
3. Erzeugen Sie die Autoloads neu: php bin/php/ezpgenerateautoloads.php -e
4. Leeren Sie die Caches und laden Sie das PHP-FPM neu, das die Website ausliefert: php bin/php/ezcache.php --clear-all --allow-root-user, dann systemctl reload <your PHP-FPM service> (starten Sie auch Velocity neu, wenn er die Website ausliefert).
5. Legen Sie unter /explayouts_ui_api/app ein Layout und eine Regel an.
6. Verbinden Sie pagelayout.tpl mit fetch( 'explayouts', 'resolve_layout', hash() ).

Migration und Gleichwertigkeit #

Die Portierung folgt der Datenform der Upstream-Layouts-Pakete, daher lässt sich ein XML/JSON-Export aus ihnen mit minimaler Umwandlung importieren. Die Unterschiede beschränken sich auf die Exponential-spezifischen Abfrage-Handler und die Rendering-Schicht der Legacy-Templates.

Verwandte Seiten #

• JSON-API des Layout-Editors (Spezifikation)
• Layout-Editor (Seite der Erweiterung) und Formular-Editor
• Der Fork von layouts-core
• Verhaltensänderungen vom Juli und August 2026
• Anleitung zu Templates und Design