Bakehouse Content-Elemente erstellen

    Neben den bestehenden Core-Elementen ist es im Bakehouse möglich, einem Projekt spezifische Content-Elemente hinzuzufügen. Diese Elemente werden unter folder /fileadmin/templates/elements/ abgelegt und im TypoScript registriert.

    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:

    AttributBeschreibungTyp Beispielwerte
    nameName des ElementsString name = [myElement]
    descriptionOptionale Beschreibung für Eigenschaften, Nutzen und Funktionalität des Elements, die dem/r Redakteur:in in der Content-Element-Auswahl als Tooltip angezeigt wirdString description = [myElementDescription]
    bheListgroupElemente 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]
    bheSortPriorityTeilt 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.
    templateFileDateiname des Fluid-TemplatesString [myElement].html
    templatePathPfad zum Verzeichnis mit dem Fluid-TemplateString 
    settingsFormDateipfad zum Fluid-Settings-Formular, in welchem Einstellungsmöglichkeiten für den/die Redakteur:in bereitgestellt werdenString 
    iconFileDateipfad zum Element-Icon. Das Bakehouse bietet werksseitig eine Auswahl von SVG-Icons an.String
    hiddenDefiniert, 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
    linkDefiniert, ob ein Content-Element als ganzes verlinkbar sein soll
    [0,1] link = 1
    doNotRenderLinkDefiniert, ob der Element-Link automatisch auf das Element gelegt wird oder frei mit dem bh:link-ViewHelper verwendet werden kann. [0,1] doNotRenderLink = 1
    linkDataDefiniert, welche Art von Link vorgesehen istArray
    • target = Download
    • type = file
    dummyDataDefiniert Standard-Content für bestimmte Felder des Content-Elements. Diese werden beim Anlegen eines Content-Elements angewendet.Array
    • dummyData.text =
    • dummyData.subtext =
    • dummyData.name =
    layerGroupFügt einem Content-Element die Bedienelemente für Layer-Steuerung hinzu (wie z.B. beim Fader oder Swiper). [0,1]layerGroup = 1
    optionsOptionen, die sich auf das Editing-Verhalten auswirkenArray


    options.oncreateDefiniert das Bakehouse-Verhalten nach dem Anlegen eines neuen Content-Elements

    [none, advanced, edit]

    • none: nichts
    • advanced: das  settings2 Settingsformular öffnet sich
    • edit: der edit Editier-Modus wird aktiviert
    options.editDefiniert, ob ein Content-Element durch den Redakteur edit inhaltlich bearbeitbar ist[0,1]options.edit = 1
    options.settingsDefiniert, ob ein Content-Element über ein settings2 Settings-Formular verfügt
    [0,1]options.settings = 1 
    options.copyDefiniert, ob ein Content-Element  copy kopierbar ist[0,1]options.copy = 1
    options.translateDefiniert, ob ein Content-Element  addlanguage übersetzbar ist, sollte ein Bakehouse-Projekt über mehrere Sprachen verfügen[0,1]options.translate = 1
    options.moveableDefiniert, ob ein Content-Element per docucrosshair Drag & Drop verschoben werden darf[0,1]options.moveable = 1
    options.newElementFü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:
    <bh:form.select name="style" value="{cObj.allSettings.style}" options="{cObj.allSettings.styleOptions}" />

    Die Werte können dann im Fluid-Template des Elements abgefragt werden.

    Array 
    userClassGibt dem Content-Element CSS-Klassen mitString
     userClass = [myClass]
    [meinattribut]Eigene Attribute können verwendet werden, um diese im Fluid-Template oder im Settings-Formular auszulesen {cObj.allSettings.meinattribut}[mixed]
    • fadeDuration = 5000
    • menu = arrow
    • animation = 1

    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:

    EigenschaftRückgabewertBeschreibung
    nameStringName des Elementes
    pictureFile (Object)Ist kein Bild gesetzt, wird ein leerer String zurückgegeben.
    textStringBeschreibung
    subtextStringzusä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]