Search by

berecont / contao-html-attributes-bundle

berecont

Fügt ausgewählten Contao-Inhaltselementen konfigurierbare benutzerdefinierte HTML-Attribute hinzu.

Package info

github.com/berecont/contao-html-attributes-bundle

Type:contao-bundle

pkg:composer/berecont/contao-html-attributes-bundle

Security

Advisories: 0

Aikido package health analysis

Transparency log

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

1.1.0 2026-09-11 21:25 UTC

Requires

Requires (Dev)

Suggests

None

Provides

None

Conflicts

Replaces

None

MIT 317357edfcda95692ada8738807f7209eb89de7a

htmlattributescontaocontent-elementsdata-attributes

Published on Packagist.org on 2026-09-12 05:30 UTC

This package is auto-updated.

Last update: 2026-09-12 05:30:45 UTC

README

Mit dem Contao HTML Attributes Bundle können Inhaltselemente in Contao ab Version 5.7 um zusätzliche HTML-Attribute ergänzt werden.

Die Attribute werden komfortabel über den rowWizard im Bereich Experteneinstellungen gepflegt und am äusseren Wrapper des Inhaltselements ausgegeben.

Anwendungsfälle sind beispielsweise:

data-controller="timeline"
data-animation="fade"
aria-label="Weitere Informationen"
role="region"
style="--animation-delay: 200ms"

Auch Insert-Tags können in den Attributwerten verwendet werden.

aria-label="aktuelles Jahr {{date::Y}}"

Voraussetzungen

  • PHP ^8.3 || ^8.4
  • Contao ^5.7

Installation

Composer

composer require berecont/contao-html-attributes-bundle

Das Bundle wird als Composer-Paket in einer Contao-Installation eingebunden. Nach der Installation bzw. nach Änderungen am Bundle sollte der Anwendungscache geleert werden:

php vendor/bin/contao-console cache:clear

Contao Manager

Unter Pakete nach berecont/contao-html-attributes-bundle suchen, auswählen und installieren.

Verwendung

Für freigeschaltete Inhaltselemente erscheint unter Experteneinstellungen neben dem Contao-Feld CSS-ID/Klasse das zusätzliche Feld:

Zusätzliche HTML-Attribute

Die Eingabe erfolgt zeilenweise mit zwei Feldern - zum Beispiel:

Attribut Wert
data-controller timeline
data-animation fade
aria-label Timeline {{date::Y}}
role region

Daraus wird beispielsweise:

<div
    class="content-text"
    data-controller="timeline"
    data-animation="fade"
    aria-label="Timeline 2026"
    role="region"
>
    ...
</div>

Konfiguration der Inhaltselemente

Standardmässig sind keine Felder für Contao-Inhaltselemente aktiviert.
Vorbereitet (auskommentiert) in der src/BerecontContaoHtmlAttributesBundle.php sind jedoch:

text
element_group

    public function configure(DefinitionConfigurator $definition): void
    {
        $definition->rootNode()
            ->children()
                ->arrayNode('content_elements')
                    ->scalarPrototype()->end()
                    ->defaultValue([
                        // 'text',
                        // 'element_group',
                    ])
                ->end()
            ->end()
        ;
    }

Inhaltselemente werden in der Projektkonfiguration unter config/config.yaml freigeschalten.

Beispiel:

berecont_contao_html_attributes:
    content_elements:
        - text
        - element_group
        - image

Die Liste ist eine Positivliste. Das Feld wird ausschliesslich bei den dort eingetragenen Inhaltselement-Typen angezeigt.

Dadurch erhalten neu installierte oder anderweitig registrierte Inhaltselemente nicht automatisch zusätzliche HTML-Attribute.

Hinweis: Sollte in der Contao-Installation noch keine config/config.yaml vorhanden sein, so muss diese manuell angelegt werden.

Eigene Inhaltselemente und RSCE

Die Konfiguration ist nicht auf Core-Inhaltselemente beschränkt. Es kann grundsätzlich jeder vorhandene tl_content.type eingetragen werden.

Beispiel mit einem RockSolid Custom Element:

