Output.Rocks verwendet geschweifte Klammern { und } innerhalb von Feldern, um Ausdrücke zu kennzeichnen, die ausgewertet werden sollen. Ausdrücke sind ein leistungsstarkes Werkzeug, um Daten in der Vorlage abzurufen und zu manipulieren.

Syntax und Verwendung

Die Expression-Syntax unterstützt verschiedene Elemente, die in beliebiger Komplexität kombiniert werden können:

Grundelemente

Einfache Datenfelder:

Einfacher Datenzugriff: <<{kunde.name}>>
Literale Werte: <<{123}>> und <<{'Text'}>>
Mathematische Operationen: <<{betrag * 1.19}>>
String-Konkatenation: <<{kunde.vorname + ' ' + kunde.nachname}>>

Ausdrücke ermöglichen die Kombination von Daten, Berechnungen und Funktionen in einem einzigen Feld.

Erweiterte Syntax

Funktionsaufrufe und komplexe Operationen:

Funktionsaufrufe: <<{round(verbrauch.kwh / 12, 2)}>>
Array-Zugriff: <<{verbrauch.monate[0].wert}>>
Verschachtelte Funktionen: <<{titleCase(toLowerCase(kunde.firma))}>>

Bedingte Logik:
<<cs_{tarif.typ == 'premium'}>>
Status: VIP-Kunde
<<else>>
Status: Standard-Kunde
<<es_>>

Komplexe Bedingung: <<{verbrauch.kwh * map(tarif.typ == 'premium' && verbrauch.kwh > 2000, true, 0.85, 1.0)}>>

