Contao-Bootstrap Dokumentation

Handbuch

Einführung

Die Erweiterung Contao-Bootstrap integriert das Frontend-Framework Bootstrap 3 in das Open Source Content Management System Contao. Als modulare Erweiterung setzt sie voll auf die Vorzüge der Composer-Paket-Verwaltung für Contao.

Diese Dokumentation setzt gute Kenntnisse über die Verwendung Contao als auch Bootstrap 3 voraus.

Kosten

Die Erweiterung kostet mich Zeit zum Entwickeln, Testen, Support leisten, Dokumentation schreiben usw. Nur ein Teil davon kann ich über eigene Projekte refinanzieren.

Contao-Bootstrap wird als Open-Source-Software unter der LGPL sowie kostenfrei angeboten. Das Projekt ist aber auf die Mitarbeit sowie auf finanzielle Unterstützung angewiesen um die kontinuierliche Weiterentwicklung sicherzustellen.

Zwischen zwei Konventionen

Sowohl Contao als auch Bootstrap verfolgen einen eigenen Weg, die sich in der Namensgebung von CSS-Klassen als auch der vorgegebenen HTML-Struktur widerspiegelt.

Contao-Bootstrap unterstüzt verfolgt den Ansatz Contao über Template-Anpassungen, eigene Module bzw. in einem sinnvollen Maße durch dynamische Anpassung von CSS-Klassen.

Bootstrap Framework

Contao-Bootstrap integriert nicht das Bootstrap-Framework. Dies liegt in der Verantwortung des Benutzers. Dadurch ist die Erweiterung vollständig unabhängig von dem bevorzugten CSS- und Javascript-Workflow. Ob CSS, Less, Sass - es werden keine Vorgaben gemacht. Möglichkeiten zur Integration werden im Bootstrap Framework einbinden aufgezeigt.

Modulare Architektur

Bootstrap für Contao ist vollständig modular aufgebaut. Dies ermöglicht schnellere Bugfixes und Weiterentwicklung einzelner Komponenten. Einzelne Komponenten können unabhängig voneinander genutzt werden, sodass eine schlanke bedarfsgerechte Installation möglich ist.

Danksagung

Contao-Bootstrap ist ein Open-Source-Projekt, das erst durch die Mit- und Vorarbeit vieler Menschen möglich wurde und denen der Dank gilt.

Dokumentation

  • ...

Die Dokumentation wird über Github verwaltet und benötigt freiwillige Helfer.

Übersetzungen

Die Übersetzungen der Erweiterung werden über Transifex verwaltet und benötigen freiwillige Helfer. Die Dokumentation wird direkt im Repository eingepflegt.

Bisher an den Übersetzungen mitgewirkt haben:

Software

Open-Source-Software folgender Projekte bzw. Organisationen machen Contao-Bootstrap erst möglich:

Installation

Contao-Bootstrap ist eine modular aufgebaute Erweiterung. Je nach Anforderungen können die gewünschten Komponenten ausgewählt und installiert werden.

Bundle

Dank des Bundles gibt es einen komfortablen Weg alle Pakete von Contao-Bootstrap auf einmal zu installieren. Da das Bundle selbst keine Versionen vorgibt, empfiehlt es sich zusätzlich die Abhängigkeit zur Core Komponente zu setzen.

{
    "require": {
        "contao-bootstrap/core": "~1.0"
        "contao-bootstrap/bundle": "*"
    }
}

Einzelne Komponenten

Dank des modularen Aufbaus der Erweiterung ist es problemlos möglich nur einzelne Komponenten zu installeren und zu verwenden. Auch dies ist über die Composer möglich.

Beispiel Installation Formular-Komponente:
{
    "require": {
        "contao-bootstrap/form": "~1.0"
    }
}

Optionale Erweiterungen

Contao-Bootstrap unterstützt einige Erweiterungen und greift somit auf bereits vorhandene Funktionen zurück. Diese werden nicht als Abhängigkeiten installiert, sondern können über die gewohnte Installation von Erweiterungen über den Composer-Client installiert werden.

Komponenten

Core

Die Core Komponente ist das Herzstück der Contao-Bootstrap Erweiterung, auch wenn viele der Funktionen für den Benutzer nicht sichtbar sind. Daher setzen alle weiteren Komponenten die Installation des Cores voraus.

Installation
{
    "require": {
        "contao-bootstrap/core": "~1.0"
    }
}
Konfiguration

Contao-Bootstrap ist eine flexible Erweiterung, die viele, teilweise versteckte Konfigurationsmöglichkeiten bietet. Sie kommt jedoch mit einer Standard-Konfiguration, sodass für viele Fälle keine Anpassung der Konfiguration erforderlich ist.

