Modul: Dokumenten-Generator¶

Zweck des Moduls¶

Der Dokumenten-Generator ermöglicht die Erstellung und Verwaltung von professionellen PDF-Dokumenten mit automatischer Versionierung. Das Modul unterstützt Dokumentvorlagen mit Logo, Markdown-basierte Inhalte mit Variablen-Unterstützung und bietet stabile öffentliche URLs für externe Verlinkungen (z.B. auf der Vereinswebseite).

Navigation im Admin-Bereich¶

Das Dokumenten-Generator-Modul finden Sie im Admin-Menü unter "DOCUMENT_GENERATOR" mit drei Hauptbereichen:

• Dokumentvorlagen - Template-Verwaltung mit Logo-Upload
• Dokumentinhalte - Content-Verwaltung mit Versionierung
• Generierte Dokumente - Fertige PDF-Dokumente mit Download-Links

Bereiche im Detail¶

Dokumentvorlagen (Admin > Document_Generator > Dokumentvorlagen)¶

Zweck: Verwaltung wiederverwendbarer Dokumentvorlagen für professionelle PDF-Dokumente

Hauptfelder: - Name: Template-Bezeichnung (z.B. "Vereinsbrief", "Satzung", "Protokoll") - Generierungsmodus: LaTeX (professionell) oder HTML (einfach) - Logo: Vereinslogo hochladen (PNG/JPG empfohlen) - LaTeX-Hauptdatei: Vollständiges Template mit Platzhaltern - LaTeX LCO-Datei: Briefkonfiguration für Kopf-/Fußzeilen

Verfügbare Platzhalter (automatisch aus Vereinsdaten):

{{fromname}}      = Vereinsname
{{fromaddress}}   = Vereinsadresse
{{fromphone}}     = Telefonnummer
{{fromemail}}     = E-Mail-Adresse
{{fromurl}}       = Homepage-URL
{{place}}         = Ort
{{frombank}}      = Bankverbindung
{{logo_filename}} = Logo-Dateiname
{{date}}          = Aktuelles Datum

Zusätzliche Platzhalter aus dem Dokumentinhalt: - {{content}} = Der Markdown-Inhalt wird hier eingefügt - Alle eigenen Variablen (z.B. {{title}}, {{author}}, {{version}})

Logo in der Listenansicht: Das hochgeladene Logo wird automatisch auf max. 100px Höhe skaliert angezeigt.

Dokumentinhalte (Admin > Document_Generator > Dokumentinhalte)¶

Zweck: Verwaltung des eigentlichen Dokumentinhalts mit Markdown und eigenen Variablen

Automatische Funktionen: - Token-Generierung: 16-stelliger sicherer Code für stabile URLs (z.B. aB3cD9eF2gH4iJ5k) - Slug-Generierung: Menschenlesbarer Kurzname aus Titel (nur zur Übersicht) - Versionsverwaltung: Automatisches Tracking aller PDF-Generierungen

Wichtige Felder: - Titel: Dokumenttitel (z.B. "Vereinssatzung FVW 2025") - Slug: Wird automatisch erstellt, nur für Admin-Übersicht - Standard-Template: Welche Vorlage soll verwendet werden? - Markdown-Inhalt: Der eigentliche Inhalt mit Formatierung - Variablen: Zusätzliche Platzhalter als JSON (siehe unten) - Aktiv: Ist dieses Dokument verfügbar?

Tab: URLs & Versionen

Hier sehen Sie den öffentlichen Token und alle verfügbaren URLs:

Token: aB3cD9eF2gH4iJ5k (16 Zeichen, sicher, nicht erratbar)

Stabile URLs (empfohlen für externe Links): - https://ihre-domain.de/documents/aB3cD9eF2gH4iJ5k/latest/ (HTML-Ansicht) - https://ihre-domain.de/documents/aB3cD9eF2gH4iJ5k/latest/pdf/ (PDF-Download)

Versionsübersicht-Tabelle: Zeigt alle bereits generierten Versionen mit: - Version-Nummer (v1, v2, v3...) - Generierungsdatum - Status (🟢 LATEST = aktuellste Version) - Links zu HTML und PDF für jede Version

Tab: Content

Hier geben Sie den eigentlichen Inhalt ein:

Markdown-Editor mit Syntax-Highlighting:

