RockSolid Custom Elements Dokumentation

Die RockSolid Custom Elements sind eine kostenlose Contao-Extension mit der Sie eigene Inhalts-Elemente und Frontend-Module erstellen können, ohne die Datenbank-Struktur verändern oder Erweiterungen programmieren zu müssen. In den meisten RockSolid Themes werden solche Elemente bereits mitgeliefert. Weitere Informationen zum Funktionsumfang finden Sie auf der Seite der Custom Elements.

Zuerst: RockSolid Custom Elements installieren

Navigieren Sie im Contao-Backend zur Erweiterungsverwaltung und klicken Sie rechts oben auf Erweiterung installieren. Geben Sie dort rocksolid-custom-elements in das Feld Erweiterung ein und klicken Sie auf weiter. Wählen Sie die aktuellste Version und folgen Sie dem Installations-Assistenten, bis die Erweiterung erfolgreich installiert wurde.

Dann: Verwendung in Themes

Um die Custom Elements in einem RockSolid Theme zu verwenden ist nicht mehr nötig als die Erweiterung zu installieren und das Theme zu importieren. Folgen Sie am besten der Installationsanleitung Ihres Themes und Sie können alle Elemente Ihrer Website bearbeiten ohne HTML-Code schreiben zu müssen.

Optional: Deinstallieren ohne Datenverlust

Sie möchten die Custom Elements eines Themes nicht verwenden und stattdessen mit HTML-Code-Modulen arbeiten? Kein Problem! Navigieren Sie einfach im Contao-Backend zu System › Systemwartung und klicken dort unter RockSolid Custom Elements auf den Button Elemente in HTML konvertieren. Nun können Sie die Erweiterung problemlos über die Erweiterungsverwaltung deinstallieren ohne dabei Daten zu verlieren.

Optional: Eigene Elemente erstellen (für Fortgeschrittene)

Um ein eigenes Custom Element anzulegen müssen Sie eine Template-Datei (.html5) und eine Konfigurationsdatei (.php) erstellen und im Ordner /templates/ ablegen. Der Name der Template-Datei muss mit rsce_ beginnen, die Konfigurationsdatei muss den selben Namen wie das Template und zusätzlich das Suffix _config haben. Zum Beispiel rsce_my_element.html5 als Template-Datei und rsce_my_element_config.php als Konfigurationsdatei.

Konfigurations- und Template-Beispiel:

<?php
// rsce_my_element_config.php
return array(
    'label' => array('Mein Element', 'Meine Beschreibung...'),
    'types' => array('content', 'module'),
    'contentCategory' => 'texts',
    'moduleCategory' => 'miscellaneous',
    'beTemplate' => 'be_wildcard',
    'standardFields' => array('headline', 'cssID'),
    'wrapper' => array(
        'type' => 'none',
    ),
    'fields' => array(
        'text' => array(
            'label' => array('Text', 'Beschreibung...'),
            'eval' => array('rte' => 'tinyMCE'),
            'inputType' => 'textarea',
        ),
    ),
);

<!-- rsce_my_element.html5 -->
<section class="<?php echo $this->class ?> block"<?php echo $this->cssID ?>>
    <header>
        <<?php echo $this->hl ?>>
            <?php echo $this->headline ?>
        </<?php echo $this->hl ?>>
    </header>
    <?php echo $this->text ?>
</section>

label: Der Name und die Beschreibung des Elements wird in der Modul- und Elementtypauswahl angezeigt.
types: Array mit den Elementtypen als die das Element verfügbar ist (content und/oder module).
contentCategory: Die Kategorie in $GLOBALS['TL_CTE'] worunter das Inhaltselement angezeigt wird.
moduleCategory: Die Kategorie in $GLOBALS['FE_MOD'] worunter das Frontend-Modul angezeigt wird.
beTemplate: Optional ein abweichendes Template das für die Ausgabe des Elements im Contao-Backend verwendet wird.
standardFields: Eine Liste aller Standardfelder die verwendet werden sollen. Die Felder headline, cssID und space sind für Module und Inhaltselemente verfügbar, bei Inhaltselementen können zusätzlich text und image verwendet werden.
wrapper: Array mit Einstellungen für Wrapper-Elemente.
- type: Wrapper-Typ des Elements in $GLOBALS['TL_WRAPPERS'] (start, stop, separator oder single)

Die Felderliste "fields"

Die Felder die beim Bearbeiten des Elements im Backend angezeigt werden, werden wie in Contao-DCAs üblich konfiguriert. Weitere Informationen zu den Konfigurationsoptionen der einzelnen Felder finden Sie im Contao-Benutzerhandbuch. Die Feldtypen password und moduleWizard werden derzeit nicht unterstützt.

