Kurzbeschreibung

Das XML-Element <Math> dient zur Durchführung mathematischer Berechnungen innerhalb einer Dokumentvorlage.

Die Berechnung erfolgt auf Basis der innerhalb des Elements angegebenen Operanden. Das Ergebnis kann gespeichert, direkt ausgegeben oder gleichzeitig gespeichert und ausgegeben werden.

Dadurch lassen sich Berechnungen direkt innerhalb der Dokumentvorlage durchführen, ohne auf externe Berechnungen angewiesen zu sein.

Einordnung

Bereich: Funktionen

Schwierigkeitsgrad: ⭐⭐⭐☆☆

Vorkenntnisse: Variable · Text · Setter

Empfohlener nächster Artikel: DateAdd

Zweck

Mit <Math> können numerische Berechnungen innerhalb einer Dokumentvorlage durchgeführt werden.

Typische Einsatzgebiete sind:

• Berechnung von Beträgen
• Prozentberechnungen
• Multiplikation von Werten
• Division von Beträgen
• Bildung von Summen
• Zwischenspeichern berechneter Werte

Das Ergebnis kann anschließend

• direkt im Dokument ausgegeben,
• für spätere Berechnungen gespeichert oder
• gleichzeitig gespeichert und ausgegeben werden.

Grundsyntax

<Math
    Name="Gesamtbetrag"
    Operation="addieren"
    Usage="speichern_und_ausgeben">

    <Variable Path="custom.1">
    </Variable>

    <Variable Path="custom.2">
    </Variable>

    <Text Content="100">
    </Text>

</Math>

Position innerhalb der Dokumentvorlage

Das XML-Element <Math> erzeugt entweder eine Ausgabe oder einen berechneten Wert.

Es wird deshalb innerhalb eines <Content> verwendet.

<Block>

    <Content>

        <Math
            Name="Gesamtbetrag"
            Operation="addieren"
            Usage="ausgeben">

            ...

        </Math>

    </Content>

</Block>

Ablauf der Verarbeitung

Die Render-Engine verarbeitet <Math> schrittweise.

Operanden lesen
       │
       ▼
Reihenfolge übernehmen
       │
       ▼
Operation ausführen
       │
       ▼
Ergebnis berechnen
       │
       ▼
Usage auswerten
       │
 ┌─────┼────────────┐
 ▼     ▼            ▼
ausgeben speichern speichern_und_ausgeben

XML-Wissen

<Math> verarbeitet sämtliche Operanden in der Reihenfolge ihres Auftretens innerhalb des XML-Codes.

Es erfolgt keine mathematische Priorisierung wie beispielsweise Punkt-vor-Strich-Rechnung.

Attribute

Math

Name

Über das Attribut Name wird festgelegt, unter welchem Namen das Ergebnis gespeichert wird.

<Math
    Name="Gesamtbetrag"
    Operation="addieren"
    Usage="speichern">

Das gespeicherte Ergebnis kann anschließend beispielsweise über <Variable> oder innerhalb eines <If> weiterverwendet werden.

Operation

Die Rechenoperation wird über das Attribut Operation festgelegt.

Zur Verfügung stehen folgende Werte.

Usage

Das Attribut Usage legt fest, wie mit dem Berechnungsergebnis umgegangen wird.

Format

Über Format kann das Ergebnis formatiert ausgegeben werden.

Beispielsweise:

<Math
    Format="C"
    ...
>

Die verfügbaren Formatangaben entsprechen den unterstützten Zahlenformaten.

Typische Beispiele sind:

Operanden

Die Berechnung erfolgt auf Basis aller XML-Elemente innerhalb des <Math>.

Typische Operanden sind:

• <Variable>
• <Text>

Beispiel:

<Math
    Name="Summe"
    Operation="addieren"
    Usage="ausgeben">

    <Variable Path="custom.2">
    </Variable>

    <Variable Path="custom.1">
    </Variable>

    <Text Content="100">
    </Text>

</Math>

In diesem Beispiel werden drei Operanden verarbeitet.

Reihenfolge der Berechnung