# Überschrift 1
## Überschrift 2

Dies ist normaler Text mit **Fettdruck** und *Kursiv*.

- Aufzählung Punkt 1
- Aufzählung Punkt 2

1. Nummerierte Liste
2. Punkt zwei

Sie können auch Platzhalter verwenden: {{title}}, {{author}}

Tab: Variablen

Hier definieren Sie eigene Platzhalter im JSON-Format:

Beispiel:

{
  "author": "Max Mustermann",
  "version": "1.0",
  "approved_date": "01.01.2025",
  "title": "Vereinssatzung"
}

Diese Variablen können dann im Markdown-Inhalt verwendet werden:

Verfasser: {{author}}
Version: {{version}}
Genehmigt am: {{approved_date}}

Zeilen-Aktionen (Buttons in der Liste): - 📄 PDF generieren (asynchron): Startet PDF-Generierung im Hintergrund

Generierte Dokumente (Admin > Document_Generator > Generierte Dokumente)¶

Zweck: Verwaltung und Zugriff auf fertig generierte PDF-Dokumente

So funktioniert die Versionierung:

Jedes Mal, wenn Sie ein Dokument neu generieren: - Neue Version wird erstellt (v1 → v2 → v3...) - Neue Version wird als "LATEST" markiert (grüner Badge) - Alte Versionen bleiben erhalten, verlieren aber den LATEST-Status - Die /latest/-URL zeigt automatisch die neueste Version

Beispiel:

1. Erste Generierung → v1 🟢 LATEST
   /documents/abc123/latest/ zeigt v1

2. Dokument bearbeiten + neu generieren → v2 🟢 LATEST
   v1 verliert LATEST-Status
   /documents/abc123/latest/ zeigt jetzt v2
   /documents/abc123/v1/ zeigt weiterhin die alte Version v1

3. Erneute Änderung + neu generieren → v3 🟢 LATEST
   v2 verliert LATEST-Status
   /documents/abc123/latest/ zeigt jetzt v3

Spalten in der Listenansicht: - Titel: Dokumenttitel - Version: Versionsnummer mit Badge (🟢 LATEST = aktuell) - Template: Verwendete Vorlage - Inhalt: Verknüpfter DocumentContent - Generiert am: Erstellungsdatum - Download-Anzahl: Wie oft wurde es heruntergeladen? - Öffentlich zugänglich: Download ohne Login möglich? - Links: Schnellzugriff auf alle URLs

Filter (rechte Seitenleiste): - Nach Öffentlich zugänglich filtern - Nach Neueste Version filtern (nur LATEST anzeigen) - Nach Generierungsdatum filtern - Nach Template filtern

Tab: Dokument: - Titel: Dokumenttitel - Template: Verwendetes Template - Inhalt: Verknüpfter DocumentContent - Öffentlich zugänglich: Erlaubt Download ohne Login

Tab: Version: - Version: Versionsnummer (automatisch vergeben) - Neueste Version: Ist dies die aktuellste? (automatisch gesetzt)

Tab: Output: - PDF-Datei: Download des generierten PDFs - Gerendertes HTML: Vollständiges HTML für Vorschau

Tab: Zugriff:

Links-Bereich zeigt alle verfügbaren URLs:

1. Version vX: URLs für diese spezifische Version
2. 🔗 HTML: /documents/<token>/v1/

3. 📄 PDF: /documents/<token>/v1/pdf/

4. 🟢 Stabile Latest-URL (nur bei aktueller Version):

5. 🔗 HTML: /documents/<token>/latest/
6. 📄 PDF: /documents/<token>/latest/pdf/

7. Grüner Hintergrund = Diese URLs aktualisieren sich automatisch!

8. Legacy (Token): Alte URLs für Rückwärtskompatibilität

9. 🔗 HTML: /view/<langer-token>/
10. 📄 PDF: /pdf/<langer-token>/

Download-Tracking: - Download-Anzahl: Zählt alle Zugriffe auf dieses Dokument - Letzter Zugriff: Wann wurde es zuletzt abgerufen?

Was passiert beim PDF-Generieren?¶

Schritt-für-Schritt Ablauf¶

Wenn Sie auf "📄 PDF generieren (asynchron)" klicken:

1. Erfolgsmeldung erscheint: 🚀 PDF-Generierung gestartet für 1 Dokument(e). Die Generierung läuft im Hintergrund. Task ID: abc123-def456...

2. Hintergrund-Verarbeitung läuft (Sie können weiterarbeiten):

3. Template wird geladen
4. Platzhalter werden mit Ihren Werten ersetzt
5. Markdown wird in formatiertes PDF umgewandelt
6. Logo wird eingefügt

7. PDF wird erstellt und gespeichert

8. Automatische Versionierung:

9. System prüft: Gibt es schon Versionen? → Nächste Nummer nehmen
10. Neue Version erhält automatisch "LATEST"-Status

11. Alte Versionen verlieren "LATEST"-Status (bleiben aber erhalten)

12. Dokument ist fertig:

13. Erscheint in "Generierte Dokumente"
14. Kann heruntergeladen werden
15. URLs sind sofort verfügbar

Dauer: Je nach Dokumentgröße 5-30 Sekunden. Die Generierung läuft im Hintergrund, Sie müssen nicht warten.

Stabile URLs für externe Verlinkungen¶

Warum sind die URLs "stabil"?¶

Problem ohne stabile URLs:

Alte Lösung: /view/abc123def456...xyz/
↓
Dokument wird neu generiert
↓
Neue URL: /view/xyz789ghi012...uvw/
↓
Alle externen Links sind kaputt! ❌

Lösung mit stabilen URLs:

Stabile URL: /documents/aB3cD9eF2gH4iJ5k/latest/
↓
Dokument wird neu generiert (v1 → v2)
↓
Gleiche URL: /documents/aB3cD9eF2gH4iJ5k/latest/
↓
URL zeigt automatisch neue Version! ✅

Verwendung auf der Webseite¶

Empfohlen (stabile Latest-URL):

<a href="/documents/aB3cD9eF2gH4iJ5k/latest/">
  Vereinssatzung (aktuelle Fassung)
</a>

👉 Vorteil: Link muss nie geändert werden, zeigt immer die neueste Version!

Spezifische Version (wenn alte Version verlinkt bleiben soll):

<a href="/documents/aB3cD9eF2gH4iJ5k/v1/">
  Vereinssatzung v1.0 (historisch)
</a>

👉 Vorteil: Link zeigt immer die gleiche Version, egal wie oft neu generiert wird.

Sicherheit der URLs¶

Warum keine einfachen Namen wie /vereinssatzung/?

❌ Einfache Namen wären erratbar: - /vereinssatzung/ → Jeder könnte das erraten - /protokoll/ → Einfach zu finden - /mitgliederliste/ → Unsicher!

✅ 16-Zeichen Token ist sicher: - aB3cD9eF2gH4iJ5k → 4.700.000.000.000.000.000.000.000.000.000 Möglichkeiten - Praktisch unmöglich zu erraten - Nur wer den Link kennt, kann darauf zugreifen

Typische Anwendungsfälle¶

Anwendungsfall 1: Vereinssatzung mit Updates¶

Situation: Die Vereinssatzung muss alle 2 Jahre aktualisiert werden.

Setup (einmalig): 1. Dokumentvorlage "Satzung Standard" mit Logo und Kopfzeile erstellen 2. Dokumentinhalt "Vereinssatzung FVW" anlegen: - Markdown-Inhalt der Satzung eingeben - Variablen: {"version": "1.0", "approved_date": "01.01.2025"} 3. Erste PDF-Generierung → v1 wird erstellt 4. Token notieren: aB3cD9eF2gH4iJ5k

Webseite verlinken:

<a href="/documents/aB3cD9eF2gH4iJ5k/latest/">
  Vereinssatzung (aktuelle Fassung)
</a>

Nach 2 Jahren - Satzung wird geändert: 1. Dokumentinhalt bearbeiten: - Markdown-Text anpassen - Variablen updaten: {"version": "2.0", "approved_date": "01.01.2027"} 2. Erneut "📄 PDF generieren" klicken 3. v2 wird erstellt (v1 bleibt als historische Version erhalten) 4. Webseiten-Link funktioniert weiter ohne Änderung! ✅

Ergebnis: - /documents/aB3cD9eF2gH4iJ5k/latest/ → zeigt automatisch v2 - /documents/aB3cD9eF2gH4iJ5k/v1/ → alte Version bleibt abrufbar - Webmaster muss nichts ändern!