Feldtyp "list"

Zusätzlich zu den Feldtypen von Contao (text, textarea, select...) steht der Typ list zur Verfügung der es ermöglicht verschachtelte Inhalte zu erzeugen. Mit den Eigenschaften minItems und maxItems kann eine Mindest- und Maximalanzahl festgelegt werden. Ein Element mit einer Überschrift und mehreren Textboxen kann folgendermaßen definiert werden:

<?php
// rsce_boxes_config.php
return array(
    'label' => array('Textboxen mit Überschrift', 'Erzeugt eine...'),
    'types' => array('content'),
    'contentCategory' => 'texts',
    'standardFields' => array('headline', 'cssID'),
    'fields' => array(
        'boxes' => array(
            'label' => array('Textboxen', ''),
            'elementLabel' => '%s. Box',
            'inputType' => 'list',
            'minItems' => 1,
            'maxItems' => 5,
            'fields' => array(
                'text' => array(
                    'label' => array('Text', ''),
                    'eval' => array('rte' => 'tinyMCE'),
                    'inputType' => 'textarea',
                ),
            ),
        ),
    ),
);

<!-- rsce_boxes.html5 -->
<section class="<?php echo $this->class ?> block"<?php echo $this->cssID ?>>
    <<?php echo $this->hl ?>>
        <?php echo $this->headline ?>
    </<?php echo $this->hl ?>>
    <?php foreach ($this->boxes as $box): ?>
        <section class="box">
            <?php echo $box->text ?>
        </section>
    <?php endforeach ?>
</section>

Abhängige Felder "dependsOn"

Bei umfangreichen Elementen kommt es oft vor, dass gewisse Felder nur dann eingeblendet werden sollen wenn ein anderes Feld einen bestimmten Wert eingestellt hat. In Contao selbst werden dafür in der Regel palettes und subpalettes eingesetzt. In Custom Elements lässt sich dieses Problem mit der dependsOn-Einstellung lösen.

Um ein Feld nur dann anzuzeigen wenn eine bestimmte Checkbox aktiv ist, setzt man die Einstellung direkt auf den Feld-Namen der Checkbox 'dependsOn' => 'checkboxFeld' und schon erscheint das so konfigurierte Feld erst dann, wenn die Checkbox aktiviert wird.

Für komplexere Fälle kann auch direkt auf einen bestimmten Wert geprüft werden:

'dependsOn' => array(
    'field' => 'feldname',  // Name des Feldes das geprüft werden soll
    'value' => 'wert',      // Der Wert der mit dem Feldwert übereinstimmen muss
),

Auch eine Prüfung auf eine Auswahl mehrere Werte ist möglich:

'dependsOn' => array(
    'field' => 'feldname',              // Name des Feldes das geprüft werden soll
    'value' => array('wert1', 'wert2'), // Einer dieser Werte muss übereinstimmen
),

Icon-Picker Erweiterung

Weiters enthält RockSolid Custom Elements die Erweiterung rocksolid-icon-picker wodurch auch der Feldtyp rocksolid_icon_picker zur Verfügung steht und es ermöglicht ein Icon aus einem Icon-Font auszuwählen. Wenn man im vorherigen Beispiel nun für jede Box ein Icon möchte kann man den Code folgendermaßen erweitern:

<?php
// rsce_boxes_config.php
return array(
    'label' => array('Textboxen mit Überschrift', 'Erzeugt eine...'),
    'types' => array('content'),
    'contentCategory' => 'texts',
    'standardFields' => array('headline', 'cssID'),
    'fields' => array(
        'boxes' => array(
            'label' => array('Textboxen', ''),
            'elementLabel' => '%s. Box',
            'inputType' => 'list',
            'fields' => array(
                'icon' => array(
                    'label' => array('Icon', ''),
                    'inputType' => 'rocksolid_icon_picker',
                    'eval' => array(
                        'iconFont' => 'files/fonts/rocksolid-icons.svg',
                    ),
                ),
                'text' => array(
                    'label' => array('Text', ''),
                    'eval' => array('rte' => 'tinyMCE'),
                    'inputType' => 'textarea',
                ),
            ),
        ),
    ),
);

<!-- rsce_boxes.html5 -->
<section class="<?php echo $this->class ?> block"<?php echo $this->cssID ?>>
    <<?php echo $this->hl ?>>
        <?php echo $this->headline ?>
    </<?php echo $this->hl ?>>
    <?php foreach ($this->boxes as $box): ?>
        <section class="box" data-icon="&#x<?php echo $box->icon ?>;">
            <?php echo $box->text ?>
        </section>
    <?php endforeach ?>
