Platzhalterverzeichnis

Block-Definitionen

Eigene Vorlagen für Blöcke (Blocktyp) für den Block Editor können unter /media/private/BlockEditor/Blocks/ registriert werden. Jeder Blocktyp wird separat in einer Block-Definition-Datei spezifiziert. Der Dateiname für die Block-Definition-Datei muss mit .html enden und kann folgende Zeichen enthalten: A-Z, a-z, 0-9, _ und -.

Hinweis: Die Dateien müssen per FTP angelegt werden.

Block-Definition-Dateien sind HTML-Dateien, welche folgende Struktur aufweisen:

<script type="text/yaml">
</script>

<script class="<modes>">
</script>

<style class="<modes>">
</style>

<template class="<modes>">
</template>

Notwendig

Folgende Abschnitte müssen zwingend implementiert werden:

• <script type="text/yaml"> YAML-Definition des Blocktyps

Optional

Folgende Abschnitte sind optional:

• <template class="<modes>"> Das HTML-Markup des Blocktyps
• <script class="<modes>"> JavaScript-Code des Blocks
• <style class="<modes>"> CSS-Code des Blocks

Als <modes> muss entweder "frontend", "backend" oder beides angegeben werden. Abhängig davon werden die Styles, Scripte und das Markup im Frontend, Backend oder beidem ausgegeben. Tags ohne eine solche Angabe werden nicht ausgegeben.

YAML-Definition

Der YAML-Abschnitt (<script type="text/yaml">...</script>) der Block-Definition-Datei beschreibt die Integration des Blocktyps in den Block Editor und hat folgenden Aufbau:

apiVersion: 1.0
identifier: <identifier>
name:
  de: <name_de>
  en: <name_en>
description:
  de: <desc_de>
  en: <desc_en>
icon: <icon>
params: <params>
paramGroups: <paramGroups>

Notwendig

Folgende Direktiven müssen zwingend definiert werden:

apiVersion

Version der Block-Definition. Aktuell immer: 1.0

identifier

Ein einzigartiger technischer Name für den Blocktyp. Wir empfehlen ein Präfix mit dem Firmen- oder Webseitennamen zu verwenden. Erlaubte Zeichen für <identifier> sind: A-Z, a-z, 0-9, _ und -.

Standard-Blocktypen

Die Standard-Blocktypen haben folgende identifier:

• heading
• link
• image
• paragraph
• source
• editor

name

Der Anzeigename des Blocktyps im Block Editor. Der Englische Name muss zwingend definiert werden. Alle weiteren Backend-Sprachen sind optional.

Optional

Folgende optionale Direktiven stehen zur Verfügung:

description

Eine Beschreibung des Blocktyps, übersetzt in die Backend-Sprachen. Englisch wird als Fallback verwendet.

icon

Dekoriert den Blocktyp im Block Editor mit einem Icon. Als <icon> ist entweder eine durch Leerzeichen getrennte Liste von CSS-Klassennamen zu notieren (dies kann z.B. mit der im Backend eingebundenen FontAwesome-Bibliothek verwendet werden) oder ein Dateipfad zu einem Icon. Der Dateipfad muss mit einem Slash (/) beginnen.

params

Parameter erlauben die Individualisierung des Blocks innerhalb des Block Editors. Die Parameter werden dabei als Einstellungsmöglichkeiten des Blocks im Block Editor angezeigt. <params> ist eine Liste vom Blocktyp bereitgestellten Parametern.

paramGroups

Parameter-Gruppen erlauben die Gruppierung von Parametern. Standartmässig sind alle Parameter in der Gruppe default. Diese Direktive erlaubt die Definition weiterer Gruppen. Siehe Parameter-Gruppen für weitere Informationen.

Parameter Definition

Ein Parameter hat folgenden Aufbau:

<paramIdentifier>:
  name:
    <lang>: <translatedName>
  icon: <formatToBeDefined>
  group: <groupIdentifier>
  placeholder:
    <lang>: <placeholderValue>
  tooltip:
    <lang>: <translatedTooltip>
  hint:
    <lang>: <translatedHint>
  type: <bool|string|number|color|url|media|list>
  hidden: <true|false>
  depends: <dependency>
  default: <defaultValues>
  fixed:
    - <fixedValues>
  bounds:
    subTypes: <subTypeList>
    validator: <regex>
    upper: <upperLimit>
    lower: <lowerLimit>
    step: <step>
    validValues:
      <value>:
        <lang>: <displayValue>