Anwendungsfall 2: Monatliches Protokoll¶

Situation: Jeden Monat wird ein neues Vorstandsprotokoll erstellt.

Setup: 1. Dokumentvorlage "Protokoll Standard" mit Vereinslogo 2. Für jeden Monat neuen Dokumentinhalt anlegen: - "Vorstandsprotokoll Januar 2025" - "Vorstandsprotokoll Februar 2025" - etc. 3. Jedes Protokoll bekommt eigenen Token 4. PDF generieren für jedes Protokoll

Webseite:

<ul>
  <li><a href="/documents/abc123/latest/">Protokoll Januar 2025</a></li>
  <li><a href="/documents/def456/latest/">Protokoll Februar 2025</a></li>
  <li><a href="/documents/ghi789/latest/">Protokoll März 2025</a></li>
</ul>

Wenn Protokoll korrigiert werden muss: 1. Dokumentinhalt bearbeiten 2. Neu generieren → v2 wird erstellt 3. Link funktioniert weiter (zeigt korrigierte Version)

Anwendungsfall 3: Historische Versionen anbieten¶

Situation: Alte Satzungsversionen sollen zur Nachvollziehbarkeit verfügbar bleiben.

Webseite:

<h2>Vereinssatzung</h2>
<p>
  <a href="/documents/aB3cD9eF2gH4iJ5k/latest/">
    📄 Aktuelle Fassung (v3.0)
  </a>
</p>

<h3>Historische Versionen</h3>
<ul>
  <li><a href="/documents/aB3cD9eF2gH4iJ5k/v2/">v2.0 (2023)</a></li>
  <li><a href="/documents/aB3cD9eF2gH4iJ5k/v1/">v1.0 (2020)</a></li>
</ul>

Vorteil: Alle Versionen bleiben dauerhaft abrufbar, auch nach weiteren Updates.

Admin-Checkliste¶

Neue Dokumentvorlage anlegen¶

• [ ] Name: Aussagekräftiger Name gewählt?
• [ ] Generierungsmodus: LaTeX (professionell) oder HTML (einfach)?
• [ ] Logo: Vereinslogo hochgeladen (PNG empfohlen)?
• [ ] Template: Alle Platzhalter korrekt verwendet?

Dokumentinhalt erstellen¶

• [ ] Titel: Klar und eindeutig?
• [ ] Template: Richtige Vorlage ausgewählt?
• [ ] Markdown: Formatierung korrekt?
• [ ] Variablen: JSON-Format gültig? Alle {{platzhalter}} definiert?
• [ ] Aktiv: Status auf "Aktiv" gesetzt?

Vor PDF-Generierung prüfen¶

• [ ] Platzhalter: Alle im Template verwendeten Variablen auch definiert?
• [ ] Markdown: Keine Tippfehler oder Syntax-Fehler?
• [ ] Logo: Im Template hochgeladen und sichtbar?

Nach PDF-Generierung prüfen¶

• [ ] PDF-Vorschau: Sieht alles korrekt aus?
• [ ] Version: Richtige Versionsnummer angezeigt?
• [ ] URLs: Latest-URL funktioniert?
• [ ] Download: PDF lässt sich herunterladen?

Externe Verlinkung einrichten¶

• [ ] Token: Aus "URLs & Versionen" Tab kopiert?
• [ ] Latest-URL: /documents/<token>/latest/ verwendet (nicht v1, v2...)?
• [ ] Test: Link funktioniert im Inkognito-Modus (ohne Login)?
• [ ] Webmaster: URL für Webseiten-Einbindung weitergegeben?

Problembehandlung¶

PDF-Generierung funktioniert nicht¶

Symptom: Nach Klick auf "PDF generieren" erscheint keine Erfolgsmeldung oder Fehler.

Mögliche Ursachen: 1. Template-Fehler: Platzhalter im Template nicht richtig geschrieben? - Prüfen: Sind alle {{variablen}} mit doppelten geschweiften Klammern? 2. Fehlende Variablen: Wird im Template ein Platzhalter verwendet, der nicht definiert ist? - Prüfen: Alle {{variablen}} im Template auch im JSON definiert? 3. JSON-Syntax-Fehler: Variablen nicht korrekt formatiert? - Prüfen: Doppelte Anführungszeichen? Kommas? Geschweifte Klammern?