berecont_contao_html_attributes:
    content_elements:
        - text
        - element_group
        - image
        - rsce_servicecard

Damit kann das Feld auch gezielt für eigene Content Elements oder Inhaltselemente anderer Extensions aktiviert werden.

Insert-Tags

Insert-Tags sind in den Werten der HTML-Attribute möglich.

Beispiel:

Attribut Wert
aria-label Wir schreiben das Jahr {{date::Y}}

Im Frontend wird der Insert-Tag erst beim Rendern ersetzt:

aria-label="Wir schreiben das Jahr 2026"

Der ursprüngliche Insert-Tag bleibt dabei in den gespeicherten Daten erhalten.

Klassen

Das Attribut class darf zusätzlich verwendet werden.

Vorhandene Klassen des Contao-Inhaltselements werden dabei nicht überschrieben, sondern mit den zusätzlichen Klassen zusammengeführt.

Beispiel:

Contao CSS-ID/Klasse:

btn-primary

Zusätzliches HTML-Attribut:

Attribut Wert
class btn

Kann beispielsweise ergeben:

<div class="btn-primary content-text btn">

ID

Das Attribut id ist über Zusätzliche HTML-Attribute bewusst nicht erlaubt.

Für die HTML-ID soll das bereits vorhandene Contao-Feld CSS-ID/Klasse verwendet werden.

Beispiel:

CSS-ID: testid

ergibt:

<div id="testid" ...>

Ein zusätzlich eingetragenes Attribut wie

Attribut Wert
id andere-id

wird ignoriert und überschreibt die CSS-ID nicht.

Event-Handler

Inline-JavaScript-Eventhandler sind aus Sicherheits- und Wartbarkeitsgründen nicht erlaubt.

Beispiele:

onclick
onload
onerror
onmouseover

Solche Attribute werden bei der Frontend-Ausgabe verworfen.

Für JavaScript-Logik sollten stattdessen beispielsweise data-*-Attribute verwendet und anschliessend über externes JavaScript oder einen Controller verarbeitet werden:

data-controller = gallery
data-action     = open

Leere und boolesche Attribute

Attribute dürfen einen leeren Wert besitzen.

Beispiel:

Attribut Wert
hidden

Die Ausgabe kann dann beispielsweise lauten:

hidden=""

Das ist gültiges HTML. Bei booleschen Attributen wie hidden ist das Vorhandensein des Attributes entscheidend.

Unterstützte Attribute

Das Bundle ist bewusst nicht auf data-* beschränkt.

Mögliche Beispiele sind:

data-controller
data-animation
data-wow-duration
aria-label
aria-describedby
role
title
style
class
hidden

Grundsätzlich werden gültige HTML-Attributnamen akzeptiert.

Ausgenommen sind insbesondere:

id
onclick
onload
onerror

sowie andere mit on beginnende Event-Handler.

Speicherung

htmlAttributes ist ein virtuelles DCA-Feld.

Es wird keine zusätzliche Datenbankspalte in tl_content benötigt. Unter Contao 5.7 werden die Daten über jsonData des Inhaltselements gespeichert.

Template-Ausgabe

Die zusätzlichen Attribute werden zentral am Wrapper der Content Elements ergänzt.

Das Bundle erweitert dazu:

contao/templates/content_element/_base.html.twig

Dadurch müssen die einzelnen Templates der freigeschalteten Inhaltselemente normalerweise nicht angepasst werden.

Beispielausgabe:

<div
    id="testid"
    class="btn-primary content-text btn"
    aria-label="Wir schreiben das Jahr 2026"
    data-animation="fade"
    style="background: red;"
    role="button"
>
    ...
</div>

Beispiel Backend

Beispieldarstellungen

Hinweise

Das Bundle kann Attribute nur an Inhaltselementen ausgeben, die einen entsprechenden HTML-Wrapper über das Contao Content-Element-Template besitzen.

Bei speziellen Inhaltselementen oder Extensions mit vollständig eigener Template-Struktur kann daher eine gesonderte Integration notwendig sein.

Lizenz

Siehe LICENSE.