Die Konfiguration erfolgt (historisch bedingt) an zwei Stellen. Zum einem kann man unter Systemeinstellungen > Bootstrap globale Konfigurationen vornehmen. Der Core bietet hier die Wahl des Iconsets an. Zum anderen kann für das erstellte Theme themespezifische Anpassungen vorgenommen werden (Themes > Bootstrap Konfiguration).

Funktionen
Bootstrap-Layout

Contao-Bootstrap setzt auf das Layout-Konzept von Contao auf und führt einen Layouttyp ein. Da einige Funktionen dynamisch im Hintergrund ausgeführt werden, besitzen Sie so die Kontrolle, wann diese Funktionen greifen.

Layouttyp

Durch den Layouttyp Bootstrap werden Funktionen der Bootstrap-Erweiterung aktiviert.

Konfigurationssystem

Contao-Bootstrap arbeitet mit einem eigenen Konfigurationssystem. Mit diesem lassen sich viele Funktionen aktivieren, deaktivieren sowie modifizieren. Ein Bestandteil des Systems ist die Backend-Konfiguration. Diese wird von einigen Komponenten genutzt um verschiedene Konfigurations-Typen anzubieten.

Konfigurationstypen

Durch den modularen Aufbau von Contao-Bootstrap hängt die zur Verfügung stehenden Konfigurationsmöglichkeiten von den installierten Komponenten ab. Jeder Typ kann im Backend mehrfach angelegt werden. Nur die aktivierten Einstellungen greifen dann auch. Die Konfigurationstypen unterscheiden sich zwischen:

  • Lokale Konfiguration gilt nur in Layouts des übergeordneten Themes.
  • Globale Konfiguration gilt in der gesamten Contao-Installation.
Konfiguration anpassen

Bei der Verwaltung der Konfiguration wird zwischen Neue Konfiguration anlegen und Konfiguration überschreiben unterschieden.

  • Neue Konfiguration anlegen ist dafür konzipiert um noch nicht konfigurierte Funktionen in das System zu integrieren. Dies sind in erster Linie neue Iconsets, können aber beispielsweise auch unkonfigurierte Formular- Widgets sein.
  • Mit Konfiguration überschreiben kann die bereits bestehende Konfiguration überschrieben und erweiteret werden. Da Contao-Bootstrap bereits vorkonfiguriert ist, ist dies wohl die gängige Variante. Beim Überschreiben einer Konfiguration, werden die bestehenden Einstellungen importiert.
Bootstrap-Konfiguration

Als Teil der Themes wird die Bootstrap-Konfiguration im Backend verwaltet.

Bemerkung

Globale Konfigurationstypen beeinflussen die gesamte Installation und können daher ungewollte Auswirkungen auf andere Themes haben. Daher zeigt Contao-Bootstrap einen Warnhinweis im Backend an.

Icon-Sets

Bootstrap 3 unterstützt von Haus aus die Glyphicons. Contao-Bootstrap bietet daher die Unterstützung von Icons-Sets an. Dabei ist die Unterstützung offen gehalten, sodass weitere Icons genutzt werden können. Im Kochbuch ist die Integration eigener Iconsets beschrieben: Weitere Iconsets einbinden.

Icons können innerhalb der Contao-Bootstrap Erweiterung unterschiedlich verwendet werden.

  • Auswahl über den Icon-Wizard durch Elemente mit direkten Icon-Support
  • Verwendung des Icon-Insert-Tags {{icon::icon-name}}. Das HTML-Markup wird automatisch generiert. Der Insert-Tag ist somit der ideale Helfer um Icons in Eingabefelder ohne HTML Unterstützung oder im TinyMce unterzubringen.

Tipp

Die Contao Erweiterung netzmacht/contao-font-awesome integriert nahtlos in Contao-Bootstrap.

Für Entwickler
Ressourcen

Buttons

Installation
{
    "require": {
        "contao-bootstrap/buttons": "~1.0"
    }
}
Funktionen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Für Entwickler

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Ressourcen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Formular

Installation
{
    "require": {
        "contao-bootstrap/form": "~1.0"
    }
}
Funktionen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Für Entwickler

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Ressourcen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Grid-Editor

Installation
{
    "require": {
        "contao-bootstrap/grid-editor": "~1.0"
    }
}
Funktionen

Mit Hilfe des Grid-Editors kann man verschiedene Spaltenlayouts konfigurieren. Diese Spaltenlayouts können dann mit Hilfe der Contao Erweiterungen semantic_html5 oder subcolumns auf Inhalte, wie beispielsweise Artikel oder Formulare, angewendet werden. In diesem Zusammenhang spricht man auch von einem Grid System. Das Bootstrap Grid besteht standardmäßig aus 12 Spalten die man individuell für jeden Viewport konfigurieren kann.

