Zum Hauptinhalt springen

Vorlagen anpassen

Die Template IDE ist die Bearbeitungsumgebung zum Gestalten von Rechnungs- und Kontoauszugsvorlagen. Dieser Leitfaden behandelt die dreispaltige Oberfläche, die Arbeit mit Variablen, das Schreiben von Jinja2-Vorlagencode, die CSS-Gestaltung und das Testen Ihrer Änderungen mit der Live-Vorschau.

Übersicht: Die dreispaltige Oberfläche​

Die Template IDE ist in drei Bereiche unterteilt:

  • Variablenseitenleiste (links): Verfügbare Datenfelder nach Kategorie durchsuchen. Klicken Sie auf eine Variable, um sie an der Cursorposition im Code-Editor einzufügen.
  • Code-Editor (Mitte): HTML und CSS mit CodeMirror-Syntaxhervorhebung schreiben und bearbeiten. Der Inhalt ist in Registerkarten organisiert: Kopfzeile, Rechnungsinhalt, Fußzeile, Kontoauszugsinhalt, CSS und Übersetzungen.
  • Live-PDF-Vorschau (rechts): Eine gerenderte PDF-Vorschau. Die Vorschau verwendet Beispieldaten aus den Variablendefinitionen.

Öffnen Sie eine beliebige Vorlage und klicken Sie auf Bearbeiten, um die IDE zu starten. Die Seitenleiste kann eingeklappt werden, um mehr Platz für den Editor zu schaffen, und die Trennlinie zwischen Editor und Vorschau kann gezogen werden, um die Panels zu vergrößern oder zu verkleinern.

Die Variablenseitenleiste​

Das linke Panel zeigt alle Datenfelder, die Ihrer Vorlage zur Verfügung stehen. Variablen sind in den JSON-Metadaten der Vorlage definiert und nach Präfix organisiert.

Variablenkategorien​

Häufige Variablenpräfixe sind:

  • invoice: invoice.invoice_number, invoice.invoice_date, invoice.benefit_period_start usw.
  • customer: customer.name, customer.customer_number, customer.vat_id, customer.address.* (mit Unterfeldern wie street, city, zip_code, country)
  • company: company.name, company.address, company.tax_id, company.vat_id usw.
  • bank_account: bank_account.bank_name, bank_account.iban, bank_account.bic
  • payment_terms: payment_terms.name, payment_terms.days, payment_terms.date, payment_terms.text
  • positions[]: positions[].title, positions[].quantity, positions[].unit_price, positions[].total, positions[].unit usw.
  • statement: statement.start_date, statement.end_date, statement.start_balance, statement.end_balance, statement.transactions

Variablen einfügen​

So fügen Sie eine Variable in Ihre Vorlage ein:

  1. Platzieren Sie den Cursor im Code-Editor an der gewünschten Stelle
  2. Klicken Sie auf einen Variablennamen in der Seitenleiste
  3. Die Variable wird an der Cursorposition in Jinja2-Syntax eingefügt

Zum Beispiel fügt ein Klick auf company.name den Code {{ company.name }} ein.

Variablen suchen​

Verwenden Sie das Suchfeld oben in der Seitenleiste, um Variablen zu filtern. Geben Sie "date" ein, um alle datumsbezogenen Felder zu finden, oder "total" für Felder im Zusammenhang mit Summen.

Der Code-Editor​

Das mittlere Panel ist ein CodeMirror-basierter Editor mit Syntaxhervorhebung für HTML und CSS.

Vorlagenabschnitte (Registerkarten)​

Ihr Vorlagencode ist in Registerkarten organisiert:

  • Kopfzeile: Inhalt, der oben auf jeder Seite gerendert wird (Logo, Firmenname, Rechnungstitel)
  • Rechnungsinhalt: Der Hauptteil einer Rechnung (Positionstabelle, Summen, Kundendetails)
  • Fußzeile: Inhalt, der unten auf jeder Seite gerendert wird (Bankdaten, Zahlungsbedingungen, rechtliche Hinweise)
  • Kontoauszugsinhalt: Alternativer Hauptinhalt für die Erstellung von Kontoauszügen anstelle von Rechnungen
  • CSS: Alle Gestaltung, die für die gesamte Vorlage gilt
  • Übersetzungen: JSON-basierte Übersetzungsschlüssel für mehrsprachigen Text (siehe Vorlagenübersetzungen)
