README

Diese Erweiterung stellt ein Inhaltselement bereit, mit dem sich Quellenangaben und Literaturhinweise unter einem Beitrag ausgeben lassen — also der klassische Block „Quellen“ am Ende eines Artikels.

Die Quellen werden im Backend zeilenweise gepflegt. Jede Zeile besteht aus einem Text und/oder einer URL und kann einzeln aktiviert bzw. deaktiviert werden. Im Frontend entsteht daraus eine nummerierte Liste.

Läuft mit: Contao 4.13 LTS und Contao 5, PHP 8.1 oder neuer
Benötigt: MultiColumnWizard (wird automatisch mitinstalliert)

Installation

Über den Contao Manager nach schachbulle/contao-references-bundle suchen und installieren, oder auf der Kommandozeile:

composer require schachbulle/contao-references-bundle

Anschließend im Contao-Installtool bzw. per contao:migrate die Datenbank aktualisieren. Dabei entstehen in tl_content die beiden Felder referenzen und referenzen_headline.

Bedienung im Backend

Das Inhaltselement heißt Quellennachweis und steht in der Gruppe Texte zur Auswahl. Nach dem Anlegen erscheint der Bereich Einstellungen mit diesen Feldern:

Feld	Bedeutung
Standardüberschrift ausgeben	Ist die Checkbox gesetzt (Voreinstellung), lautet die Überschrift automatisch „Quelle“ bzw. „Quellen“ — je nachdem, wie viele Einträge aktiv sind. Eine im Feld Überschrift eingetragene eigene Überschrift wird dann ignoriert; die dort gewählte Ebene (h1–h6) bleibt aber erhalten. Ohne Haken erscheint die eigene Überschrift.
Quellen	Die eigentliche Liste. Über das Plus-Zeichen werden weitere Zeilen angelegt, über die Pfeile lassen sie sich sortieren.

Jede Zeile der Quellenliste besteht aus vier Spalten:

Spalte	Bedeutung
Aktiv	Nur aktive Zeilen werden ausgegeben. So lässt sich eine Quelle vorübergehend ausblenden, ohne sie zu löschen.
Text	Die Quellenangabe, z. B. „Deutsche Schachzeitung 4/2017, S. 12“. HTML ist erlaubt, `<em>` oder `<strong>` funktionieren also.
URL	Optionales Verweisziel. Neben dem Feld liegt der Contao-Auswahlknopf, mit dem sich statt einer externen Adresse auch eine Seite der eigenen Website auswählen lässt (es wird dann ein Insert-Tag `{{link_url::…}}` eingetragen).
Neues Fenster	Öffnet den Verweis in einem neuen Fenster (`target="_blank"` mit `rel="noreferrer noopener"`).

Wie die drei Felder zusammenspielen:

Text und URL → der Text wird zum Verweis.
nur URL → die URL dient selbst als Beschriftung des Verweises.
nur Text → die Zeile bleibt unverlinkt.
beides leer → die Zeile wird übersprungen, es entsteht keine leere Listenzeile.

Ausgabe im Frontend

Ausgegeben wird eine unsortierte Liste innerhalb von div.ce_references. Ab zwei Einträgen wird jeder Eintrag mit seiner Nummer in eckigen Klammern eingeleitet; bei einer einzelnen Quelle entfällt die Nummerierung.

<div class="ce_references block">
  <h3>Quellen</h3>
  <ul>
    <li>[1] <a href="https://de.wikipedia.org/wiki/Schach">Wikipedia: Schach</a></li>
    <li>[2] Deutsche Schachzeitung 4/2017, S. 12</li>
  </ul>
</div>

Ein zurückhaltendes Standard-Design (kursive, graue Einträge mit quadratischen Aufzählungszeichen) bringt die Erweiterung unter bundles/contaoreferences/css/default.css mit (im Web-Verzeichnis der Installation). Die Datei wird nur eingebunden, wenn das Element auf der Seite auch vorkommt. Wer das nicht möchte, überschreibt die Regeln im eigenen Stylesheet oder verwendet ein eigenes Template (siehe unten).

Eigenes Template

Das Element benutzt das Template ce_references. Ein eigenes Template wird wie üblich unter templates/ angelegt (z. B. ce_references_kompakt.html5) und im Element unter Template-Einstellungen ausgewählt.

Im Template stehen zusätzlich zu den üblichen Contao-Variablen zur Verfügung:

Variable	Inhalt
`$this->references`	Array der auszugebenden Einträge, siehe unten
`$this->references_count`	Anzahl der Einträge — praktisch, um die Nummerierung erst ab zwei Quellen anzuzeigen

Jeder Eintrag in $this->references ist ein Array mit diesen Schlüsseln:

Schlüssel	Inhalt
`nummer`	Fortlaufende Nummer, beginnend bei 1 (deaktivierte und leere Zeilen zählen nicht mit)
`text`	Die fertige Ausgabe: entweder der reine Text oder der komplette `<a>`-Verweis
`label`	Nur die Beschriftung ohne Verweis (bei fehlendem Text die URL)
`url`	Die hinterlegte URL, ggf. als Insert-Tag; leer, wenn kein Verweis gepflegt ist
`target`	`true`, wenn der Verweis in einem neuen Fenster geöffnet werden soll

Ein minimales eigenes Template als nummerierte Liste sähe damit so aus:

<?php $this->extend('block_searchable'); ?>

<?php $this->block('content'); ?>
  <?php if ($this->references): ?>
    <ol>
    <?php foreach ($this->references as $item): ?>
      <li><?= $item['text'] ?></li>
    <?php endforeach; ?>
    </ol>
  <?php endif; ?>
<?php $this->endblock(); ?>

Hinweise zum Umstieg von Version 3.x

Die Erweiterung setzt jetzt PHP 8.1 und Contao 4.13 oder 5 voraus.
Das Feld „Gästen anzeigen“ (guests) ist aus der Palette verschwunden, weil es in Contao 5 nicht mehr existiert. Der Schutz über Mitgliedergruppen (Zugriffsschutz) bleibt unverändert erhalten.
Der Auswahlknopf neben dem URL-Feld benutzt jetzt den regulären Contao-Picker. Bereits gespeicherte Werte — auch Insert-Tags aus dem alten Seitenwähler — funktionieren unverändert weiter.
Vorhandene Datensätze müssen nicht angefasst werden; das Datenformat ist gleich geblieben.

Entwickler

Frank Hoppe

schachbulle / contao-references-bundle

Maintainers

Package info

Statistics

Security