<paramIdentifier> ist ein pro Block-Definition einzigartiger technischer Name für den Parameter. Erlaubt sind die Zeichen A-Z, a-z, 0-9, _ und -.

<lang> ist die jeweilige Sprach-Kennung. Z.B. de für Deutsch oder en für Englisch.

Notwendig

Folgende Direktiven müssen zwingend definiert werden:

name

Der Anzeigename für den Parameter in der Sprache <lang>.

type

Der Typ des Parameters. Für mögliche Werte für <type> siehe Parameter-Typen

Optional

Folgende optionale Direktiven stehen zur Verfügung:

icon

<icon> ist entweder eine kommagetrennte Liste von CSS-Klassen, oder ein Dateipfad relativ zur Stammverzeichnis der Webseite, beginnend mit einem Slash ("/").

group

<groupIdentifier> ist der Name einer unter Parameter-Gruppen definierten Gruppe. Wird keine Gruppe angegeben, wird der Parameter der Gruppe "Allgemein" (default) zugewiesen.

hidden

<hidden> kann auf true gesetzt werden, wenn der Parameter zwar gespeichert und validiert, aber in der Sidebar nicht angezeigt werden soll. Dies ist nützlich um Parameter mit JavaScript, z.B. direkt innerhalb des Blocks zu bearbeiten. Wird dies auf true gesetzt, so ist die Angabe von name optional.

depends

<dependency> kann auf den Identifikator eines anderen Feldes gesetzt werden. Der Parameter wird dann nur angezeigt, wenn das angegebene Feld als true evaluiert wird.

toolbar

Hier kann eine Liste von Tools angegeben werden, die in der Toolbar angezeigt werden sollen. Ist die Liste leer oder toolbar wird gar nicht angegeben, so wird keine Toolbar angezeigt. Damit die Toolbar funktioniert, muss ein Element die Klasse clx-block-editor-toolbar-field haben. Die Aktionen der Toolbar beziehen sich dann auf dieses Feld.

placeholder

<placeholderValue> ist der Platzhalter-Wert für das Eingabefeld für den Parameter.

tooltip

<translatedTooltip> ist der übersetzte Tooltip-Text für den Parameter.

hint

<translatedHint> ist der übersetzte Text der angezeigt wird, wenn die Validierung des Feldes fehlschlägt. Insbesondere Hilfreich in Kombination mit bounds.validator.

default

<defaultValues> enthält den Wert oder die Werte, die gesetzt werden, wenn der Parameter noch keinen Wert gesetzt hat. Die genauen Möglichkeiten sind abhängig vom Parameter-Typ.

fixed

<fixedValues> enthält Werte, die dem Parameter fix zugeordnet sind und nicht entfernt werden können. Hilfreich um z.B. bei CSS-Klassen klar zu machen, welche Klassen fix gesetzt sind. Die genauen Möglichkeiten sind abhängig vom Typ.

bounds

<bounds> definiert Einschränkungen für den Wert / die Werte des Parameters. Die nachfolgenden Einschränkungen können je nach Typ definiert werden:

Parameter-Typen

Die nachfolgende Tabelle dient als Übersicht über die verfügbaren Typen und der Verwendung der Direktiven default, fixed und bounds.

bool

Wird als einfaches Ja/Nein-Feld dargestellt (Checkbox, Schieber, ...).

Als default kann nur ein einziger Wert im Format true oder false angegeben werden. Sofern angegeben, wird er verwendet, wenn der Parameter noch nicht gesetzt ist.

Beispiel:

params:
  myBoolParam:
    name:
      de: "Ein Ja/Nein-Feld"
      en: "A yes/no selection"
    type: bool
    default: true

string

Wird je nach zugelassener Länge als einzeiliges oder mehrzeiliges Textfeld dargestellt.

Als default kann nur ein einziger Wert als Zeichenkette angegeben werden. Sofern angegeben, wird er verwendet, wenn der Parameter noch nicht gesetzt ist.

