Erstellen von Layout-Presets

Es gibt einen Abschnitt der YAML-Dateien für die Layout-Presets, der sich mit dem voreingestellten Bild beschäftigt. Dies ist ein wichtiger Teil der Datei, da sie das Vorschaubild erstellt, das Sie beim Durchsuchen der Administrationsoberfläche von Outlines sehen. Es kann als Kurzreferenz auf die Outline dienen und gibt Ihnen auf einen Blick einen Eindruck davon, wie das Layout aussieht, ohne den Layoutmanager besuchen zu müssen.

Gantry enthält eine Reihe dieser Bilder, aus denen Sie wählen können. Sie befinden sich im Verzeichnis SITE_ROOT/administrator/components/com_gantry5/images/layouts/ und können über einen Streamlink einfach referenziert werden. Wenn Sie beispielsweise auf die Datei 2-col-left.png in diesem Ordner verlinken möchten, verwenden Sie die URL: gantry-admin://images/layouts/2-col-left.png als Standardbild.

Sie können auch eigene Bilder hinzufügen. Nehmen wir zum Beispiel an, wir haben example.png und wollen es als voreingestelltes Bild verwenden. Wir würden es in /templates/TEMPLATE_DIR/custom/images/admin/layouts platzieren und in der YAML-Datei als gantry-media://admin/layouts/example.png referenzieren.

Erstellen einer neuen Layoutvorlage für ein neues Layout

Das Erstellen einer neuen Layoutvoreinstellung ist ziemlich einfach. Das erste, was Sie tun müssen, ist, eine neue YAML-Datei in THEME_DIR/custom/layouts zu erstellen. Für unser Beispiel werden wir diese Datei example1.yaml benennen.

Hier ist der Beispielcode, der sich in unserer neuen YAML-Datei befinden wird:

Dies ist eine grundlegende Layoutvoreinstellung, die drei Abschnitte enthält, die im ursprünglichen Styling des Themas enthalten sind (header, main, und footer), wobei ein zusätzlicher Abschnitt hinzugefügt wird (mainbottom), der nicht im ursprünglichen Design enthalten ist. Wir empfehlen nicht, neue Abschnitte hinzuzufügen, wenn Sie es nicht müssen, aber dies kann durch Hinzufügen in einem benutzerdefinierten Layout-Preset geschehen.

Sobald Sie einen neuen Sektion hinzugefügt haben, wird er ohne Styling über die Standardeinstellungen der Template hinaus angezeigt. Um Ihr eigenes Styling hinzuzufügen, müssen Sie dies über die Datei custom.scss tun, die sich in THEME_DIR/custom/scss befindet. Wenn Sie beispielsweise möchten, dass das H1-Tag eine rote Schrift ausgibt, fügen Sie die Zeile #g-mainbottom h1 {color: red;} hinzu.

Gantry-Abschnitte erscheinen in scss unter dem Tag g-(Abschnittsname). Der Hauptabschnitt wäre beispielsweise g-main. Dies geschieht, um Ihre Abschnittsnamen von anderen potenziell widersprüchlichen Stylingzuweisungen Dritter zu trennen.

So erstellen Sie einen Sidebar-Bereich

In diesem Abschnitt wird erläutert, wie Sie ein neues Layout-Preset mit doppelter Sidebar erstellen. Jeder Abschnitt der Sidebar stellt einen Block innerhalb des Grid-Containers dar, aus dem die Abschnitte Main, Sidebar 1 und Sidebar 2 bestehen. Weitere Informationen zur Funktionsweise der Sidebars finden Sie im Abschnitt Blöcke und Grids der Sidebar im Handbuch Layout Manager.

Das erste, was Sie tun müssen, ist, eine neue YAML-Datei in THEME_DIR/custom/layouts zu erstellen. Für unser Beispiel werden wir diese Datei example2.yaml benennen.

Hier ist der Beispielcode, der sich in unserer neuen YAML-Datei befinden wird:

Dies ist ein sehr einfaches Layout-Preset, das den Benutzer-Header-, Main- und Footer-Abschnitten zusätzlich zu zwei unabhängigen Sidebar-Abschnitten enthält. Jeder Abschnitt erhält sein eigenes Basis-Styling, das die Grundlage für die Platzierung zusätzlicher Partikel und Positionen bildet.

Jede horizontale Reihe muss 100% Breite aufweisen. Im obigen Beispiel werden Sie feststellen, dass main einen Breitengrad von 60% hat, gefolgt von zwei Sidebars mit jeweils 20% Breite. Es ist auch sehr wichtig, sich daran zu erinnern, dass YAML-Dateien nur durch 2 teilbare Zwischenräume und nicht Tabs unterstützen.

Überspannen einer Sidebar über mehrere Abschnitte hinweg

In diesem Abschnitt werden wir zwei YAML-Dateien demonstrieren, die einen und zwei Seitenleiste-Bereiche erstellen, die sich über mehrere Abschnitte der Website erstrecken. Dies ist nützlich, wenn Sie zusätzliche Abschnitte benötigen, wie z.B. Ihre Kopf- und Fußzeile, die sich den horizontalen Raum mit der Sidebar teilen.

Wie Sie im obigen Beispiel sehen können, haben wir mehrere Abschnitte verschachtelt, einschließlich header, navigation, messages, und footer im gleichen horizontalen Bereich wie der Seitenabschnitt (aside), der als Seitenleiste fungiert.

Im folgenden Beispiel sehen Sie ein voreingestelltes Zwei-Seitenleisten-Layout YAML mit einer Seitenleiste links und einem Seitenabschnitt rechts von mehreren Sektionen.

Syntax Guide

Es gibt fünf Hauptregeln, die Sie beim Erstellen einer Layoutvoreinstellung beachten sollten.

1. Stufeninhalte sind als Gitter - grid - block - grid - block - grid - block geordnet. Das Raster ist eine Zeile und der Block eine Spalte. Siehe die früheren Beispiele.
2. foo: erstellt einen Abschnitt. wrapper-foo: erstellt einen Wrapper. container-foo: erstellt einen Container. Der Name muss im Layout eindeutig sein.
3. Das Hinzufügen von Schrägstrichen (Beispiel: /foo/:) ermöglicht es Ihnen, die Einstellungen für das Abschnittslayout zu nutzen, um die Flexibilität des Stylings zu erhöhen.
4. Mehrere Partikel in einer Reihe können auch in [ ] Klammern gesetzt werden. Beispiel: - [logo, menu]
5. Sie benötigen keine Klammern oder zusätzlichen Bindestriche für Einzelpartikelreihen. Beispiel: - menu ist die Abkürzung von - [menu].

Allgemeine YAML-Items

Item	Beschreibung
system-messages	Fügt eine Position für Systemmeldungen ein, die Systemmeldungen am Frontend anzeigt.
system-content	In dieser Zeile werden die Inhalte auf der vom CMS bereitgestellten Seite angezeigt. Es ist der Content-Body.
position-	Direkt gefolgt von einem Positionsnamen (Beispiel:position-header) wird eine Position angelegt und mit dem Vornamen versehen.
version	Dies zeigt die verwendete Gantry YAML-Version an. So wurde beispielsweise die Version 2 mit Gantry 5.2 eingeführt.

Hinzufügen eines Abschnitts zu einer bestehenden Layout-Voreinstellung

Es gibt zwei Möglichkeiten, einen Abschnitt zu einer bestehenden Layoutvoreinstellung hinzuzufügen. Die erste gilt für Layout-Presets, die bereits in Ihrem THEME_DIR/custom Verzeichnis vorhanden sind.

Sie können das benutzerdefinierte Preset direkt bearbeiten oder seine YAML-Datei duplizieren und das Duplikat bearbeiten, wenn Sie das aktuelle Preset beibehalten und ein anderes mit einer kleinen Änderung verwenden möchten.

Nehmen wir also an, Sie haben eine Datei namens example1.yaml in Ihrem THEME_DIR/custom Verzeichnis. Und diese Datei enthält folgendes:

Diese Layoutvoreinstellung legt header, main, und footer fest. Aber, sagen wir, du wolltest einen neuen Abschnitt zwischen Haupt- und Fußzeile namens mainbottom hinzufügen. Dies zu tun ist unglaublich einfach. Fügen Sie einfach folgendes zwischen dem main und dem footer Bereich der Datei hinzu:

Sobald dies erledigt ist und die Datei gespeichert ist, aktualisieren Sie Ihren Layout-Manager und laden Sie die Voreinstellung. Ihre Änderung sollte erscheinen.

Sie können auch einen Abschnitt zu einem bestehenden Layout mit einem sehr ähnlichen Prozess hinzufügen. Sie müssen nur die YAML-Datei des Layouts vom ursprünglichen Speicherort kopieren und in Ihr /custom Verzeichnis legen. Sie können beispielsweise THEME_DIR/layouts/default.yaml kopieren und die Kopie in das Verzeichnis THEME_DIR/xxx/default.yaml legen und Ihre Änderungen an der Kopie vornehmen.

Struktur

Es gibt einen weiteren Abschnitt in der YAML-Datei einer Layoutvorlage, der die Struktur des Layouts festlegt. Dies ist der Strukturbereich. In diesem Abschnitt werden die strukturellen Eigenschaften Ihres Layouts festgelegt. Es sind die Bits und Stücke, die nicht im Hauptlayoutbereich definiert werden können, in dem Sie zunächst Ihre Abschnitte erstellen und Partikel zuweisen.

Die Struktur eines YAMLs lässt viel Raum für die Zuordnung neuer Eigenschaften zu praktisch jedem Element in der Struktur des Layouts. Beispielsweise können Sie das Verhalten eines Abschnitts mithilfe der Struktureigenschaften ändern, wie z.B. den Typ eines Abschnitts in ein div und nicht in sein Standardverhalten: Abschnitt.

Es gibt fünf verschiedene Arten von Eigenschaften: ID, Titel, Typ, Subtyp und Attribute. Die einem Abschnitt zugewiesene ID bestimmt seine Tags. Beispielsweise wird eine id von foo als <section id="foo"> im Frontend angezeigt. Die id ist eine intern verwendete Funktion, die nicht manuell geändert werden sollte.

Die title-Eigenschaft ermöglicht es Ihnen, einen Titel für die Sekunde festzulegen, wie er im Backend erscheint. Beispielsweise können Sie den Abschnitt wie folgt einrichten:

Und es wird als Main im Backend erscheinen, wie unten abgebildet:

Attribute sind die Änderungen, die in den Einstellungen des Abschnitts im Portal-Administrator vorgenommen wurden. Wenn Sie beispielsweise die Abschnittseinstellungen im Gantry-Administrator wie folgt festlegen:

Sie erscheint in der benutzerdefinierten YAML-Datei wie folgt:

Hier ist eine Liste der Struktureigenschaften, mit denen Sie den Typ und den Subtyp eines Abschnitts definieren können:

Type	Beschreibung
block	Dies ist der Container des Partikels. Im Admin-Bereich wird es in den Einstellungen der einzelnen Partikel als Registerkarte Block angezeigt.
container	Ein Container wird verwendet, um mehrere Abschnitte aufzunehmen, wie z.B. einen Hauptkörper und eine sidebar/aside.
grid	Ein Grid ist im Wesentlichen die Zeile. Jede Zeile kann mehrere Blöcke enthalten. Es definiert die Eigenschaften einer bestimmten Zeile.
offcanvas	Offcanvas beschreibt den Bereich, in dem sich das mobile Menü befindet.
section	Ein Abschnitt enthält Zeilen (Grids), die Blöcke mit Partikeln enthalten. Es sind die großen weißen Blöcke, die im Admin auftauchen. Häufig verwendete Namen wie Header, Footer, Mainbody, und Sidebar.
wrapper	Ein Wrapper ist im Admin nicht zu sehen. Es ist im Layout nicht erforderlich, kann aber optional zur Unterstützung des Stylings verwendet werden. Wenn Sie beispielsweise mehrere Abschnitte haben, die Sie ein einzelnes Hintergrundbild durchgängig überspannen möchten, können Sie dies mit einem Wrapper tun.