Tipp: Kontaktieren Sie den IT-Support, wenn die Generierung länger als 5 Minuten nicht abgeschlossen ist.

Stabile URL führt zu Fehler (404)¶

Symptom: Beim Klick auf /documents/<token>/latest/ erscheint "Seite nicht gefunden".

Mögliche Ursachen: 1. Kein PDF generiert: Wurde überhaupt ein PDF erstellt? - Prüfen: Gibt es Einträge unter "Generierte Dokumente"? 2. Nicht öffentlich: Ist das Dokument als "Öffentlich zugänglich" markiert? - Prüfen: Bei "Generierte Dokumente" → Status prüfen 3. Falscher Token: Token aus der URL korrekt kopiert? - Prüfen: 16 Zeichen? Keine Leerzeichen am Anfang/Ende?

Alte Version wird angezeigt¶

Symptom: Die /latest/ URL zeigt eine alte Version, obwohl neu generiert wurde.

Ursache: Neue Version hat nicht "LATEST"-Status erhalten.

Lösung: 1. Gehen Sie zu "Generierte Dokumente" 2. Finden Sie die neueste Version (höchste Versionsnummer) 3. Überprüfen Sie, ob der grüne "🟢 LATEST"-Badge sichtbar ist 4. Falls nicht: Kontaktieren Sie den IT-Support

Variablen werden nicht ersetzt¶

Symptom: Im PDF steht wörtlich {{author}} statt "Max Mustermann".

Ursache: Variable nicht im JSON definiert.

Lösung: 1. Gehen Sie zum Dokumentinhalt 2. Tab "Variablen" öffnen 3. Variable hinzufügen: json { "author": "Max Mustermann" } 4. Erneut PDF generieren

Logo wird nicht angezeigt¶

Symptom: Im PDF fehlt das Vereinslogo.

Mögliche Ursachen: 1. Logo nicht hochgeladen: Wurde das Logo im Template hochgeladen? - Prüfen: "Dokumentvorlagen" → Template öffnen → Logo-Feld 2. Logo-Platzhalter fehlt: Wird {{logo_filename}} im Template verwendet? - IT-Support kontaktieren für Template-Anpassung

Tipps & Best Practices¶

Markdown-Formatierung¶

Überschriften:

# Große Überschrift (Ebene 1)
## Mittlere Überschrift (Ebene 2)
### Kleine Überschrift (Ebene 3)

Textformatierung:

**fetter Text**
*kursiver Text*
***fett und kursiv***

Listen:

- Aufzählungspunkt 1
- Aufzählungspunkt 2
  - Unterpunkt 2.1
  - Unterpunkt 2.2

1. Nummerierter Punkt 1
2. Nummerierter Punkt 2
3. Nummerierter Punkt 3

Absätze:

Erster Absatz mit Text.

Zweiter Absatz mit Text.
(Leerzeile dazwischen!)

Variablen sinnvoll nutzen¶

Wiederverwendbare Werte:

{
  "year": "2025",
  "president": "Dr. Max Mustermann",
  "club_name": "Fischereiverein Wangen e.V."
}

Im Markdown dann:

# Protokoll der Mitgliederversammlung {{year}}

Der Vorsitzende {{president}} eröffnet die Sitzung des {{club_name}}.

Vorteil: Werte müssen nur einmal geändert werden, nicht an jeder Stelle im Text!

Token-Verwaltung¶

Token dokumentieren: Notieren Sie wichtige Tokens für die Webseite:

Vereinssatzung: aB3cD9eF2gH4iJ5k
Beitragsordnung: xY9zW8vU7tS6rQ5p
Geschäftsordnung: mN4oP3qR2sT1uV0w

URL-Format merken: /documents/<token>/latest/ oder /latest/pdf/

Versionierung nutzen¶

Versionsnummern in Variablen:

{
  "version": "2.1",
  "approved_date": "15.03.2025",
  "changes": "Anpassung §3 Abs. 2"
}

Im Markdown:

Version {{version}} | Genehmigt am: {{approved_date}}

Änderungen: {{changes}}

Historische Versionen behalten: Alte Versionen werden automatisch archiviert - löschen Sie sie nicht!

Änderungsverlauf¶