String-Syntax beachten: Verwenden Sie immer einfache Anführungszeichen (') für String-Vergleiche, nicht doppelte (").

Anwendungsbereiche

Felder mit Ausgabe:

<<{ausdruck}>>                     // Ersetzt Feld mit Ergebnis

Vorlagen-Variablen:

<<$gesamtkosten={grundpreis + (verbrauch * arbeitspreis)}>>
Gesamtkosten: <<$gesamtkosten>> €

Vorlagen-Variablen verbessern Lesbarkeit und Performance bei komplexen Berechnungen.

Verfügbare Funktionen

Output.Rocks bietet umfangreiche Funktionsbibliotheken für verschiedene Anwendungsbereiche. Diese Funktionen können in Ausdrücken kombiniert werden, um komplexe Berechnungen und Datenmanipulationen durchzuführen.

Beispiel: Verbrauchsanalyse mit verschiedenen Funktionen:

Durchschnitt: <<{round((verbrauch.januar + verbrauch.februar + verbrauch.maerz) / 3, 0)}>> kWh/Monat

Trend: <<{map(verbrauch.aktuell > verbrauch.vorjahr, true, 'Anstieg', 'Rückgang')}>>

Telefon: <<{ifBlank(kunde.telefon, 'Nicht angegeben', kunde.telefon)}>>

Firma: <<{titleCase(toLowerCase(kunde.firma))}>>

Rechnungsdatum: <<{dateFormat(rechnungsdatum, 'dd.MM.yyyy')}>>

Gesamtbetrag: <<{numFormat(betrag, '#,##0.00', 'DE')}>> €

Funktionen können verschachtelt und kombiniert werden: round((wert1 + wert2) / 2, 2)

Expression-Funktionen:

Logik-Funktionen: ifBlank(), isBlank(), map()
Text-Funktionen: titleCase(), toUpperCase(), toLowerCase(), replace(), length()
Numerische Funktionen: round(), abs(), max(), min(), numFormat()
Datums-Funktionen: dateFormat(), dateAdd(), dateDiff()
Locale-Funktionen: numFormat(), locale() für Währung und Zahlenformate

Wichtige Syntax-Regeln

String-Literale: In Output.Rocks werden String-Werte in Ausdrücken immer mit einfachen Anführungszeichen (') angegeben, nicht mit doppelten Anführungszeichen (").

<<{kunde.status=='aktiv'}>>    ✓ Richtig
<<{kunde.status=="aktiv"}>>    ✗ Falsch

Operator-Priorität: Mathematische Operatoren folgen den üblichen Prioritätsregeln. Verwenden Sie Klammern () zur expliziten Gruppierung komplexer Ausdrücke.

Null-Werte: Ausdrücke handhaben null- und undefined-Werte automatisch. Verwenden Sie ifBlank() für explizite Behandlung fehlender Daten.

Verschachtelte Daten in Funktionen: Punktnotation wie objekt.feld funktioniert nicht direkt in Funktionsparametern. Verwenden Sie stattdessen Variablen:

❌ Funktioniert nicht: <<{map(objekt.wert, 'Wert1', 'Ausgabe 1 ', 'Wert2', 'Ausgabe 2', 'Ausgabe 3')}>>

✅ Richtig - Variable vorher definieren:

<<$variablenname=objekt.wert>>
<<{map($variablenname, 'Wert1', 'Ausgabe 1 ', 'Wert2', 'Ausgabe 2', 'Ausgabe 3')}>>

Eckige Klammern [objekt.feld] sind nicht die Lösung - sie sind nur für Bindestriche in Feldnamen und Array-Indizes gedacht.

Bedingte Logik

Für bedingte Logik verwendet Output.Rocks bedingte Abschnitte anstelle einer if()-Funktion:

<<cs_{verbrauch > 1000}>>
  <<cs_{tarif == 'premium'}>>
  Hoher Premium-Verbrauch
  <<else>>
  Hoher Standard-Verbrauch  
  <<es_>>
<<else>>
  Normaler Verbrauch
<<es_>>

Für eine detaillierte Erklärung zur Verwendung von bedingten Abschnitten, siehe Bedingte Abschnitte.

Operatoren

Output.Rocks Operatoren arbeiten mit verschiedenen Datentypen basierend auf der Docmosis Tornado Engine.

Die 5 wichtigsten Operatoren

1. Addition/String-Konkatenation (+)

<<{grundpreis + arbeitspreis}>>           // Numerische Addition: 89.90
<<{kunde.vorname + ' ' + kunde.nachname}>> // String-Konkatenation: "Anna Schmidt"

2. Gleichheit (== oder '!=')

<<cs_{status != 'aktiv'}>>               // negativer String-Vergleich
<<cs_{verbrauch == 1000}>>               // Numerischer Vergleich

3. Größer/Kleiner als (>, <, >=, <=)

<<cs_{alter > 18}>>                      // Numerischer Vergleich
<<cs_{verbrauch <= schwellenwert}>>       // Variable vs Variable

4. Logisches UND (&&) bzw. ODER (||)

<<cs_{status == 'aktiv' && verbrauch > 1000}>>  // Kombinierte Bedingungen

5. Klammern (()) für Prioritätssteuerung

<<{(grundpreis + arbeitspreis) * monate}>>       // Gruppierung von Operationen

Die Output.Rocks Engine überprüft automatisch den Datentyp und führt den entsprechenden Vergleich durch. Ein nicht-erwarteter Typ erzeugt einen Fehler beim Rendern.

Vollständige Operator-Referenz: Alle mathematischen, Vergleichs- und logischen Operatoren, Prioritätsregeln und erweiterte Beispiele finden Sie unter Operatoren.

Tornado-Basis: Diese Operatoren entsprechen der Docmosis Tornado Template Engine. Für spezifische Datentyp-Behandlung verwenden Sie Funktionen wie isBlank(), numFormat() oder dateFormat().

Best Practices

Lesbarkeit verbessern: Komplexe Ausdrücke sollten in Vorlagen-Variablen ausgelagert werden, um die Übersichtlichkeit zu erhöhen. Verwenden Sie beschreibende Variablennamen und setzen Sie Klammern für bessere Lesbarkeit.

Fehlerbehandlung: Nutzen Sie ifBlank() für fehlende Daten und implementieren Sie Null-Checks bei kritischen Berechnungen mit Fallback-Werten.

Formatierung: Verwenden Sie numFormat() für Währungsdarstellungen, einheitliche Datumsformate und runden Sie Dezimalstellen konsistent.

Performance: Vermeiden Sie wiederholte Berechnungen, bevorzugen Sie einfache Operatoren und reduzieren Sie unnötige Verschachtelungen.

Vorlagen-Variablen nutzen: Für wiederkehrende oder komplexe Berechnungen verwenden Sie Vorlagen-Variablen: <<$total={grundpreis + verbrauch * arbeitspreis}>>. Dies verbessert sowohl Lesbarkeit als auch Performance.

Ausdrücke sind das Herzstück dynamischer Vorlagen in Output.Rocks und ermöglichen die Erstellung intelligenter, datengesteuerter Dokumente für jeden Anwendungsfall in der Energiewirtschaft.