Die folgenden bounds (Einschränkungen) werden unterstützt:

• validator: Eine RegEx zur Validierung der Eingabe.
• upper: Die maximale Anzahl Zeichen. Keine Angabe oder 0 werden als "unlimitiert" interpretiert.
• lower: Ist dieses Feld auf 0 oder eine negative Zahl gesetzt, oder gar nicht angegeben, so wird ein mehrzeiliges Textfeld ausgegeben. Wird lower nicht angegeben, so wird ein einzeiliges Feld ausgegeben und der Wert enthält keine Zeilenumbrüche.

number

Gibt ein Zahlenfeld (input type "number") aus.

Als default kann nur ein einziger Wert als int oder float angegeben werden. Sofern angegeben, wird er verwendet, wenn der Parameter noch nicht gesetzt ist.

Die folgenden bounds (Einschränkungen) werden unterstützt:

• upper: Höchste einstellbare Zahl.
• lower: Tiefste einstellbare Zahl.
• step: Schrittweite.

color

Gibt ein Farbwahlfeld (input type "color") aus.

Als default kann nur ein einziger Wert als CSS-kompatible Farbangabe angegeben werden. Sofern angegeben, wird er verwendet, wenn der Parameter noch nicht gesetzt ist.

Die folgenden bounds (Einschränkungen) werden unterstützt:

• validator: Eine RegEx zur Einschränkung der Farbwerte. Dabei ist zu beachten, dass CSS verschiedene Angaben erlaubt (z.B. #XXXXXX, #XXX, rgb(...), rgba(...)).
• validValues: Eine Liste von CSS-kompatiblen Farbwerten, die als Vorauswahl zur Verfügung stehen. Die Auswahl ist nicht auf diese Farben begrenzt! Soll die Auswahl auf gewisse Farben begrenzt sein, kann stattdessen der Typ list verwendet werden.

url

Stellt eine Auswahl für eine oder mehrere URLs dar. URLs können auf eine Datei im Webseiten-Verzeichnis, eine Inhaltsseite oder eine externe Quelle zeigen.

Als default kann, abhängig von der maximalen Anzahl URLs, ein einziger Wert oder Mehrere angegeben werden. Sofern angegeben, werden die Werte verwendet, wenn der Parameter noch nicht gesetzt ist.

Die folgenden bounds (Einschränkungen) werden unterstützt:

• validator: Eine RegEx zur Validierung der einzelnen URLs.
• upper: Die maximale Anzahl URLs. Wird als 1 interpretiert, wenn nicht angegeben. 0 oder eine negative Zahl bedeuten "unendlich".
• lower: Kann verwendet werden, um mindestens so viele leere Felder darzustellen, auch wenn keine Werte vorhanden sind. Wird ignoriert, wenn upper 1 ist.
• subTypes: Kann auf eine Komma-getrennte Kombination folgender Werte gesetzt werden: page (Inhaltsseiten), local (Dateien im Webseiten- Verzeichnis), remote (sonstige/externe Quellen). Standard sind alle drei (page,local,remote).

media

Stellt eine Auswahl für eine oder mehrere Medien-Datei dar. Aktuell werden nur Bilder unterstützt.

Als default kann, abhängig von der maximalen Anzahl, ein einziger Wert oder Mehrere angegeben werden. Sofern angegeben, werden die Werte verwendet, wenn der Parameter noch nicht gesetzt ist.

Die folgenden bounds (Einschränkungen) werden unterstützt:

• validator: Eine RegEx zur Validierung der einzelnen Datei-URLs.
• upper: Die maximale Anzahl Medien-Dateien. Wird als 1 interpretiert, wenn nicht angegeben. 0 oder eine negative Zahl bedeuten "unendlich".
• lower: Kann verwendet werden, um mindestens so viele leere Felder darzustellen, auch wenn keine Werte vorhanden sind. Wird ignoriert, wenn upper 1 ist.
• subTypes: Kann auf eine Komma-getrennte Kombination folgender Werte gesetzt werden: image (Bilder), video (Videos), audio (Audio-Dateien). Aktuell wird nur image unterstützt, dies ist auch der Vorgabewert. aufgelisteten Dateien zur Auswahl.

list

Stellt eine Auswahl aus einer Liste von Werten dar.

Als default kann, abhängig von der maximalen Anzahl, ein einziger Wert oder Mehrere angegeben werden. Sofern angegeben, werden die Werte verwendet, wenn der Parameter noch nicht gesetzt ist.

Die Direktive fixed kann verwendet werden, um Werte zu hinterlegen, die der Benutzer nicht entfernen kann. Dies ist z.B. hilfreich für CSS-Klassen, die der Benutzer sehen, aber nur erweitern können soll.

Die folgenden bounds (Einschränkungen) können optional wie folgt genutzt werden:

• validator: Wird dieses Feld angegeben kann der Kunde weitere Werte hinzufügen, sofern sie dem in dem Feld angegebenen Regulären Ausdruck entsprechen.
• upper: Die maximale Anzahl an gewählten Werte. Ist der Wert 0 oder eine negative Zahl bedeutet dies "unlimitiert". Ist dies grösser als 1 ist eine Mehrfachauswahl möglich. Standartwert ist 1.
• lower: Die minimale Anzahl an gewählten Werte. Ist der Wert 1 oder grösser muss mindestens ein Wert gewählt sein. Ist der Wert 0 kann auch kein Wert gewählt werden.
• validValues: Kann zur Angabe der verfügbaren Werte genutzt werden.

Parameter-Gruppen

Eine Parameter-Gruppe hat folgenden Aufbau:

<groupIdentifier>:
  name:
    <lang>: <translatedName>

<groupIdentifier> ist ein pro Gruppe einzigartiger technischer Name. Erlaubt sind die Zeichen A-Z, a-z, 0-9, _ und -.

<lang> ist die jeweilige Sprach-Kennung. Z.B. de für Deutsch oder en für Englisch.

HTML-Markup

Mit dem <template class="<modes>">-Tag wird die visuelle Darstellung des Blocks definiert. Als <modes> entweder frontend backend angegeben werden, um die Anzeige sowohl im Backend (Block Editor) als auch im Frontend zu definieren. Alternativ kann nur frontend bzw. backend gesetzt werden, um die Anzeige ausschliesslich im Frontend bzw. Backend zu steuern. Letzteres ermöglicht es zwei separate <template class="<modes>">-Tags zu implementieren - für eine unterschiedliche Darstellung im Frontend und im Backend.

Innerhalb des <template>-Tags kann normales HTML verwendet werden. Zusätzlich stehen folgende Funktionen zur Verfügung:

• func_editor_attr()
• func_editor_if_attr()
• func_editor_if_not_attr()
• func_editor_escape_content()
• func_editor_block()

Die Argumente aller Funktionen können entweder mit Backticks (`), einfachen (') oder doppelten Anführungszeichen (") umschlossen werden.

Parameter Anzeige

Mit dem funktionalen Platzhalter func_editor_attr("paramName"[, "delimiter"]) kann der Wert eines Parameters (paramName) ausgegeben werden. Ist der Wert von einem Typ, der mehrere Werte unterstützt, kann als zweiter Parameter ein Trennzeichen (delimiter) angegeben werden, der die einzelnen Werte trennt. Wird der Delimiter nicht angegeben, so wird " " verwendet.

Parameter verknüpfen

In der Backend-Ansicht kann ein Feld automatisch mit einem Parameter verknüpft werden, indem bei <div>-Elementen mit contenteditable oder bei <input>-Elementen vom Typ text das Datenattribut data-block-param auf den gewünschten Parameter gesetzt wird.

Beispiel um ein <input>-Element mit dem Parameter myParam zu verknüpften:

<input type="text" data-block-param="myParam">

HTML Escaping

Wird ein Parameter innerhalb eines HTML-Attributs ausgegeben (z.B. im value-Attribut eines Inputfeldes), so müssen die Anführungszeichen escaped werden. Dies kann mit dem Platzhalter func_editor_escape_content("content") umgesetzt werden. Ein Beispiel dafür findet sich der Block-Definition "link".

Bedingte Ausgabe basierend auf Parameter

Die funktionalen Platzhalter func_editor_if_attr("paramName", "markup") und func_editor_if_not_attr("paramName", "markup") erlauben die bedingte Anzeige von Markup (markup). Bei Verwendung von func_editor_if_attr("paramName", "markup") wird das Markup (markup) nur dann ausgegeben, wenn der Wert des Parameters paramName als Wahr (true) ausgewertet wird. Im Gegensatz dazu wird das Markup (markup) bei Verwendung von func_editor_if_not_attr("paramName", "markup") nur dann ausgegeben, wenn der Wert des Parameters paramName nicht als Wahr (false) ausgewertet wird. Dies ist insbesondere sinnvoll für Parameter vom Typ bool.

Block-Integration

Der funktionale Platzhalter func_editor_block("identifier", "blockType"[, "options"]) ermöglicht die Integration von einem oder mehreren weiteren Blöcken im Markup. identifier ist ein frei wählbarer Bezeichner für den zu integrierenden Block. Er darf innerhalb der Block-Definition nur einmal verwendet werden. Erlaubte Zeichen sind: A-Z, a-z, 0-9, _ und -. Als blockType kann der identifier eines der Standard-Blocktypen oder eines der selbst definierten Blocktypen verwendet werden. Mit dem optionalen Argument options können Parameter des blockType gesetzt werden. options muss als JSON notiert werden. So gesetzte Parameter können in der Sidebar nicht bearbeitet werden.

Beispiele:

func_editor_block(`text`, `paragraph`)

Dieses Beispiel fügt einen Block vom Typ paragraph ein.

func_editor_block(`subtitle`, `heading`, `{"level": 3}`)

Dieses Beispiel fügt einen Block vom Typ heading ein, wobei die Ebene fest auf h3 gesetzt ist.

Integration einer Blockauswahl

Um dem Benutzer eine Auswahl von Blöcken anzubieten, kann als blockType der spezielle Identifier editor verwendet werden. Mit options wird definiert, welche Blocktypen zur Verfügung stehen und wie viele Blöcke des jeweiligen Typs mindestens und maximal vorhanden sein dürfen. options ist ein JSON mit der folgenden Form:

{
  "<blockType>": {
    "min": <minCount>,
    "max": <maxCount>,
    "params": {<options>}
  }
}

So kann pro Blocktyp die Mindest- und Maximalanzahl eingeschränkt werden. Der Index params ermöglicht das Setzen von Parametern pro Blocktyp, analog zum Argument options bei der regulären Verwendung von func_editor_block().

Beispiele:

func_editor_block(`weblinks`, `editor`, `{"link": {"min": 0, "max": 3}}`)

Dieses Beispiel erlaubt es, bis zu drei Blöcke vom Typ link einzufügen. Es ist zu beachten, dass die Anführungszeichen nicht vermischt werden dürfen.

func_editor_block(`content`, `editor`, `{"paragraph":{}, "heading":{}, "hr":{} }`)

Dieses Beispiel erlaubt die Integration der Blocktypen paragraph, heading und hr.

JavaScript- & CSS-Code

Die Tags <script> und <style> sind optional und können für Script und Styles verwendet werden. Mit der Angabe von "frontend" und/oder "backend" im Attribut class="" des Tags kann die Ausgabe auf einen der beiden Modes beschränkt werden.

JavaScript-API

Der Backend-JavaScript-Code eines Blocktyps wird als Teil einer Klasse eingebunden. Pro Block des Typs wird eine Instanz der Klasse erstellt.

Die Methode init() kann angegeben werden (siehe auch nachfolgendes Beispiel), um bei der Initialisierung eines Blocks einzugreifen:

init(api, block) {
    // Diese Funktion wird bei jeder Instanzierung des Blocktyps aufgerufen.
    // Als parameter werden die editor API im Parameter `api`, sowie
    // die Referenz auf den aktuellen Block als `block` mitgegeben.
}

Ausserdem stehen folgende Helfer als Klassen-Eigenschaften und -Methoden zur Verfügung:

• this.constructor.baseConfig: Die YAML-Konfiguration als JSON
• this.constructor.template: Das definierte Markup template als String
• this.constructor.identifier: Identifier des Blocktyps als String
• this.setParam(<name>, <value>): Setzt den Parameter <name> des Blocks auf den Wert <value>.

Beispiele

Als Beispiele können die vordefinierten Blocktypen verwendet werden.

Ein einfaches Beispiel, wie eine Block-Definition aussehen kann ist der vordefinierte Typ "link" in der Datei Link.html:

<script type="text/yaml">
    apiVersion: 1.0
    identifier: "link"
    name:
      de: "Link"
      en: "Link"
    icon: "fa-solid fa-link"
    params:
      linkTarget:
        name:
          de: "Linkziel"
          en: "Link target"
        type: url
      targetWindow:
        name:
          de: "Zielfenster"
          en: "Target window"
        type: list
        default: "_self"
        bounds:
          lower: 1
          upper: 1
          validValues:
            "_self":
              de: "Gleiches Fenster"
              en: "Same window"
            "_blank":
              de: "Neues Fenster"
              en: "New Window"
            "_parent":
              de: "Übergeordnetes Fenster"
              en: "Parent frame"
            "_top":
              de: "Oberstes Fenster"
              en: "Top frame"
      linkContent:
        name:
          de: "Inhalt"
          en: "Content"
        type: string
        default: "Link"
        bounds:
          lower: 0
</script>

<a href="func_editor_attr("linkTarget")" target="func_editor_attr("targetWindow")">
    func_editor_attr("linkContent")
</a>

InlineTools

InlineTools sind Tools, die in der Inline Toolbar verwendet werden können. Definiert werden solche Tools prinzipiell genau gleich wie Blocktypen. Die entsprechenden Dateien liegen im Unterordner /media/private/BlockEditor/InlineTools statt /media/private/BlockEditor/Blocks.

YAML-Definition

Aktuell gibt es keine speziellen YAML-Definitionen für InlineTools. Lediglich die API-Version und der Identifier müssen angegeben werden:

apiVersion: 1.0
identifier: <identifier>
localization:
  <varName>:
    de: <value_de>
    en: <value_en>

Der Abschnitt localization ist optional und kann verwendet werden um übersetzte Werte abzulegen. Kann z.B. mit der Helfer-Methode this.lang(varName) ausgelesen werden.

JavaScript-API

Wie auch bei Blocktypen wird der Code in eine Klasse ausgeführt. Die folgenden beiden Methoden müssen angegeben werden, damit das Tool funktioniert:

render(block, element) {
    // Diese Methode wird bei der Initialisierung des Tools aufgerufen.
    // Das Tool wird für jeden gewählten Block neu initialisiert.
    // `block` enthält den aktuell gewählten Block, `element` enthält
    // das Element in der Toolbar für dieses Tool.
}

update(block, element, event) {
    // Diese Methode wird bei jeder Änderung an dem aktuellen Block,
    // auch bei jeder Änderung der Textauswahl, aufgerufen.
    // Die Parameter `block` und `element` enthalten dieselben
    // Informationen wie bei `render()`. `event` enthält den Event, der
    // das Update ausgelöst hat.
}

Folgende Methoden sind optional und können bei Bedarf verwendet werden:

processSave(data) {
    // Diese Methode wird aufgerufen, wenn ein Feld, das Tools erlaubt,
    // gepeichert wird. `data` muss wieder zurückgegeben werden, kann
    // aber zuvor verändert werden. Ein Beispiel findet sich im Standard
    // InlineTool "Shy".
    return data;
}

processLoad(data) {
    // Diese Methode wird aufgerufen, wenn ein Feld, das Tools erlaubt,
    // geladen wird. `data` muss wieder zurückgegeben werden, kann
    // aber zuvor verändert werden. Ein Beispiel findet sich im Standard
    // InlineTool "Shy".
    return data;
}

Ausserdem stehen folgende Helfer als Klassen-Eigenschaften und -Methoden zur Verfügung:

• this.constructor.baseConfig: Die YAML-Konfiguration als JSON
• this.constructor.template: Das definierte Markup template als String
• this.constructor.identifier: Identifier des Blocktyps als String
• this.lang(varName): Gibt den übersetzten Wert zurück.
• this.allowIfFocusInElement(block, element, event): Kann in update() aufgerufen werden um das Tool zu aktivieren wenn immer der Fokus im Inputfeld liegt.
• this.allowIfTextSelected(block, element, event): Kann in update() aufgerufen werden um das Tool zu aktivieren wenn immer Text selektiert ist.