Variablen sind mächtige Werkzeuge in Output.Rocks Vorlagen, die es ermöglichen, Werte zu speichern, Berechnungen durchzuführen und komplexe Datenstrukturen zu referenzieren. Sie werden durch das <<$>> (Dollar) Symbol gekennzeichnet und bieten eine flexible Möglichkeit, Vorlagen zu optimieren und zu strukturieren.

Was sind Variablen?

Variablen können in Vorlagen erstellt werden, um den Wert eines einzelnen Datenfelds zu speichern oder als Referenz auf ein Datenobjekt zu dienen. Sie sind besonders nützlich für:

• Vereinfachung von langen Feldnamen
• Speicherung von Berechnungsergebnissen
• Referenzierung komplexer Objektstrukturen
• Performance-Optimierung durch Wiederverwendung

Grundlegende Variablen-Syntax

<<$firma=kunde.stammdaten.kontaktdaten.rechnungsadresse.name>>
<<$verbrauch=kunde.jahresverbrauch>>
<<$tarif=vertrag.tarifbezeichnung>>

Sehr geehrte Damen und Herren der <<$firma>>,

Ihr Jahresverbrauch beträgt <<$verbrauch>> kWh.
Sie sind im Tarif <<$tarif>> eingestuft.

Expressions in Variablen

Variablen können nicht nur einfache Feldwerte speichern, sondern auch das Ergebnis komplexer Berechnungen und Ausdrücke. Für Expressions müssen die Werte in geschweifte Klammern {...} gesetzt werden:

<<$summe={betrag1 + betrag2 + betrag3}>>
<<$kundenname={kunde.vorname + ' ' + kunde.nachname}>>
<<$rabatt={map(kunde.typ == 'Premium', true, 0.15, 0.05)}>>
<<$grundpreis_formatiert={numFormat(grundpreis, '#,##0.00')}>>

Verfügbare Expression-Typen:

• Mathematische Operationen: +, -, *, /, %
• Textverknüpfungen: String-Konkatenation mit +
• Bedingte Abschnitte: <<cs_{bedingung}>> für Logik
• Datentransformation: titleCase(), toLowerCase(), toUpperCase(), replace()
• Numerische Operationen: round(), abs(), max(), min(), ceil(), floor(), numFormat()
• Logikfunktionen: ifBlank(), isBlank(), map(), mapi()
• Datumsfunktionen: dateFormat(), dateAdd(), dateDiff()

Mehr Details zu Expressions finden Sie unter Ausdrücke und Funktionen.

Erweiterte Variablen-Anwendungen

<<$gesamtkosten=0>>
<<$ersterkunde=kunden[0]>>
<<$firmenname={ifBlank($ersterkunde.name, 'Unbekannter Kunde')}>>

Kostenaufstellung für das Jahr:

<<rs_tarife>>
- <<bezeichnung>>: <<$kosten={ifBlank(grundpreis, 0) * 12 + ifBlank(arbeitspreis, 0) * ifBlank(verbrauch, 0)}>> €
<<$gesamtkosten={$gesamtkosten + $kosten}>>
<<es_>>

Gesamtkosten: <<{numFormat($gesamtkosten, '#,##0.00')}>> €
Referenzkunde: <<$firmenname>>

Gültigkeitsbereiche von Variablen

Legende:

• Teil-Vorlagen (Blau): Interne Variablen nur innerhalb der Teil-Vorlage verfügbar

• Überschneidung: Teil-Vorlagen können globale Variablen lesen (aber nicht umgekehrt)

• Global (Grün): Vorlagen-übergreifende Variablen mit Schleifen- und bedingten Unterbereichen

• Variablen-Sichtbarkeit:

• Globale Variablen: Überall verfügbar (Stamm-Vorlagen, Teil-Vorlagen)

• Teil-Vorlagen: Sehen globale Variablen, eigene Variablen nicht global sichtbar

• Komponenten: Völlig isoliert, vorgerendert in eigenem Kontext

• Schleifen/Bedingte: Lokaler Scope (rs_/rr_ und cs_ Bereiche)

<<$jahreskosten=0>>

Kostenübersicht:

<<rs_quartale>>
  <<$quartalssumme={map(monate, 'betrag') + map(monate, 'grundpreis')}>>
  Quartal <<$itemnum>>: <<$quartalssumme>> €
  <<$jahreskosten={$jahreskosten + $quartalssumme}>>
<<es_>>

Gesamtkosten: <<$jahreskosten>> €

Alternative Syntax mit var_

Output.Rocks unterstützt eine alternative Syntax für Variablen mit var_ anstelle von $. Diese ist besonders nützlich in Microsoft Word, wo das Dollar-Symbol in Bookmark-Namen nicht verwendet werden kann.

<<$firmenname=kunde.unternehmen.name>>
<<var_kontakt=kunde.ansprechpartner.name>>

Firma: <<$firmenname>>
Kontakt: <<var_kontakt>>

Beide Werte: <<$firmenname>> / <<var_firmenname>>

Sichere Variablen-Referenzen

In Vorlagen, die von verschiedenen Quellen aufgerufen werden, kann es vorkommen, dass eine Variable möglicherweise nicht initialisiert wurde. Output.Rocks bietet dafür "nachsichtige" Variablen-Lookups:

<<cs_{isBlank($?unternehmen)}>>
Kein Unternehmen angegeben
<<else>>
Unternehmen: <<$unternehmen>>
<<es_>>

Kontakt: <<$?ansprechpartner>>

Built-in Variables

Output.Rocks stellt eine Reihe von eingebauten Variablen zur Verfügung, die automatisch in jedem Template verfügbar sind. Diese Built-in Variables bieten Zugriff auf Kontext-Informationen, Zeitstempel, Formatierungshilfen und Meta-Daten ohne explizite Definition.