Einen guten Überblick über den Aufbau des Bootstrap Grid findet man auf der Webseite getbootstrap.com.

Aufgerufen wird der Grid-Editor über das Backendmodul Spaltensets. Dieses befindet sich unter dem Menüpunkt Layout.

_images/spaltensets.png
Erstellung eines Spaltensets mit 3 Spalten für verschieden Viewports

Über den Grit Editor soll ein Spaltenlayout mit folgenden Anforderungen erstellt werden:

  • Bei mittlerer und großer Auflösung (Notebook und PC) soll der Inhalt über 3 Spalten ausgegeben werden.
  • Bei Geräten mit kleiner Auflösung (Tablet) soll der Inhalt in 2 Spalten ausgegegeben werden.
  • Bei Geräten mit extra kleinen Auflösung (Smartphone) soll der Inhalt jeweils in einer Spalte ausgegeben werden.

Wie schon erwähnt besteht das Bootstrap Grid standardmäßig aus 12 Spalten. Eine Spalte welche sich über die gesamte Breite der Webseite erstrecken soll wäre also 12 Einheiten breit. Zwei gleich große Spalten wären dann jeweils 6 Einheiten breit (6+6=12). Möchte man 3 Spalten mit gleicher Breite darstellen wird das ganze mathematisch nicht viel schwieriger, die Spaltenbreite beträgt 4 (4+4+4=12).

Bei den Einheiten handelt es sich immer um Prozentangeben. Spaltenbreite 12 entspricht 100%, Spaltenbreite 6 entspricht 50 %, Spaltenbreite 4 entspricht 33.3333% usw.

Über den Spaltenabstand kann man den Abstand links der Spalte definieren. Dabei sollte man aber beachten daß die Summe der Spaltenbreite und des Spaltenabstands 12 ergibt.

_images/modul_spaltensets.png

Nachdem man ein Spaltenset definiert hat, kann man es mit Hilfe der Contao Erweiterung semantic_html5 oder subcolumns anwenden.

Verwendung eines Spaltensets mit sematic_html5

Um beispielsweise einen Artikel, bestehend aus 3 Spalten mit Hilfe von semantic_html5 zu erstellen geht man wie folgt vor:

Unter Artikel fügt man als erstes ein Element vom Typ HTML5-Element hinzu. Als HTML5 Element verwendet man am besten div. Unter Bootstrap Grid-Element verwenden wählt man Zeile(row) aus und selektiert das zuvor erstellte Spaltenset.

_images/html5_row.png

Dadurch wird ein div Container mit der Bootstrap Klasse row erzeugt.

Innerhalb des div Containers wird als nächstes ein weiteres Element von Typ HTML5-Element erzeugt. Unter Bootstrap Grid-Element verwenden wählt man jetzt Spalte und es wird automatisch das Feld Zugeordnetes Grid-Element ausgewählt.

_images/html5_spalte.png

Folgende verschachtelte DIV Container sind entstanden:

_images/artikel_1.png

Im inneren DIV Container wird anschließend der Inhalt der ersten Spalte erstellt. Für den Inhalt der zweiten Spalte benötigt man anschließend wieder einen DIV Container vom Typ HTML5-Element als Bootstrap Grid-Element Spalte.

_images/html5_artikel_backend.png

Die Ausgabe auf den verschiedenen Viewports im Frontend stellt sich dann so dar:

Ausgabe bei Viewport Medium und Large (Desktop):

_images/html5_artikel_md.png

Ausgabe bei Viewport Small (Tablet):

_images/html5_artikel_sm.png

Ausgabe bei Vieport ExtraSmall (Phone):

_images/html5_artikel_xs.png
Verwendung eines Spaltensets mit subcolumns und Formularen

Im folgenden sollen die Formularelemnte eines einfachen Formulars in Abhängigkeit der verschiednen Displaygrößen in Spalten dargestellt werden.

  • Auf Smartphones und Tablets sollen die Formularelemente in einer Spalte dargestellt werden.
  • Bei Geräten mit großen und sehr großen Displays sollen die Formularfelder in zwei Spalten nebeneinander dargestellt werden.

Dazu erstellt man ein Spaltenset mit zwei Spalten:

_images/spaltenset_form.png

Anschließend wechselt man in den Formulargenerator und fügt im enstprechenden Formular einen neuen Feldtyp Spaltenset Startelement vor dem ersten Formularelement ein. Im Auswahlfeld “Unterspalten” wählt man 2 aus. Anschließend kann man unter Spaltenset das zuvor erstellte Spaltenset auswählen.

_images/subcolumns_form.png
Es werden automatisch 3 Formularelemente erstellt:
  • Spaltenset-Startelement
  • Spaltenset-Trennelement
  • Spaltenset-Endelement