Wie Abschnitte zusammengesetzt werden

Bei der PDF-Erstellung assembliert docs101 ein vollständiges HTML-Dokument aus CSS (in einem <style>-Tag), Kopfzeile (in einem .header-Div), Fußzeile (in einem .footer-Div) und entweder Rechnungsinhalt oder Kontoauszugsinhalt (in einem .content-Div). Dieses zusammengesetzte HTML wird zusammen mit dem Datenmodell an den Rendering-Service gesendet.

Grundlegende HTML-Struktur​

Ein typischer Rechnungsinhalt-Abschnitt:

<div class="invoice-header">
  <h1>{{ company.name }}</h1>
  <p>{{ company.address }}</p>
</div>

<table class="invoice-items">
  <thead>
    <tr>
      <th>{{ t('col_description') }}</th>
      <th>{{ t('col_quantity') }}</th>
      <th>{{ t('col_unit_price') }}</th>
      <th>{{ t('col_total') }}</th>
    </tr>
  </thead>
  <tbody>
    {% for position in positions %}
    <tr>
      <td>{{ position.title }}</td>
      <td>{{ position.quantity }}</td>
      <td>{{ position.unit_price }}</td>
      <td>{{ position.total }}</td>
    </tr>
    {% endfor %}
  </tbody>
</table>

Jinja2-Syntax​

Vorlagen verwenden Jinja2 für alle dynamischen Inhalte. Der Rendering-Service (DocsRabbit) verarbeitet die Jinja2-Syntax und ersetzt sie durch die tatsächlichen Daten.

Variablen​

Datenwerte mit doppelten geschweiften Klammern anzeigen:

{{ company.name }}
{{ invoice.invoice_number }}
{{ customer.name }}
{{ invoice.invoice_date }}

Filter​

Variablen mit Jinja2-Filtern über den Pipe-Operator (|) formatieren:

{{ customer.name|upper }}
{{ invoice.invoice_date }}
Datumsformatierung

Datumswerte in docs101-Vorlagen werden vom Backend gemäß der Datumsformat-Einstellung des Unternehmens vorformatiert, bevor sie an die Vorlage übergeben werden. Sie müssen in Ihrem Vorlagencode keine Datumsfilter anwenden — geben Sie die Variable einfach direkt aus.

Bedingungen​

Abschnitte basierend auf Datenwerten ein- oder ausblenden:

{% if customer.vat_id %}
  <p>USt-IdNr.: {{ customer.vat_id }}</p>
{% endif %}

{% if IS_REVERSE_CHARGE %}
  <p class="notice">{{ t('reverse_charge_notice') }}</p>
{% endif %}

{% if IS_INVOICE_DOCUMENT %}
  <!-- Rechnungsspezifischer Inhalt -->
{% endif %}

{% if IS_ACCOUNT_STATEMENT_DOCUMENT %}
  <!-- Kontoauszugsspezifischer Inhalt -->
{% endif %}

Schleifen​

Über Listen von Elementen iterieren — am häufigsten Rechnungspositionen:

{% for position in positions %}
<tr>
  <td>{{ position.title }}</td>
  <td>{{ position.quantity }}</td>
  <td>{{ position.unit }}</td>
  <td>{{ position.unit_price }}</td>
  <td>{{ position.total }}</td>
</tr>
{% endfor %}

Auf Schleifen-Metadaten für spezielle Gestaltung zugreifen:

{% for position in positions %}
<tr class="{% if loop.first %}first-row{% endif %} {% if loop.last %}last-row{% endif %}">
  <td>#{{ loop.index }}</td>
  <td>{{ position.title }}</td>