Navigation und Datenkontext

Diese Variablen ermöglichen die Navigation durch die JSON-Datenstruktur und den Zugriff auf verschiedene Kontext-Ebenen.

Stammdaten: <<$root.kunde.firmenname>>

<<rs_rechnungen>>
  Rechnung: <<rechnungsnummer>>
  Aktueller Kontext: <<$this.betrag>> €
  
  <<rs_positionen>>
    Position: <<beschreibung>>
    Preis: <<$this.einzelpreis>> €
    
    Von oben: <<$parent.rechnungsnummer>>
    Stamm: <<$root.kunde.firmenname>>
  <<es_>>
<<es_>>

Zeitstempel

Built-in Variables für Zeitinformationen werden automatisch zum Zeitpunkt der Vorlagen-Verarbeitung generiert.

Rechnung erstellt am: <<dateFormat($nowUTC, 'dd.MM.yyyy')>>
Zeitstempel: <<dateFormat($nowUTC, 'dd.MM.yyyy HH:mm:ss')>>

Millisekunden seit 1970: <<$nowMS>>
UTC-Zeit (ISO): <<$nowUTC>>

Verarbeitungszeit: <<$nowMS>> ms

Zeilenumbrüche

Die Built-in Variablen <<$nl>> und <<$nl2>> helfen bei der Formatierung und Strukturierung der Ausgabe, besonders in Wiederholenden Abschnitten wie Tabellen und Listen.

Kunde: EnergiePartner Nord GmbH<<$nl>>
Adresse: Musterstraße 123<<$nl>>

Rechnungspositionen:<<$nl>>
<<rs_positionen>>
- <<beschreibung>>: <<einzelpreis>> €<<$nl>>
<<es_>>

Zeilenumbruch-Test:
Zeile 1<<$nl>>Zeile 2<<$nl>>Zeile 3

Meta-Informationen

Built-in Variables, die Informationen über die Vorlagen-Verarbeitung und -Umgebung bereitstellen.

Template-Engine: <<$tornado>>
Tornado-Version: <<$tornadoVersion>>
Docmosis-Version: <<$docmosisVersion>>

Verarbeitungszeit: <<$nowMS>> ms
UTC-Format: <<$nowUTCFormat>>

Debug-Informationen:
- Engine: <<$tornado>>
- Version: <<$tornadoVersion>>
- Zeitstempel: <<$nowUTC>>

Range Specifiers und Lookups

Range Specifiers sind ein Werkzeug, um den gezielten Zugriff auf bestimmte Elemente in Arrays und Listen zu ermöglichen. Sie können kombiniert mit hierarchischen Lookups (z.B. <<kunde.stammdaten.firmenname>>) verwendet werden, um eine große Auswahl an Daten zu selektieren.

Erste Rechnung: <<rechnungen[0].nummer>>
Letzte Rechnung: <<rechnungen[L].nummer>>
Alle Rechnungen: <<rechnungen[*].nummer>>

Erste 3 Rechnungen:
<<rs_rechnungen[F3]>>
- <<nummer>>: <<betrag>> €
<<es_>>

Letzte 2 Rechnungen:
<<rs_rechnungen[L2]>>
- <<nummer>>: <<betrag>> €
<<es_>>

Spezielle Auswahl (Index 1,3,5):
<<rs_rechnungen[1,3,5]>>
- <<nummer>>: <<betrag>> €
<<es_>>

Komplex: Letzte Position der ersten Rechnung:
<<rechnungen[0].positionen[L].beschreibung>>

Erweiterte Range-Kombinationen:

Alle außer letzten 2: <<rechnungen[0-L2].nummer>>

Range 1-3 plus letzte 2:
<<rs_rechnungen[1-3,L2]>>
<<$itemnum>>. <<nummer>> (<<betrag>> €)
<<es_>>

Hierarchische Navigation:
Kunde: <<kunde.stammdaten.firmenname>>
Anschrift: <<kunde.stammdaten.adresse.strasse>> <<kunde.stammdaten.adresse.hausnummer>>

Verbrauchsdaten - Letzte Messung:
Zählerstand: <<kunde.zaehler[0].messungen[L].stand>> kWh
Datum: <<kunde.zaehler[0].messungen[L].datum>>

Erste und letzte Messung vergleichen:
Start: <<kunde.zaehler[0].messungen[0].stand>> kWh
Ende: <<kunde.zaehler[0].messungen[L].stand>> kWh
Verbrauch: <<{kunde.zaehler[0].messungen[L].stand - kunde.zaehler[0].messungen[0].stand}>> kWh

Best Practices für Variablen

Defensive Programmierung mit Logik-Funktionen

1. Sichere Standardwerte:

// Statt unsicherer Variablen:
<<$name=kunde.vorname + ' ' + kunde.nachname>>

// Verwende ifBlank() für Fallbacks:
<<$name={ifBlank(kunde.vorname, 'Unbekannt') + ' ' + ifBlank(kunde.nachname, 'Unbekannt')}>>

2. Null-sichere Berechnungen:

// Statt direkter Berechnungen:
<<$jahreskosten={monatlich * 12}>>

// Verwende ifBlank() für null-Werte:
<<$jahreskosten={ifBlank(monatlich, 0) * 12}>>

3. Intelligente Klassifizierung:

// Status-Mapping mit map():
<<$status_text={map(kunde.status, 'A', 'Aktiv', 'I', 'Inaktiv', 'Unbekannt')}>>

// Case-insensitive mit mapi():
<<$verbrauchstyp={mapi(zaehler.typ, 'smart', 'Intelligenter Zähler', 'analog', 'Standard-Zähler', 'Unbekannt')}>>

Allgemeine Richtlinien