Als nächstes verschiebt man die Formularelemente welche in der linken Spalte plaziert werden sollen, zwischen den Spaltenset-Startelement und den Spaltenset-Trennelement. Formularelemente welche in der rechten Spalte plaziert werden sollen verschiebt man zwischen das Spaltenset-Trennelement und den Spaltenset-Endelement.

_images/subcolumns_form_liste.png

Die Ausgabe auf den verschiedenen Viewports im Frontend stellt sich dann so dar:

Ausgabe bei Viewport Medium und Large (Desktop):

_images/subcolumns_form_md.png

Ausgabe bei Viewport Small (Tablet):

_images/subcolumns_form_sm.png

Ausgabe bei Vieport ExtraSmall (Phone):

_images/subcolumns_form_xs.png
Änderung der Spaltenreihenfolge

Bei der Konfiguration von Spaltensets gibt es noch die Konfigurationsmöglichkeit Reihenfolge. Über diesen Punkt kann man die Reihenfolge der Spalten individuell für jeden Vieport gestalten.

Ein Beipiel:

_images/spaltenset_reihenfolge.png

Dadurch wird im Frontend für den Viewport Mittlere Auflösung (md) der Inhalt der zweiten Spalte mit der ersten Spalte getauscht. (Spalte 1 wird 4 Einheiten nach rechts gepusht, Spalte 2 wird 4 Einheiten nach links gepullt.)

_images/spaltenset_reihenfolge_frontend.png

Bei allen anderen Viewports hat sich die Reihenfolge nicht verändert.

Für Entwickler

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Ressourcen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Layout

Installation
{
    "require": {
        "contao-bootstrap/layout": "~1.0"
    }
}
Funktionen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Für Entwickler

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Ressourcen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Panel

Installation
{
    "require": {
        "contao-bootstrap/panel": "~1.0"
    }
}
Funktionen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Für Entwickler

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Ressourcen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Tab

Installation
{
    "require": {
        "contao-bootstrap/tab": "~1.0"
    }
}
Funktionen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Für Entwickler

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Ressourcen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Templates

Installation
{
    "require": {
        "contao-bootstrap/templates": "~1.0"
    }
}
Funktionen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Für Entwickler

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Ressourcen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Ressourcen

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Kochbuch

Kochbuch

Migration von netzmacht/contao-bootstrap

Die Erweiterung contao-bootstrap existierte erstmal als Komplettpaket unter netzmacht/contao-bootstrap. Auch wenn contao-bootstrap daraus hevorgegangen ist, so hat sich dessen Interna an vielen Stellen geändert. Eine Migration einer Contao-Installation auf die neue Version sollte daher mit Bedacht vorgenommen werden.

Seit dem Release des Grid-Editors 1.0.0 wurde ein Migrationsskript hinzugefügt, der die Spaltensetzuweisung aktualisiert, sodass die Datenbankstruktur prinzipiell kompatibel ist. Jedoch empfehle ich dringend ein Update nur in einer Testumgebung durchzuführen.

Checkliste
Nicht mehr unterstützte Funktionen

Nicht mehr unterstützte Funktionen müssen überprüft werden und ggf. durch andere Funktionen ersetzt werden.

Abhängige Erweiterungen

Die vorherige Version netzmacht/contao-bootstrap hat einige Erweiterungen vorausgesetzt und automatisch mit installiert. Sollen diese weiterhin eingesetzt werden, so sind die nachzuinstallieren.

Dies betrifft vor allem:

  • Theme+
  • Subcolumns
Templateänderungen

Vor allem die Templates haben sich geändert. Angepasste Templates müssen dementsprechend überprüft werden und ggf. angepasst.

Assets

Die Bootstrap Assets werden nicht mehr mitgeliefert und müssen nun selbst eingebunden werden.

Empfehlenswert können z.b. die components/bootstrap Pakete sein.

Bootstrap Framework einbinden

Quellen
  • components/bootstrap
  • twbs/bootstrap
  • Theme files
Boardmittel nutzen

Der Bootstrap Code lässt sich von getbootstrap.com downloaden und auf dem eigenen Server speichern und dann lokal in Contao in das Seitenlayout einbinden, oder alternativ als CDN direkt in das Seitenlayout in dem Feld Zusätzliche <head>-Tags einbinden.

Theme+

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Weitere Iconsets einbinden

Hinweis

Dieser Bereich ist noch nicht dokumentiert. Für die Dokumentation werden Unterstützer gesucht. Du kannst an der Dokumentation mitarbeiten oder durch eine finanzielle Unterstützung zur Vervollständigung der Dokumentation beitragen.

Verzeichnisse