</section>

@font-face {
    font-family: "RockSolid Icons";
    src: url("../fonts/rocksolid-icons.eot");
    src: url("../fonts/rocksolid-icons.eot?#iefix") format('eot'), 
         url("../fonts/rocksolid-icons.woff") format('woff'), 
         url("../fonts/rocksolid-icons.ttf") format('truetype'), 
         url("../fonts/rocksolid-icons.svg") format('svg');
}
*[data-icon]:before {
    content: attr(data-icon);
    font: 1em/1 "RockSolid Icons";
}

Beachten Sie dass der Pfad iconFont auf die SVG-Datei des Icon-Fonts zeigt. Um sicherzustellen dass die Icons im Contao-Backend auf allen Browsern korrekt dargestellt werden, sollten Sie zusätzlich zur SVG-Datei auch EOT-, WOFF- und TTF-Dateien mit dem gleichen Dateinamen im selben Ordner abspeichern.

Feldtyp "standardField"

Neben den oben angeführten vordefinierten standardFields ist es auch möglich jedes Feld aus tl_content oder tl_module an einer beliebigen Position zu verwenden und zu verändern. Verwenden Sie dafür als inputType den Wert standardField. In folgendem Beispiel werden drei Felder aus tl_content übernommen und teilweise verändert:

<?php
// rsce_my_element_config.php
return array(
    'label' => array('Mein Element', 'Meine Beschreibung...'),
    'types' => array('content'),
    'fields' => array(
        'multiSRC' => array(
            'inputType' => 'standardField',
        ),
        'headline' => array(
            'inputType' => 'standardField',
            'options' => array('h2', 'h3'),
        ),
        'text' => array(
            'label' => array('Text', 'Hilfetext...'),
            'inputType' => 'standardField',
            'eval' => array(
                'mandatory' => false,
            ),
        ),
    ),
);

'inputType' => 'standardField' kann nur in der obersten Ebene verwendet werden. Der Einsatz innerhalb des Feldtyp "list" ist nicht möglich.

Feldtyp "group"

Mit dem inputType group können Eingabefelder in Bereiche unterteilt werden. Dazu fügen Sie ein group-Feld an der Stelle ein wo ein neuer Bereich beginnen soll. Beispiel:

<?php
// rsce_my_element_config.php
return array(
    'label' => array('Mein Element', 'Meine Beschreibung...'),
    'fields' => array(
        'headline' => array(
            'label' => array('Überschrift', ''),
            'inputType' => 'text',
        ),
        'description' => array(
            'label' => array('Beschreibungen', 'Fügen Sie hier Ihre Beschreibungstexte ein.'),
            'inputType' => 'group',
        ),
        'text' => array(
            'label' => array('Text', ''),
            'inputType' => 'textarea',
        ),
    ),
);

Feldtyp "url"

Verwenden Sie als inputType den Wert url um ein Textfeld zu erzeugen mit der Option eine Seite aus der Seitenstruktur auszuwählen. Ein solches Textfeld finden Sie auch im Contao-Core im Inhaltselement Text unter Bildlink-Adresse.

Mehrsprachige Labels

Wenn Ihr Element im Backend in verschiedenen Sprachen angezeigt werden soll, können Sie bei allen label und elementLabel Einträgen Bezeichnungen für mehrere Sprachen hinterlegen. Beispiel:

<?php
return array(
    'label' => array(
        'de' => array('Mein Element', 'Meine Beschreibung...'),
        'en' => array('My Element', 'My description...'),
    ),
);

Beispiel herunterladen

Beispiel-Element für eine Teamseite herunterladen

Tipp für Module, die nicht in den Contao-Suchindex aufgenommen werden sollen

Module, die auf mehreren Seiten vorkommen (z.B. Kontaktboxen, Öffnungszeiten...) und die deshalb nicht in den Suchindex aufgenommen werden sollen können Sie mit folgendem Code ausschließen:

<!-- indexer::stop -->

    <div>Ihr Inhalt</div>

<!-- indexer::continue -->

Hinweis: Die Leerzeilen davor und danach können, je nach Position des Elements, eine Rolle spielen und sollten nicht weggelassen werden.

Gab es Unklarheiten oder haben Sie einen Fehler in diesem Artikel entdeckt? Geben Sie uns Bescheid und hinterlassen Sie Ihr Feedback.