Subtypen

• article
• aside
• div
• footer
• header
• main
• nav
• section

Subtypen sind im Wesentlichen HTML-Tags, die den Inhalt Ihrer Seite definieren. Es handelt sich um thematische Gruppierungen, die Browsern und Webcrawlern sagen, was Inhalte sind. Beispielsweise würde ein Artikel innerhalb von  <article></article> Tags definiert werden.

Subtypen werden nur für den Abschnitt verwendet. Wenn Sie einen Abschnitt als Abschnitt(section) definiert haben, werden die anderen Subtypen nicht verwendet.

Hier ist ein kurzes Beispiel für einen Abschnitt, der diese strukturellen Eigenschaften verwendet, um den Abschnitt weiter anzupassen.

Im obigen Beispiel sehen wir zwei Abschnitte: Kopf und Navigation. Der Kopf wurde mit einem alternativen Titel des Hauptkopfes versehen. Es wird im HTML als < header > angezeigt. Wir mussten den Header-Subtyp nicht zuordnen, da der Name des Abschnitts selbst header ist. Es erledigt dies automatisch für uns.

Der Navigationsabschnitt wurde mit dem Subtyp Nav versehen. Wir haben auch den Titel geändert, wie wir es im Kopfbereich getan haben, so dass er als Hauptnavigation im Gantry-Administrator erscheint. Die HTML-Tags des Frontends erscheinen als < nav id="g-navigation" >, die den definierten Subtyp und die Standard-ID verwendet.

Inhalt (content)

Der Inhaltsbereich der YAML-Datei ist im Wesentlichen der Speicherort für beliebige Partikelattribute. Als Beispiel haben wir ein Datumspartikel erstellt und die Einstellungen für Partikel und Block angepasst:

So wird dies im Content-Bereich der YAML-Datei dargestellt:

Beachten Sie, dass Sie alle Block-Einstellungen in das block Attribut einfügen können.

Benannte Grids und Blöcke

Manchmal ist es notwendig, ein benanntes Gitter oder einen Block hinzuzufügen, um eine ID oder eine Klasse daran anzuhängen.

Beachten Sie, dass Sie Bindestriche und benannte Schlüssel nicht mischen können. Wenn Sie also nicht alle Grids benennen möchten, verwenden Sie stattdessen eindeutige (oder wachsende) Ganzzahlen als die anderen Schlüssel.

Sie können das Gleiche auch mit Blöcken tun, aber es wird selten benötigt, da Sie die Blockattribute in Abschnitt und Partikel einfügen können.

Vererbung / Inheritance

Ab Gantry 5.3 gibt es ein neues Vererbungsattribut für Abschnitte und Partikel.

Die Vererbung von Abschnitten ist etwas einfacher, da sie nur die Attribute umfasst und beinhaltet:

Die Partikelvererbung hat einen zusätzlichen Parameter, um festzulegen, von welchem Partikel sie übernommen werden soll:

YAML-Versionen

Als sich Gantry 5 weiterentwickelte, wollten wir das Layout der YAML-Dateien leichter lesbar und nutzbar machen. Durch die Vereinfachung der Syntax, das Entfernen von Partikel-Tags und die Vereinfachung der Verwaltung von Abschnitten konnten wir eine bessere Benutzerfreundlichkeit schaffen. Diese Änderungen wurden in Gantry 5.2 und späteren Versionen umgesetzt.

Da dieses Update YAML-Dateien, die mit dem ursprünglichen YAML-Stil erstellt wurden, beschädigen würde, haben wir uns für eine Versionsbezeichnung entschieden, die Gantry darüber informiert, welcher YAML-Stil in einer bestimmten Datei verwendet wird.

Kurz gesagt, jede YAML-Voreinstellungsdatei, die nach Gantry 5.2 mit dem neuen (aktuellen) YAML-Stil erstellt wurde, sollte die Version: 2 als erste Zeile haben. Andernfalls verwendet Gantry standardmäßig die ursprüngliche YAML-Syntax.