README

ChurchTools für Contao

Bringt Termine samt Flyer und Personen aus ChurchTools auf eine Contao-Website - ohne die Daten doppelt zu pflegen.

Kompatibel mit Contao 5.7 LTS und PHP ^8.3. Ausschließlich Twig-Templates, damit der Wechsel auf Contao 6 nichts kostet. Verifiziert gegen ChurchTools 3.135.

Funktionen

Termin-Abgleich aus beliebig vielen ChurchTools-Kalendern in ganz normale Contao-Events - Listen, Reader, Suche und Feeds funktionieren unverändert
Flyer vom Termin werden mitgeholt, inklusive Fokuspunkt für sauberen Zuschnitt in Listenansichten
Serien, Ausnahmen und Zusatztermine werden korrekt abgebildet
Personen als Insert-Tag oder Inhaltselement - entweder fest gewählt oder als Rolle („die Leitung der Gruppe X"), die automatisch mitwechselt
Personenauswahl per Namenssuche im Backend statt per ID
Inhaltselement „Termin-Flyer": zeigt die Flyer der nächsten Termine, vorbei ist vorbei
Mandantenfähig - mehrere Websites in einer Contao-Installation können auf verschiedene ChurchTools-Instanzen zugreifen
Datenschutz eingebaut: ausgeliefert wird nur, wer ausdrücklich freigegeben ist

Was das Bundle nicht tut: Es baut nichts nach, was ChurchTools bereits kann. E-Mail-Versand, Routinen, Follow-ups und Anmeldelogik bleiben dort.

Installation

composer require samuelheer/contao-churchtools-bundle
vendor/bin/contao-console contao:migrate

Alternativ über den Contao Manager nach samuelheer/contao-churchtools-bundle suchen.

Einrichtung

1. Dienstkonto in ChurchTools

Eine eigene Person mit eigener Berechtigungsgruppe anlegen, die nur Leserechte auf die freizugebenden Kalender und Gruppen hat, und dafür unter Persönliche Einstellungen → Logintoken ein Token erzeugen.

Kein persönliches Token verwenden. Es hängt an einem Menschen, stirbt mit dessen Konto und schreibt jede Änderung im ChurchTools-Log auf dessen Namen.

2. Token in die Umgebung

# .env.local
CHURCHTOOLS_TOKEN_MAIN=…

Das Token wird nie in der Datenbank gespeichert - im Backend steht nur der Name der Variablen. So landet es weder in einem Datenbank-Backup noch in einem Export.

3. Verbindung anlegen

Backend → System → ChurchTools-Verbindungen

Feld	Bedeutung
Bezeichnung	Name der Gemeinde bzw. Instanz
Adresse	Basis-URL, z. B. `https://example.church.tools`
Name der Umgebungsvariablen	z. B. `CHURCHTOOLS_TOKEN_MAIN` - nicht das Token selbst
Ordner für Bilder	Zielordner für importierte Flyer, z. B. `files/gemeinde/churchtools`
Freigabegruppe für Personen	ID der Gruppe, die entscheidet, wer auf der Website erscheinen darf
Freigabegruppe für Bilder	optional. Leer: Das ChurchTools-Profilfoto erscheint bei jeder freigegebenen Person. Mit Gruppe: nur bei deren Mitgliedern
Freigegebene Personenfelder	Welche Felder ChurchTools überhaupt verlassen
Erlaubte E-Mail-Domains	z. B. `etg-scheppach.de` - dann erscheint nur eine Gemeinde-Adresse (auch eine weitere, nicht die Standardadresse), private nie. Leer: Standardadresse

Die Übersicht zeigt an, ob das Token in der Umgebung gefunden wurde. Fehlt es, steht das dort - statt dass der Abgleich stillschweigend nichts tut.

Empfehlung: Freigaben als Einwilligungsgruppen zum Selbsteintragen

Freigabe- und Bildfreigabegruppe sind Einwilligungen. Am einfachsten pflegen die Personen sie selbst:

Einstellung der Gruppe	Wert
Sichtbarkeit	intern (in App und Web auffindbar)
Offen für Anmeldungen / automatisch aufnehmen	an / an - der Eintritt ist die Einwilligung
Anmelde-Überschrift	der Einwilligungstext (was, wo, freiwillig, Widerruf durch Austritt)
Rolle der Teilnehmer	ohne „Teilnehmer sehen" - niemand sieht, wer sonst eingewilligt hat

Eintrittsdatum und Protokoll belegen die Einwilligung. Alte Einwilligungsgruppen nicht löschen, sondern beenden - sonst geht das Eintrittsdatum als Nachweis verloren.

Ein selbst bearbeitbares Personenfeld ist keine Alternative, wenn die Einwilligung vor anderen verborgen sein soll: ChurchTools-Sicherheitsstufen sind eine Treppe. Was die Person selbst bearbeiten darf, liegt unterhalb dessen, was etwa Gruppenmitglieder sehen, sobald diese mehr als nur eigene Felder sehen sollen (z. B. den Geburtstag).

4. Website zuordnen

In den Seiteneinstellungen der Startseite die Verbindung auswählen. Sie gilt für alle Personen-Elemente und Insert-Tags dieser Website. Am einzelnen Element ist die Instanz bewusst nicht wählbar, damit kein Element versehentlich Personen einer fremden Gemeinde anzeigt.

5. Kalender zuordnen

Einen Contao-Kalender öffnen, Verbindung wählen, speichern, dann die gewünschten ChurchTools-Kalender ankreuzen.

Einstellung	Bedeutung
ChurchTools-Verbindung	Aus welcher Instanz die Termine kommen
ChurchTools-Kalender	Welche Kalender übernommen werden (Liste kommt aus der API)
Abgleich-Intervall	Stündlich, täglich oder nur manuell
Termin-Link statt Detailseite	Ist am Termin ein Link hinterlegt, führt der Titel direkt dorthin

Wichtig: Das Merkmal „öffentlich" am ChurchTools-Kalender taugt nicht als Filter - auch Putzpläne, Sitzungen und private Belegungen stehen dort auf öffentlich. Deshalb wird hier ausdrücklich ausgewählt.

Ein zugeordneter Kalender gehört ab dann dem Abgleich: Seine Termine sind im Backend schreibgeschützt, weil der nächste Lauf Handarbeit sonst stillschweigend überschreiben würde.

Abgleich

Läuft automatisch über Contaos Cron, je Kalender nach dessen Intervall. Zusätzlich gibt es in der Kalenderliste die Schaltfläche „Jetzt abgleichen".

Auf der Konsole:

# zeigt nur an, was geschehen würde
vendor/bin/contao-console churchtools:sync --dry-run

# führt aus
vendor/bin/contao-console churchtools:sync

# abweichender Zeitraum, etwa für die Erstbefüllung
vendor/bin/contao-console churchtools:sync --from=2025-01-01 --to=2026-12-31

Was der Abgleich tut

Übernommen wird jeder Termin, der nicht als intern markiert ist
Gelöschtes wird deaktiviert, nicht gelöscht - so leert ein API-Fehler nie den Kalender
Unveränderte Termine erzeugen keine Schreibvorgänge
Termine außerhalb des Zeitfensters bleiben unangetastet

Grenzen

Das Zeitfenster reicht standardmäßig einen Monat zurück und zwölf Monate voraus. Ältere Termine werden nicht angefasst; für eine Erstbefüllung --from/--to verwenden.
Serien werden von ChurchTools aufgelöst geliefert. Eine Instanz ist erst über Termin-ID plus Startzeitpunkt eindeutig - wird eine Serie in ChurchTools verschoben, entstehen neue Instanzen und die alten werden deaktiviert.
Ein Termin kann ein Bild tragen. Mehrere Flyer pro Termin sind nicht vorgesehen.

Personen anzeigen

Insert-Tags

{{ct_person::42}}                 Person 42, Name im Fließtext
{{ct_person::42::card}}           Person 42 als Karte
{{ct_person_group::17}}           alle freigegebenen Mitglieder der Gruppe 17
{{ct_person_group::17::3}}        nur Rolle 3, z. B. die Leitung
{{ct_person_group::17::3::card}}  dieselbe Auswahl als Karte

Inhaltselement „Person"

Eine Rolle in einer Gruppe und/oder eine feste Person, beides kombinierbar:

Gruppe und Rolle: z. B. „Leitung der Spürnasen". Wechselt die Zuständigkeit in ChurchTools, wechselt die Anzeige automatisch mit. Die Rollenliste zeigt nur Rollen des Gruppentyps der gewählten Gruppe.
Anzahl: alle Personen dieser Rolle oder nur eine (die erste in der Reihenfolge von ChurchTools).
Zusätzliche Person: im Backend über ein Suchfeld nach Namen gewählt. Sie erscheint nach den Personen aus der Gruppe; steht sie dort schon, wird sie nicht doppelt gezeigt. Ohne Gruppe ist sie die einzige Person.

Berücksichtigt werden nur aktive Mitgliedschaften - Wartende, Angefragte und Ausgeschiedene erscheinen weder über die Rolle noch in der Freigabegruppe.

Darstellungen: card, inline, contact, list. Die Templates liegen unter @Contao/churchtools/person_*.html.twig und lassen sich im Projekt überschreiben.

Datenschutz

Das Bundle ist hier absichtlich streng:

Personendaten werden nicht in die Contao-Datenbank gespiegelt, sondern bei Bedarf geholt und kurz zwischengespeichert
Ausgeliefert wird nur, wer in der Freigabegruppe steht. Ohne konfigurierte Gruppe erscheint niemand - eine fehlende Einstellung gilt nicht als Vollfreigabe. Das greift auch, wenn eine Personen-ID direkt in einem Insert-Tag steht
Nur ausgewählte Felder verlassen ChurchTools; E-Mail und Telefon sind voreingestellt aus. Mit „Erlaubte E-Mail-Domains" lässt sich die E-Mail zusätzlich auf Gemeinde-Adressen begrenzen
Bilder - gezeigt wird ausschließlich das Profilfoto, das die Person selbst in ChurchTools hinterlegt hat, und nur bei freigegebenen Personen. Wer es hochlädt und in die Veröffentlichung einwilligt, zeigt es bewusst. Optional lässt sich das Foto zusätzlich an eine Bildfreigabegruppe binden
Personenbilder laufen über eine eigene Route und werden nie im Web-Verzeichnis abgelegt. Fehlt die Freigabe, antwortet sie mit 404 statt mit einem Platzhalter, der die Existenz der Person bestätigen würde
Caches sind pro Verbindung getrennt - Mandanten können sich nicht gegenseitig sehen

Ausfallverhalten

Ist ChurchTools nicht erreichbar, bleibt die Website vollständig: Termine liegen ohnehin in der Contao-Datenbank, Personen kommen aus einem unbefristet abgelegten letzten guten Stand. Im Frontend erscheint keine Fehlermeldung.

Fehlersuche

Symptom	Ursache und Lösung
Übersicht meldet „Umgebungsvariable fehlt"	Die in der Verbindung genannte Variable ist nicht gesetzt. Nach dem Eintragen in `.env.local` den Cache leeren.
Abgleich meldet „ChurchTools ist nicht erreichbar"	Basis-URL prüfen (ohne abschließenden Schrägstrich) und ob das Token noch gültig ist. `churchtools:person` zeigt beides an.
Kalenderliste im Backend bleibt leer	Verbindung wählen und speichern - die Liste wird erst danach von der API geholt.
Termine kommen, aber ohne Flyer	Hat der Termin in ChurchTools ein Bild? Der Bericht des Abgleichs nennt die Ursache je Termin.
Person erscheint nicht auf der Website	`vendor/bin/contao-console churchtools:person <ID>` - meist fehlt der Eintrag in der Freigabegruppe.
Person erscheint, aber ohne Bild	In ChurchTools ist kein Profilfoto hinterlegt, oder - falls konfiguriert - die Person steht nicht in der Bildfreigabegruppe. `churchtools:person <ID>` nennt den Grund.
Änderungen am Termin verschwinden wieder	Der Kalender ist einer Verbindung zugeordnet und gehört dem Abgleich. Termine in ChurchTools bearbeiten.
Eigenes Template greift nicht	Nach dem Anlegen `cache:clear` und `cache:warmup` - die Twig-Hierarchie wird nur beim Warmup neu gebaut.

Befehle

Befehl	Zweck
`churchtools:sync`	Termine abgleichen, mit `--dry-run`, `--from`, `--to`
`churchtools:person <ID>`	Prüft Freigabe und zeigt, welche Felder ausgeliefert würden
`churchtools:person --search=<Name>`	Personensuche wie im Backend-Auswahlfeld
`churchtools:person --group=<ID> [--role=<ID>]`	Löst eine Gruppe bzw. Rolle auf

Weiterentwicklung

Designentscheidungen, Architektur und die Fallstricke aus dem Bau stehen in docs/entwicklung.md - lesenswert, bevor man etwas ändert.

Lizenz

LGPL-3.0-or-later

samuelheer / contao-churchtools-bundle

Package info

Security

Statistics