Wie erstelle ich Design-Bausteine? (Tutorial)

Ein Block ist wie ein fertiger, vorgefertigter Baustein für eine Inhaltsseite. Das kann ein Textabschnitt sein, ein Bild, eine Überschrift oder eine Bildergalerie. Sie platzieren diesen "Baustein" einfach an die Stelle, wo Sie ihn haben möchten, und füllen ihn mit Ihren Inhalten. Jeder Block hat seine eigene Form und Funktion.

Um Ihre Block-Definitionen auf einer Cloudrexx Website zu integrieren, benötigen Sie eine FTP-Verbindung.

1. Öffnen Sie Ihren bevorzugten FTP-Client (z.B. FileZilla, Cyberduck, Transmit).

2. Verbinden Sie sich mit Ihrer Cloudrexx Website (siehe https://cloudrexx.atlassian.net/wiki/spaces/HELP/pages/468585430).

3. Navigieren Sie zu den Verzeichnissen für Definitionen. Dies sind die relevanten Orte, an denen Ihre Dateien abgelegt werden müssen. Für Blöcke ist dies der Pfad /media/private/BlockEditor/Blocks/.

Beginnen wir mit der absoluten Minimaldefinition eines Blocks – der YAML-Definition. Dies ist der Kern, der dem Block Editor mitteilt, dass ein neuer Block verfügbar ist.

1. Erstellen Sie eine neue Datei auf Ihrem lokalen Computer mit dem Namen meinErsterBlock.html.

2. Fügen Sie den folgenden Inhalt in meinErsterBlock.html ein:

   <script type="text/yaml"> apiVersion: 1.0 identifier: meinErsterBlock name: de: "Mein Erster Block" en: "My First Block" </script>

3. Überprüfen Sie die YAML-Syntax sorgfältig!

   • Stellen Sie sicher, dass die Einrückungen (Spaces, keine Tabs!) korrekt sind. YAML ist sehr empfindlich gegenüber Einrückungen.

   • Der identifier muss eindeutig sein (siehe identifier der Standard-Blocktypen) und darf nur Buchstaben (A-Z, a-z), Zahlen (0-9), Unterstriche (_) und Bindestriche (-) enthalten.

   • Die Angabe des englischen (en) name ist zwingend notwendig.

4. Laden Sie meinErsterBlock.html per FTP in das Verzeichnis /media/private/BlockEditor/Blocks/ hoch.

Nach dem Hochladen der minimalen Block-Definition ist es an der Zeit zu überprüfen, ob der Block im Block Editor erkannt wird.

1. Melden Sie sich im Backend Ihrer Cloudrexx Website an.

2. Navigieren Sie zum Content Manager.

3. Öffnen Sie eine bestehende Seite oder erstellen Sie eine neue, die den Block Editor verwendet.

4. Suchen Sie nach Ihrem Block:

   • Klicken Sie im Block Editor auf die Schaltfläche zum Hinzufügen eines neuen Blocks.

   • Suchen Sie in der Liste der Individuelle Blocktypen nach "Mein Erster Block" (oder den von Ihnen definierten Namen).

Erwartetes Ergebnis: Sie sollten "Mein Erster Block" in der Liste der verfügbaren Blöcke sehen. Wenn nicht, prüfen Sie den Abschnitt Häufige Probleme & Fehlerbehebung.

Der Block wird jetzt erkannt, aber er hat noch keinen visuellen Inhalt. Fügen wir ein einfaches HTML-Template hinzu, damit Sie sehen können, wie der Block im Editor angezeigt wird.

1. Bearbeiten Sie meinErsterBlock.html auf Ihrem lokalen Computer.

2. Fügen Sie ein <template>-Abschnitt unterhalb der YAML-Definition ein. Ihre Block-Definition sollte nun wie folgt aussehen:

   <script type="text/yaml"> apiVersion: 1.0 identifier: meinErsterBlock name: de: "Mein Erster Block" en: "My First Block" </script> <template class="frontend backend"> <p>Dies ist das HTML-Template meines ersten Blocks.</p> </template>

3. Laden Sie die aktualisierte meinErsterBlock.html per FTP erneut hoch und überschreiben Sie die bestehende Datei.

4. Überprüfen Sie im Content Manager:

   • Aktualisieren Sie den Browser-Tab mit dem geöffneten Block Editor im Cloudrexx Backend.

   • Fügen Sie "Mein Erster Block" erneut zu Ihrer Seite hinzu.

Erwartetes Ergebnis: Sie sollten den Text "Dies ist das HTML-Template meines ersten Blocks." direkt im Block Editor sehen.

Um den Block dynamisch und anpassbar zu machen, fügen wir einen Parameter hinzu, den der Benutzer im Editor bearbeiten kann. Wir erstellen einen einfachen Text-Parameter für eine Überschrift.

1. Bearbeiten Sie meinErsterBlock.html und erweitern Sie die YAML-Definition um den params-Bereich:

   <script type="text/yaml"> apiVersion: 1.0 identifier: meinErsterBlock name: de: "Mein Erster Block" en: "My First Block" params: headline: name: de: "Überschrift" en: "Headline" type: string default: "Standard-Überschrift" </script> <template class="frontend backend"> <h2>func_editor_attr(`headline`)</h2> <p>Dies ist das HTML-Template meines ersten Blocks.</p> </template>

   • Wir haben einen Parameter namens headline vom Typ "string" hinzugefügt und einen Standardwert (default) gesetzt.

   • Im <template>-Abschnitt verwenden wir func_editor_attr(`headline`), um den Wert des Parameters an dieser Stelle auszugeben.

2. Laden Sie die aktualisierte meinErsterBlock.html per FTP erneut hoch.

3. Überprüfen Sie im Content Manager:

   • Aktualisieren Sie den Browser-Tab mit dem geöffneten Block Editor im Cloudrexx Backend.

   • Fügen Sie "Mein Erster Block" erneut zu Ihrer Seite hinzu - falls Sie die Seite bisher nicht gespeichert haben.

   • Wählen Sie Ihren Block im Editor aus. Sie sollten nun in der Seitenleiste ein Feld mit der Beschriftung "Überschrift" sehen.

   • Ändern Sie den Text in diesem Feld und beobachten Sie, wie sich die Überschrift direkt im Editor aktualisiert.

Erwartetes Ergebnis: Ihr Block zeigt eine anpassbare Überschrift im Editor an.

Manchmal möchten Sie bestimmte HTML-Teile nur anzeigen, wenn ein Parameter einen bestimmten Wert hat (z.B. ein Checkbox-Parameter ist aktiviert). Dies ist ideal für optionale Elemente.

1. Fügen Sie einen neuen Parameter vom Typ “bool” (Checkbox) zu Ihrer YAML-Definition hinzu und nutzen Sie func_editor_if_attr() in Ihrem Template.

   <script type="text/yaml"> apiVersion: 1.0 identifier: meinErsterBlock name: de: "Mein Erster Block" en: "My First Block" params: headline: name: de: "Überschrift" en: "Headline" type: string default: "Standard-Überschrift" showDescription: name: de: "Beschreibung anzeigen?" en: "Show Description?" type: bool default: true </script> <template class="frontend backend"> <h2>func_editor_attr(`headline`)</h2> func_editor_if_attr(`showDescription`, `Optionale Beschreibung`) <p>Dies ist das HTML-Template meines ersten Blocks.</p> </template>

   • Wir haben den Parameter showDescription vom Typ bool hinzugefügt, der standardmässig true ist.

   • Mit func_editor_if_attr(`showDescription`, `...`) wird der als zweites Argument definierte HTML-Code nur angezeigt, wenn showDescription auf true gesetzt ist.

2. Laden Sie die aktualisierte meinErsterBlock.html per FTP erneut hoch.

3. Überprüfen Sie im Content Manager:

   • Aktualisieren Sie die Seite. Sie sollten die optionale Beschreibung sehen. Wählen Sie den Block aus und finden Sie die Checkbox "Beschreibung anzeigen?". Deaktivieren Sie sie, und die Beschreibung sollte sofort verschwinden.

Erwartetes Ergebnis: Sie können die Sichtbarkeit von HTML-Teilen Ihres Blocks über Parameter steuern.

Für interaktive Elemente oder komplexere Logik können Sie JavaScript hinzufügen. Wir fügen ein einfaches Skript hinzu, das bei der Einfügung des Blocks einen Hinweis-Dialog anzeigt.

1. Bearbeiten Sie meinErsterBlock.html und fügen Sie einen <script>-Bereich für JavaScript hinzu:

   <script type="text/yaml"> apiVersion: 1.0 identifier: meinErsterBlock name: de: "Mein Erster Block" en: "My First Block" params: headline: name: de: "Überschrift" en: "Headline" type: string default: "Standard-Überschrift" showDescription: name: de: "Beschreibung anzeigen?" en: "Show Description?" type: bool default: true init: type: bool hidden: true default: false </script> <template class="frontend backend"> <h2>func_editor_attr(`headline`)</h2> func_editor_if_attr(`showDescription`, `Optionale Beschreibung`) <p>Dies ist das HTML-Template meines ersten Blocks.</p> </template> <script class="backend"> // JavaScript für das Backend (Editor) init(api, block) { if (block.getParam('init')) { return; } this.setParam( 'init', true ); cx.ui.dialog({ title: 'Hinweis', content: 'Das ist ein Hinweis zu unserem Block', }); } </script>

   • Die init(api, block)-Methode wird aufgerufen, wenn der Block im Editor initialisiert wird.

   • Wir haben einen neuen versteckten Parameter (hidden) init hinzugefügt, um unseren Code nur einmalig ausführen zu lassen.

   • Mit block.getParam('init') fragen wir den Wert des Parameters init ab.

   • Mit this.setParam() wird der Wert eines Parameters gesetzt.

   • Wichtiger Hinweis: Das Attribut class="backend" ist entscheidend, damit dieses Skript nur im Backend (Block Editor) ausgeführt wird.

2. Laden Sie die aktualisierte meinErsterBlock.html per FTP erneut hoch.

3. Überprüfen Sie im Content Manager:

   • Aktualisieren Sie den Browser-Tab mit dem geöffneten Block Editor im Cloudrexx Backend.

   • Fügen Sie "Mein Erster Block" zu Ihrer Seite hinzu oder entfernen Sie ihn und fügen Sie ihn erneut hinzu.

Erwartetes Ergebnis: Sie sollten nun einen Hinweis angezeigt erhalten. Dies bestätigt, dass Ihr JavaScript erfolgreich geladen und ausgeführt wurde.

Fügen wir ein <style>-Tag hinzu, um den Block zu stylen.

1. Bearbeiten Sie meinErsterBlock.html und fügen Sie einen <style>-Bereich hinzu:

   <script type="text/yaml"> apiVersion: 1.0 identifier: meinErsterBlock name: de: "Mein Erster Block" en: "My First Block" params: headline: name: de: "Überschrift" en: "Headline" type: string default: "Standard-Überschrift" showDescription: name: de: "Beschreibung anzeigen?" en: "Show Description?" type: bool default: true init: type: bool hidden: true default: false </script> <template class="frontend backend"> <div class="block-meinErsterBlock"> <h2>func_editor_attr(`headline`)</h2> func_editor_if_attr(`showDescription`, `Optionale Beschreibung`) <p>Dies ist das HTML-Template meines ersten Blocks.</p> </div> </template> <script class="backend"> // JavaScript für das Backend (Editor) init(api, block) { if (block.getParam('init')) { return; } this.setParam( 'init', true ); cx.ui.dialog({ title: 'Hinweis', content: 'Das ist ein Hinweis zu unserem Block', }); } </script> <style class="frontend backend"> .block-meinErsterBlock { border: 1px dashed #ccc; padding: 15px; margin-bottom: 20px; background-color: #f9f9f9; } .block-meinErsterBlock h2 { color: #336699; font-size: 2em; margin-bottom: 10px; } </style>

   • Wir haben im <template>-Abschnitt ein umhüllendes <div>-Tag mit der CSS-Klasse block-meinErsterBlock hinzugefügt, um es mit CSS ansprechen zu können.

   • Beachten Sie class="frontend backend" im <style>-Tag. Dies bedeutet, dass dieses Styling sowohl im Backend (Block Editor) als auch im Frontend (Live-Seite) angewendet wird.

2. Laden Sie die aktualisierte meinErsterBlock.html per FTP erneut hoch.

3. Überprüfen Sie im Content Manager:

   • Aktualisieren Sie den Browser-Tab mit dem geöffneten Block Editor im Cloudrexx Backend.

   • Fügen Sie "Mein Erster Block" erneut zu Ihrer Seite hinzu - falls Sie die Seite bisher nicht gespeichert haben.

   • Sie sollten nun sehen, dass Ihr Block im Editor mit dem hinzugefügten Rahmen, Polsterung und blauer Überschrift formatiert ist.

Erwartetes Ergebnis: Der Block erscheint im Editor gestylt.

Ein mächtiges Feature ist die Möglichkeit, Blöcke ineinander zu verschachteln. Dies ermöglicht komplexe Layouts und wiederverwendbare Komponenten.

1. Bearbeiten Sie meinErsterBlock.html und ersetzen Sie die optionale Beschreibung im <template>-Abschnitt durch die Funktion func_editor_block() wie im folgenden Beispiel:

   <script type="text/yaml"> apiVersion: 1.0 identifier: meinErsterBlock name: de: "Mein Erster Block" en: "My First Block" params: headline: name: de: "Überschrift" en: "Headline" type: string default: "Standard-Überschrift" showDescription: name: de: "Beschreibung anzeigen?" en: "Show Description?" type: bool default: true init: type: bool hidden: true default: false </script> <template class="frontend backend"> <div class="block-meinErsterBlock"> <h2>func_editor_attr(`headline`)</h2> func_editor_if_attr( `showDescription`, `func_editor_block( `description`, `paragraph`, `{"content": "Optionale Beschreibung"}` )` ) <p>Dies ist das HTML-Template meines ersten Blocks.</p> </div> </template> <script class="backend"> // JavaScript für das Backend (Editor) init(api, block) { if (block.getParam('init')) { return; } this.setParam( 'init', true ); cx.ui.dialog({ title: 'Hinweis', content: 'Das ist ein Hinweis zu unserem Block', }); } </script> <style class="frontend backend"> .block-meinErsterBlock { border: 1px dashed #ccc; padding: 15px; margin-bottom: 20px; background-color: #f9f9f9; } .block-meinErsterBlock h2 { color: #336699; font-size: 2em; margin-bottom: 10px; } </style>

   • Als erstes Argument zur Funktion func_editor_block() setzen wir als Identifikator den Wert description. Der Identifikator ist frei wählbar, darf innerhalb der Block-Definition aber nur einmal verwendet werden. Erlaubte Zeichen sind: A-Z, a-z, 0-9, _ und -.

   • Als zweites Argument wählen wir den zu integrierenden Blocktyp. In unserem Fall ein paragraph.

   • Als drittes Argument setzen wir den Parameter content des Blocktyps paragraph auf den bisherigen Text "Optionale Beschreibung".

2. Laden Sie die aktualisierte meinErsterBlock.html per FTP erneut hoch.

3. Überprüfen Sie im Content Manager:

   • Aktualisieren Sie die Seite. Der Text "Optionale Beschreibung" sollte nun bearbeitbar sein.

Erwartetes Ergebnis: Sie können innerhalb Ihres Blocks andere Blöcke hinzufügen.

Neben einzelnen Blöcken kann auch eine Blockauswahl integriert werden. Dadurch kann der Benutzer weitere Blöcke aus einer konfigurierbaren Auswahl hinzufügen.

1. Bearbeiten Sie meinErsterBlock.html und ersetzen Sie im <template>-Abschnitt den <p>-Tag mit der Funktion func_editor_block() mit gesetztem Blocktyp editor:

   <script type="text/yaml"> apiVersion: 1.0 identifier: meinErsterBlock name: de: "Mein Erster Block" en: "My First Block" params: headline: name: de: "Überschrift" en: "Headline" type: string default: "Standard-Überschrift" showDescription: name: de: "Beschreibung anzeigen?" en: "Show Description?" type: bool default: true init: type: bool hidden: true default: false </script> <template class="frontend backend"> <div class="block-meinErsterBlock"> <h2>func_editor_attr(`headline`)</h2> func_editor_if_attr( `showDescription`, `func_editor_block( `description`, `paragraph`, `{"content": "Optionale Beschreibung"}` )` ) func_editor_block( `links`, `editor`, `{"link": {"min": 0, "max": 3}}` ) </div> </template> <script class="backend"> // JavaScript für das Backend (Editor) init(api, block) { if (block.getParam('init')) { return; } this.setParam( 'init', true ); cx.ui.dialog({ title: 'Hinweis', content: 'Das ist ein Hinweis zu unserem Block', }); } </script> <style class="frontend backend"> .block-meinErsterBlock { border: 1px dashed #ccc; padding: 15px; margin-bottom: 20px; background-color: #f9f9f9; } .block-meinErsterBlock h2 { color: #336699; font-size: 2em; margin-bottom: 10px; } </style>

   • Wir haben den <p>-Tag durch eine Auswahl von Links ersetzt.

   • Durch setzen des Blocktyps (zweiten Argument zu func_editor_block()) auf editor wird eine Block-Auswahl definiert, welche im dritten Argument spezifiziert wird.

   • Mit {"link": {"min": 0, "max": 3}} definieren wir, dass der Benutzer bis zu drei Link-Blöcke einfügen kann.

2. Laden Sie die aktualisierte meinErsterBlock.html per FTP erneut hoch.

3. Überprüfen Sie im Content Manager:

   • Aktualisieren Sie die Seite. Sie sollten nun bis zu drei Links einfügen können.

Erwartetes Ergebnis: Sie können innerhalb Ihres Blocks eine Block-Auswahl integrieren.

Bisher haben wir uns hauptsächlich auf den Backend-Modus (den Editor) konzentriert. Jetzt ist es an der Zeit, den Unterschied zum Frontend zu verstehen und zu überprüfen, wie der Block auf der Live-Website aussieht.

Unterschied zwischen Frontend und Backend:

• class="backend": Code wird nur im Backend (Block Editor) geladen und ausgeführt. Dies ist nützlich für Editor-spezifische UI-Elemente oder Logik.

• class="frontend": Code wird nur auf der tatsächlichen Webseite (Frontend) geladen und ausgeführt. Hier sollte Ihr produktiver Code liegen.

• class="frontend backend": Code wird sowohl im Backend (Block Editor) als auch auf der Live-Seite (Frontend) geladen. Ideal für allgemeines Styling und grundlegende Skripte.

• Kein class-Attribut: Der Inhalt des Tags wird ignoriert.

1. Passen Sie Ihr HTML-Template an, um den Unterschied zwischen Backend- und Frontend-Ansicht zu verdeutlichen:

   <script type="text/yaml"> apiVersion: 1.0 identifier: meinErsterBlock name: de: "Mein Erster Block" en: "My First Block" params: headline: name: de: "Überschrift" en: "Headline" type: string default: "Standard-Überschrift" showDescription: name: de: "Beschreibung anzeigen?" en: "Show Description?" type: bool default: true init: type: bool hidden: true default: false </script> <template class="frontend"> <div class="block-meinErsterBlock"> <h2>func_editor_attr(`headline`)</h2> func_editor_if_attr( `showDescription`, `func_editor_block( `description`, `paragraph`, `{"content": "Optionale Beschreibung"}` )` ) func_editor_block( `links`, `editor`, `{"link": {"min": 0, "max": 3}}` ) </div> </template> <template class="backend"> <div class="block-meinErsterBlock"> <p style="color: grey; font-style: italic;">(Diesen Hinweis sehen Sie nur im Editor)</p> <h2>func_editor_attr(`headline`)</h2> func_editor_if_attr( `showDescription`, `func_editor_block( `description`, `paragraph`, `{"content": "Optionale Beschreibung"}` )` ) func_editor_block( `links`, `editor`, `{"link": {"min": 0, "max": 3}}` ) </div> </template> <script class="backend"> // JavaScript für das Backend (Editor) init(api, block) { if (block.getParam('init')) { return; } this.setParam( 'init', true ); cx.ui.dialog({ title: 'Hinweis', content: 'Das ist ein Hinweis zu unserem Block', }); } </script> <style class="frontend backend"> .block-meinErsterBlock { border: 1px dashed #ccc; padding: 15px; margin-bottom: 20px; background-color: #f9f9f9; } .block-meinErsterBlock h2 { color: #336699; font-size: 2em; margin-bottom: 10px; } </style>

   Wir haben jetzt zwei separate <template>-Tags. Eines fürs Frontend (<template class="frontend">) und eines fürs Backend (<template class="backend">). Jenes fürs Backend enthält einen Hinweis.

2. Laden Sie die aktualisierte meinErsterBlock.html per FTP erneut hoch.

3. Überprüfen Sie im Content Manager und in der Seitenvorschau:

   • Im Backend (Editor): Aktualisieren Sie die Seite. Sie sollten den Text "(Das ist ein Hinweis zu unserem Block)" sehen.

   • In der Seitenvorschau (Frontend): Klicken Sie auf die Vorschau-Funktion.

   • Im Vorschaufenster sollte der Hinweis nicht angezeigt werden.

Erwartetes Ergebnis: Der Block zeigt unterschiedlichen Inhalt, je nachdem, ob er im Editor oder in der Frontend-Vorschau betrachtet wird.

Sie haben nun erfolgreich die Grundlagen des Block Editors gemeistert! Um Ihre Kenntnisse zu vertiefen und noch komplexere Elemente zu erstellen, können Sie Folgendes erkunden:

• Erweiterte Parametertypen:

  • Der list-Typ erlaubt Ihnen, Listen von Werten oder sogar Listen von komplexeren Objekten als Parameter zu definieren, was für wiederholbare Inhalte (z.B. eine Liste von Links oder Bildern) unerlässlich ist.

  • Nutzen Sie die bounds-Direktive bei Parametern, um Validierungsregeln festzulegen:

    • validator: Für reguläre Ausdrücke zur Überprüfung von Strings.

    • upper/lower: Für numerische Begrenzungen.

    • validValues: Für vordefinierte Auswahlmöglichkeiten.

• Komplexere JavaScript-Interaktionen:

  • Erkunden Sie die vollständige API, die Ihnen über das api-Objekt in Ihren Backend-JavaScript-Klassen zur Verfügung steht. Damit können Sie auf Block-Daten zugreifen, Blöcke manipulieren oder sogar mit anderen Blöcken auf der Seite interagieren.

• Best Practices für die Entwicklung:

  • Modularität: Halten Sie Ihre Blöcke spezifisch und wiederverwendbar.

  • Performance: Achten Sie auf die Performance Ihrer Blöcke, insbesondere des Frontend-Codes (minimieren Sie JS und CSS, die nicht unbedingt benötigt werden).

  • Barrierefreiheit (Accessibility): Stellen Sie sicher, dass Ihre Blöcke auch für Benutzer mit Einschränkungen gut bedienbar sind.

Viel Erfolg beim Entwickeln Ihrer eigenen Blöcke!

Sollten Sie auf Probleme stossen, überprüfen Sie die folgenden Punkte:

• Block erscheint nicht im Editor:

  • Falscher Dateipfad: Stellen Sie sicher, dass Ihre .html-Datei exakt im richtigen Verzeichnis Blocks/ liegt.

  • Fehler im Dateinamen: Der Dateiname muss auf .html enden und dem Schema [a-zA-Z0-9]+.html folgen.

  • Fehlerhafte YAML-Syntax: Dies ist die häufigste Ursache. YAML ist sehr empfindlich gegenüber Einrückungen (nutzen Sie Leerzeichen, keine Tabs!) und der korrekten Schlüssel-Wert-Struktur. Ein kleiner Tippfehler kann schon alles lahmlegen.

• Parameter nicht sichtbar / nicht funktionsfähig:

  • Tippfehler im paramIdentifier: Stellen Sie sicher, dass der Bezeichner im YAML-Teil und in func_editor_attr() exakt übereinstimmt.

  • Falscher type: Ist der Parameter-Typ korrekt definiert (z.B. string, bool)?

• JavaScript oder CSS wird nicht angewendet:

  • Falsches class-Attribut: Überprüfen Sie, ob Sie class="backend", class="frontend" oder class="frontend backend" korrekt gesetzt haben, je nachdem, wo der Code ausgeführt werden soll.

  • JavaScript-Fehler: Öffnen Sie die Entwicklerkonsole (F12) und suchen Sie nach Fehlermeldungen in der Konsole.