Aufbau
Eine Content-Element setzt sich üblicherweise aus folgenden Ressourcen zusammen:
- TypoScript: Element definieren, registrieren und konfigurieren
- Fluid-Template: erstellt das HTML-Grundgerüst
- Fluid-Settings-Formular: definiert den Inhalt des Settings-Fensters
- CSS: enthält Design-Anweisungen
- JavaScript: optional, um komplexere Funktionen umzusetzen
Tipp
Der Bakehouse Content-Element-Generator
Bei der Erstellung der Grundstruktur und dem konformen Aufbau eines Content-Elements hilft der Bakehouse Content-Element-Generator.
TypoScript
Die TypoScript-Konfiguration eines Content-Elementes kann auf der page Root-Seite global für das ganze Projekt durchgeführt werden. Auf diese Weise können neue Content-Elemente registriert und Bestehende verändert werden.
Konfiguration
Im folder Element-Ordner wird eine file TypoScript-Datei angelegt, welche die grundsätzliche Konfiguration eines Content-Elements übernimmt. Das folgende Beispiel zeigt das TypoScript eines neuen Elements:
Typoscript
plugin.tx_bh.settings.contentElements.[myElement] < abstract.bhElement
plugin.tx_bh.settings.contentElements.[myElement] {
# ----- GENERAL -----
# Name
name = Mein Content-Element
# Beschreibung
description = Dieses Element erfüllt vielseitige Aufgaben
# Positionierung in der Element-Auswahl im Front-End
bheListgroup = 1
# Priorisierung in der Gruppe
bheSortPriority = 20
# ----- PFADE -----
# Dateiname Fluid-Template
templateFile = [myElement].html
# Pfad zum Fluid-Template
templatePath = fileadmin/templates/elements/[myElement]/
# Pfad zum Fluid-Settings-Formular
settingsForm = fileadmin/templates/elements/[myElement]/[myElement]-settings.html
# Pfad zum Icon
iconFile = typo3/sysext/bh/Resources/Public/Icons/Elemente/default.svg
# ----- EIGENSCHAFTEN -----
# Element kann verlinkt werden
link = 1
options {
# Verhalten nach dem Anlegen eines neuen Elements
oncreate = none
# Element kann inhaltlich editiert werden
edit = 1
# Element kann kopiert werden
copy = 1
# Element besitzt ein Settings-Formular
settings = 1
# [...]
}
# ----- CSS-KLASSEN
userClass = [meineKlasse] [meineKlasse]
# ----- STYLES
styleOptions {
classes {
[myClass] = Beschreibung der Klasse
[myClass] = Beschreibung der Klasse
# [...]
}
}
# ----- DUMMY-INHALTE
# Werden beim Anlegen eines neuen Elements angewendet
dummyData {
name (
Headline
)
text (
Lorem ipsum dolor sit amet, consetetur sadipscing
)
}
}
# Pfad zur CSS-Datei
page.includeCSS.[myElement] = fileadmin/templates/elements/[myElement]/[myElement].css
# Pfad zur JavaScript-Datei
page.includeJS.[myElement] = fileadmin/templates/elements/[myElement/[myElement.js
# ----- Optional: Konfiguration für Bakehouse-Erweiterung 'Mobilversion'
[bh.isMobile]
bhDefaultMobilePage.includeCSS.[myElement] < page.includeCSS.[myElement]
bhDefaultMobilePage.includeCSS.[myElement]-mobile = fileadmin/templates/elements/[myElement]/[myElement]-mobile.css
[global]
Attribute
Folgende Attribute können für ein Content-Element im TypoScript definiert werden:
| Attribut | Beschreibung | Typ | Beispielwerte |
| name | Name des Elements | String | name = [myElement] |
| description | Optionale Beschreibung für Eigenschaften, Nutzen und Funktionalität des Elements, die dem/r Redakteur:in in der Content-Element-Auswahl als Tooltip angezeigt wird | String | description = [myElementDescription] |
| bheListgroup | Elemente werden in der Auswahl in der Werkzeugleiste für gewöhnlich hinsichtlich ihrer Eigenschaften für die Redakteure übersichtlich gruppiert (z.B. Inhaltselemente wie Text und Bilder oder Layoutelemente wie Spalten oder Tabs). | Integer | [default = 0] |
| bheSortPriority | Teilt einem Element eine bestimmte Priorität innerhalb einer Gruppe (bheListgroup) zu und wirkt sich somit auf die Sortierung in der Element-Auswahl aus. Je kleiner der Wert, desto größer die Priorität. | Integer | [default = 50] Beispiel: Das Element "Text" wird für gewöhnlich am öftesten verwendet und sollte daher eine höhere Priorität bekommen. |
| bheParentElement | Hier kann ein übergeordnetes Element angegeben werden. Elemente mit dieser Einstellung werden in der Element-Liste unterhalb des angegebenen Elements und kleinerer Optik dargestellt. | String | el-form-manager |
| templateFile | Dateiname des Fluid-Templates | String | [myElement].html |
| templatePath | Pfad zum Verzeichnis mit dem Fluid-Template | String | |
| settingsForm | Dateipfad zum Fluid-Settings-Formular, in welchem Einstellungsmöglichkeiten für den/die Redakteur:in bereitgestellt werden | String | |
| iconFile | Dateipfad zum Element-Icon. Das Bakehouse bietet werksseitig eine Auswahl von SVG-Icons an. | String | |
| hidden | Definiert, ob ein Content-Element in der Element-Auswahl angezeigt wird oder nicht. Das Element – sofern bereits in einem Content-Bereich eingefügt – bleibt aber weiterhin verwendbar. | [0,1] | hidden = 0 |
| link | Definiert, ob ein Content-Element als ganzes verlinkbar sein soll | [0,1] | link = 1 |
| doNotRenderLink | Definiert, ob der Element-Link automatisch auf das Element gelegt wird oder frei mit dem bh:link-ViewHelper verwendet werden kann. | [0,1] | doNotRenderLink = 1 |
| linkData | Definiert, welche Art von Link vorgesehen ist | Array |
|
| dummyData | Definiert Standard-Content für bestimmte Felder des Content-Elements. Diese werden beim Anlegen eines Content-Elements angewendet. | Array |
|
| layerGroup | Fügt einem Content-Element die Bedienelemente für Layer-Steuerung hinzu (wie z.B. beim Fader oder Swiper). | [0,1] | layerGroup = 1 |
| options | Optionen, die sich auf das Editing-Verhalten auswirken | Array | |
| options.oncreate | Definiert das Bakehouse-Verhalten nach dem Anlegen eines neuen Content-Elements | [none, advanced, edit] |
|
| options.edit | Definiert, ob ein Content-Element durch den Redakteur edit inhaltlich bearbeitbar ist | [0,1] | options.edit = 1 |
| options.settings | Definiert, ob ein Content-Element über ein settings2 Settings-Formular verfügt | [0,1] | options.settings = 1 |
| options.copy | Definiert, ob ein Content-Element copy kopierbar ist | [0,1] | options.copy = 1 |
| options.translate | Definiert, ob ein Content-Element addlanguage übersetzbar ist, sollte ein Bakehouse-Projekt über mehrere Sprachen verfügen | [0,1] | options.translate = 1 |
| options.moveable | Definiert, ob ein Content-Element per docucrosshair Drag & Drop verschoben werden darf | [0,1] | options.moveable = 1 |
| options.newElement | Fügt einem Content-Element das add Bedienelement für das verschachtelte Erstellen neuer Content-Elemente hinzu und bestimmt, welches dies sein sollte (z.B. das Kind-Element einer Layoutbox). | String | options.newElement = [myChildElement] |
| styleOptions | Hier können mögliche Style-Varianten für das Element festgelegt werden. Diese können im Settings-Formular dem/der Redakteur:in z. B. in einem Select zur Verfügung gestellt werden: Die Werte können dann im Fluid-Template des Elements abgefragt werden. | Array | |
| userClass | Gibt dem Content-Element CSS-Klassen mit | String | userClass = [myClass] |
| [meinattribut] | Eigene Attribute können verwendet werden, um diese im Fluid-Template oder im Settings-Formular auszulesen {cObj.allSettings.meinattribut} | [mixed] |
|
Vordefinierte Icons
Folgende Icons werden vom Bakehouse unter typo3/sysext/bh/Resources/Public/Icons/Elemente/ bereitgestellt. Es steht dem/der Integrator:in frei, dem Content-Element ein eigenes Icon beizulegen.
Registrierung
Die file Typoscript-Datei des Content-Elements wird mit folgender Zeile im Root-TypoScript registriert:
Typoscript
@import 'fileadmin/templates/elements/[myElement]/[myElement].typoscript'
Fluid-Template
Das file HTML-Template eines Content-Elements gibt dessen Struktur vor. Spezielle Funktionen, wie etwa Text- und Bildbereiche, die im Front-End von den Redakteuren bearbeitet werden können, werden mit den entsprechenden ViewHelpern im Template definiert.
Ein Beispiel-Template eines einfachen Content-Elementes:
HTML
{namespace bh=TYPO3\Bh\ViewHelpers}
<!-- Element-ViewHelper -->
<bh:tmpl.element object="{cObj}">
<!-- Container mit Werten aus dem TypoScript oder Settings-Formular -->
<div class="element-wrapper" style="height: {cObj.settings.height};">
<div class="element-headline">
<!-- Bearbeitbarer Text-Bereich -->
<bh:property.text tag="h2" property="name" />
</div>
<div class="element-picture">
<!-- Bearbeitbarer Bild-Bereich -->
<bh:property.picture picture="{cObj.thing.picture}" />
<!-- Abfrage von TypoScript-Attributen -->
<f:if condition="{cObj.allSettings.style.copyright}">
<f:if condition="{cObj.picture.copyright}">
<div>Foto: {cObj.picture.copyright}</div>
</f:if>
</f:if>
</div>
<div class="element-content">
<!-- Bearbeitbarer Text-Bereich -->
<bh:property.text tag="span" property="text" />
</div>
</div>
</bh:tmpl.element>
Jedem Template wird automatisch das Content-Object {cObj} übergeben. Damit erhält man Zugriff auf die Settings, die entweder aus der file TypoScript-Konfiguration und/oder aus dem file Settings-Formular stammen (das Settings-Formular überschreibt vorhandene "Defaults" der TypoScript-Konfiguration).
Mit dem Element-ViewHelper (bh:tmpl.element) wird das Element definiert und kann somit im Editier-Modus des Bakehouse als solches behandelt werden (verschieben, kopieren, löschen, ...).
Der Element ViewHelper bh:tmpl.element muss immer das HTML umschließen und darf nicht von anderen Tags umschlossen sein.
Mit dem Property-ViewHelper bh:property.text oder bh:property.picture werden die im Front-End inhaltlich befüllbaren Bereiche definiert:
- mit dem Attribut property wird definiert, in welchem Feld des Thing-Records der Text oder das Bild gespeichert werden soll
- dem Picture-ViewHelper muss das File-Object über das Attribut picture mitgegeben werden
Derzeit sind in einem Contentelement folgende Attribute verfügbar:
| Eigenschaft | Rückgabewert | Beschreibung |
| name | String | Name des Elementes |
| picture | File (Object) | Ist kein Bild gesetzt, wird ein leerer String zurückgegeben. |
| text | String | Beschreibung |
| subtext | String | zusätzlicher Text |
Fluid-Settings-Template
Das file Settings-Formular-Template wird im TypoScript definiert (siehe TypoScript Konfiguration) und im Grunde gleich wie jedes andere Template im Bakehouse aufgebaut. Da es sich aber um ein Formular handelt, müssen die Formularfelder vom Bakehouse-ViewHelper bh:form.settingsform umschlossen sein.
Beispiel:
HTML
{namespace bh=TYPO3\Bh\ViewHelpers}
<!-- Formular-Viewhelper-->
<bh:form.settingsform content="{cObj}">
<!-- Option mit Select -->
<div class="bhe-formsettings-option">
<label data-tooltip="Wähle den Style für das Element">Style</label>
<f:form.select name="style" value="{cObj.settings.style}" options="{cObj.allSettings.styles}" />
</div>
<!-- Option mit Checkbox -->
<div class="bhe-formsettings-option">
<label>Headline ausgeben</label>
<f:form.checkbox name="style[headline]" value="headline" checked="{cObj.allSettings.style.headline}" />
</div>
<!-- Option mit Textfeld -->
<div class="bhe-formsettings-option">
<label data-tooltip="Angabe in Pixel">Höhe des Elements</label>
<f:form.textfield name="height" value="{cObj.settings.height}" />
</div>
<!-- Speichern -->
<f:form.submit value="Speichern" />
</bh:form.settingsform>
- Für Selects, deren Optionen aus dem Element-TypoScript ausgelesen werden (siehe style), muss der Fluid f:form.select-ViewHelper verwendet werden
- Im name-Attribut wird der Settings-Key definiert
- Mit {cObj.allSettings} hat man Zugriff auf alle TypoScript-Element-Einstellungen.
CSS und JavaScript
CSS- und JavaScript-Dateien können im TypoScript eines Content-Elements eingebunden werden. Dies dient nur zur übersichtlicheren Aufteilung und ist nicht auf das Content-Element begrenzt. CSS-Anweisungen in einer Content-Element-CSS-Datei beispielsweise wirken sich also global auf das gesamte Bakehouse-Projekt aus. Folgendes Beispiel zeigt die Einbindung im file Content-Element-TypoScript:
Typoscript
# Pfad zur CSS-Datei
page.includeCSS.[myElement] = fileadmin/templates/elements/[myElement]/[myElement].css
# Pfad zur JavaScript-Datei
page.includeJS.[myElement] = fileadmin/templates/elements/[myElement]/[myElement].js
# Optionale Konfiguration für die Bakehouse-Erweiterung 'Mobilversion'
[bh.isMobile]
# Übernahme der CSS-Datei in die Mobilversion
bhDefaultMobilePage.includeCSS.[myElement] < page.includeCSS.[myElement]
# Hinzufügen einer weiteren CSS-Datei nur in der Mobilversion
bhDefaultMobilePage.includeCSS.[myElement]-mobile = fileadmin/templates/elements/[myElement]/[myElement]-mobile.css
# Übernahme der JS-Datei in die Mobilversion
bhDefaultMobilePage.includeJS.[myElement] < page.includeJS.[myElement]
[global]