</tr>
{% endfor %}

Die Übersetzungsfunktion​

Verwenden Sie {{ t('schlüssel_name') }}, um übersetzten Text auszugeben. Die korrekte Sprache wird automatisch basierend auf der Spracheinstellung des Kunden ausgewählt:

<h1>{{ t('invoice_title') }}</h1>
<th>{{ t('col_description') }}</th>

Siehe Vorlagenübersetzungen für alle Details.

CSS-Gestaltung​

Wechseln Sie zur Registerkarte CSS, um alle visuellen Aspekte der Vorlage zu steuern.

Häufige CSS-Aufgaben​

Grundschriftart festlegen​

body {
  font-family: Arial, sans-serif;
  font-size: 11pt;
  line-height: 1.5;
  color: #333;
}

Kopfzeile gestalten​

.invoice-header {
  background-color: #003366;
  color: white;
  padding: 20px;
  border-radius: 4px;
}

.invoice-header h1 {
  margin: 0;
  font-size: 24pt;
}

Positionstabelle gestalten​

.invoice-items {
  width: 100%;
  border-collapse: collapse;
  margin-top: 20px;
}

.invoice-items th {
  background-color: #f0f0f0;
  padding: 10px;
  text-align: left;
  font-weight: bold;
  border-bottom: 2px solid #333;
}

.invoice-items td {
  padding: 8px 10px;
  border-bottom: 1px solid #ddd;
}

.invoice-items tr:nth-child(even) {
  background-color: #f9f9f9;
}

Firmenlogo positionieren​

.company-logo {
  max-width: 150px;
  margin-bottom: 20px;
}
<img src="{{ company.logo_url }}" class="company-logo" alt="Firmenlogo">

CSS Best Practices​

  • Verwenden Sie relative Einheiten (%, em) für Breiten, wenn möglich, für besseres PDF-Rendering
  • Definieren Sie eine konsistente Farbpalette am Anfang Ihres CSS mit Kommentaren
  • Verwenden Sie CSS-Klassen statt Inline-Stile für bessere Wartbarkeit
  • Testen Sie in mehreren PDF-Readern — einige unterstützen möglicherweise keine fortgeschrittenen CSS-Funktionen
  • Organisieren Sie CSS nach Abschnitt (Kopfzeile, Tabelle, Summen, Fußzeile)

Live-Vorschau​

Das rechte Panel rendert eine PDF-Vorschau mit demselben Rendering-Service, der auch Ihre endgültigen Rechnungen erstellt.

Verwendung der Vorschau​

  1. Bearbeiten Sie Ihren Vorlagencode im mittleren Panel
  2. Speichern Sie Ihre Änderungen, um eine Vorschau-Aktualisierung auszulösen
  3. Das Vorschau-Panel zeigt das gerenderte PDF
  4. Verwenden Sie die Zoom-Steuerung, um die Vorschaugröße anzupassen
  5. Scrollen Sie, um alle Seiten zu sehen, wenn die Vorlage mehrseitige Ausgaben erzeugt
Vorschaudaten

Die Vorschau verwendet die Beispielwerte, die in den Variablen-Metadaten der Vorlage definiert sind. Der Rendering-Service generiert Beispielpositionen, um mehrseitige Layouts zu testen.

Häufige Vorschauprobleme​

Wenn die Vorschau nicht korrekt aussieht:

  • Variable wird nicht angezeigt: Prüfen Sie, ob der Variablenname mit den Variablen-Metadaten übereinstimmt (z.B. company.name nicht company.fullname)
  • Tabelle nicht ausgerichtet: Überprüfen Sie, ob die CSS-Klassennamen zwischen HTML und CSS übereinstimmen
  • Schrift zu klein oder groß: Passen Sie font-size in der CSS-Registerkarte an
  • Farben werden nicht angewendet: Suchen Sie nach widersprüchlichen oder überschreibenden CSS-Regeln

Speichern und Versionierung​

Änderungen speichern​