Die Reihenfolge der Operanden ist entscheidend.

Beispiel:

<Math
    Operation="subtrahieren"
    Usage="ausgeben">

    <Text Content="100">
    </Text>

    <Text Content="20">
    </Text>

    <Text Content="5">
    </Text>

</Math>

Das Ergebnis lautet:

100 - 20 - 5 = 75

Nicht dagegen:

100 - (20 - 5)

Dasselbe gilt für Divisionen.

Die Berechnung erfolgt stets von links nach rechts entsprechend der Reihenfolge der Operanden im XML-Code.

Hinweis

Die Reihenfolge der Operanden ist insbesondere bei den Operationen subtrahieren und dividieren von Bedeutung.

Ergebnis speichern

<Math
    Name="MatheRechnung1"
    Operation="addieren"
    Usage="speichern">

    <Variable Path="custom.2">
    </Variable>

    <Variable Path="custom.1">
    </Variable>

    <Text Content="100">
    </Text>

</Math>

Das Ergebnis wird unter dem Namen MatheRechnung1 gespeichert.

Es erfolgt keine Ausgabe im Dokument.

Ergebnis ausgeben

<Math
    Format="C"
    Name="123"
    Operation="addieren"
    Usage="ausgeben">

    <Variable Path="custom.2">
    </Variable>

    <Variable Path="custom.1">
    </Variable>

    <Text Content="100">
    </Text>

</Math>

Das Ergebnis wird direkt im Dokument ausgegeben.

Ergebnis weiterverwenden

Ein gespeichertes Ergebnis kann anschließend wie eine Variable verwendet werden.

Beispielsweise:

<If
    Compare="2000"
    DataType="Text"
    IsGreater="MatheRechnung1">

    <TrueContainer>

        <Block>

            <Content>

                <Text Content="Größer als 2000 €.">
                </Text>

            </Content>

        </Block>

    </TrueContainer>

    <FalseContainer>

        <Block>

            <Content>

                <Text Content="Kleiner als 2000 €.">
                </Text>

            </Content>

        </Block>

    </FalseContainer>

</If>

XML-Wissen

Ein unter Name gespeichertes Berechnungsergebnis steht anschließend innerhalb der Dokumentvorlage wie eine Variable zur Verfügung.

Es kann beispielsweise in <Variable>, <If>, <Case> oder weiteren XML-Elementen verwendet werden.

Typische Fehler

Fehlende Usage

Ohne eine geeignete Usage wird das Ergebnis unter Umständen weder gespeichert noch ausgegeben.

Falsche Reihenfolge

Bei Subtraktion und Division beeinflusst die Reihenfolge der Operanden unmittelbar das Berechnungsergebnis.

Nicht numerische Werte

Alle Operanden sollten numerische Werte liefern.

Textinhalte, die nicht als Zahl interpretiert werden können, führen zu einem fachlich unerwarteten Ergebnis beziehungsweise zu einer fehlerhaften Verarbeitung.

Fehlendes Name bei Speicherung

Soll das Ergebnis später weiterverwendet werden, muss ein eindeutiger Name vergeben werden.

Best Practices

• Verwenden Sie sprechende Namen.
• Nutzen Sie speichern, wenn das Ergebnis mehrfach benötigt wird.
• Verwenden Sie ausgeben für einmalige Berechnungen.
• Nutzen Sie speichern_und_ausgeben, wenn beides erforderlich ist.
• Achten Sie auf die Reihenfolge der Operanden.
• Verwenden Sie ein geeignetes Zahlenformat.
• Halten Sie Berechnungen übersichtlich und teilen Sie komplexe Berechnungen gegebenenfalls auf mehrere <Math>-Elemente auf.

Technischer Hinweis

Während der Dokumenterzeugung verarbeitet die Render-Engine sämtliche Operanden innerhalb des <Math> in ihrer Reihenfolge.

Anschließend wird die angegebene Rechenoperation ausgeführt.

Abhängig vom Attribut Usage wird das Ergebnis gespeichert, ausgegeben oder beides.