Klicken Sie auf Speichern, um Ihre Änderungen zu speichern. Jedes Speichern erhöht automatisch die Versionsnummer der Vorlage und aktualisiert den last_updated-Zeitstempel.

Folgende Felder werden gespeichert: Name, Inhalt (Rechnungskörper), Kontoauszugsinhalt, Kopfzeile, Fußzeile, CSS und Übersetzungen.

Versionsverfolgung

Die Versionsnummer wird bei jedem Speichern erhöht, sodass Sie nachvollziehen können, wie viele Überarbeitungen vorgenommen wurden. Sie können sicher experimentieren, da Ihre Änderungen erfasst werden.

Vorlagenoptionen​

Vorlagen unterstützen boolesche Optionen, die das bedingte Verhalten in der gerenderten Ausgabe steuern. Diese werden in den Optionen-Metadaten der Vorlage konfiguriert und automatisch in das Vorlagenmodell eingefügt.

Zum Beispiel kann eine Vorlage eine Option wie SHOW_BANK_DETAILS definieren, die steuert, ob der Bankdaten-Abschnitt angezeigt wird:

{% if SHOW_BANK_DETAILS %}
<div class="bank-details">
  <p>{{ bank_account.bank_name }}</p>
  <p>IBAN: {{ bank_account.iban }}</p>
</div>
{% endif %}

Zusätzlich werden einige Optionen automatisch erkannt:

  • IS_REVERSE_CHARGE: Automatisch true, wenn eine Position den USt.-Kategoriecode "AE" hat
  • IS_SMALL_BUSINESS_EXEMPT: Automatisch true, wenn eine Position den USt.-Kategoriecode "O" hat
  • IS_INVOICE_DOCUMENT / IS_ACCOUNT_STATEMENT_DOCUMENT: Wird basierend auf dem generierten Dokumenttyp gesetzt

Häufige Anpassungen​

Beispiel: Bedingtes Zahlungsstatus-Abzeichen​

{% if invoice.is_paid %}
  <span class="status-badge paid">BEZAHLT</span>
{% elif invoice.is_overdue %}
  <span class="status-badge overdue">ÜBERFÄLLIG</span>
{% else %}
  <span class="status-badge pending">AUSSTEHEND</span>
{% endif %}
.status-badge {
  display: inline-block;
  padding: 5px 15px;
  border-radius: 20px;
  font-weight: bold;
  font-size: 10pt;
}

.status-badge.paid { background-color: #4CAF50; color: white; }
.status-badge.overdue { background-color: #f44336; color: white; }
.status-badge.pending { background-color: #ff9800; color: white; }

Beispiel: Zweispaltiges Layout​

.two-column {
  display: flex;
  gap: 20px;
}

.two-column > div {
  flex: 1;
}
<div class="two-column">
  <div>
    <h4>{{ t('bill_to') }}</h4>
    <p>{{ customer.name }}</p>
  </div>
  <div>
    <h4>{{ t('invoice_details') }}</h4>
    <p>{{ invoice.invoice_number }}</p>
  </div>
</div>

Beispiel: Umgang mit fehlenden Daten​

{% if customer.vat_id %}
  <p>USt-IdNr.: {{ customer.vat_id }}</p>
{% endif %}

{% if payment_terms.text %}
  <div class="payment-terms">
    <strong>{{ t('payment_terms_label') }}:</strong>
    {{ payment_terms.text }}
  </div>
{% endif %}

Anpassungen testen​

  1. Speichern Sie Ihre Vorlage in der IDE
  2. Überprüfen Sie die PDF-Vorschau im rechten Panel
  3. Erstellen Sie eine Testrechnung und wählen Sie Ihre Vorlage
  4. Laden Sie das generierte PDF herunter und überprüfen Sie es
  5. Drucken Sie das PDF, um die Formatierung auf Papier zu prüfen
  6. Testen Sie mit verschiedenen Sprachen, wenn Übersetzungen konfiguriert sind

Um Mehrsprachigkeit hinzuzufügen, fahren Sie fort mit Vorlagenübersetzungen.