United Planet GmbH

$CalcUtil

Inhalt

Einleitung

Im Folgenden wird das Velocity-Kontextobjekt zur Berechnung von Werten vorgestellt und anhand von Codebeispielen erläutert.

$CalcUtil

Mit der Funktion calculate() des Objekts $CalcUtil (JavaDoc Link) können beliebig komplexe Rechen- und Vergleichsoperationen durchgeführt werden. Zur Strukturierung der Operation stehen Ihnen die '( )' Klammern zur Verfügung. Die Werte für die durchzuführenden Rechen- und Vergleichsoperationen können aus Datenfeldern, Sessions, Requests, Tabellenzellen oder SharedStates ausgelesen werden.


Operatoren

Folgende Operatoren stehen innerhalb einer Berechnungsformel stehen zur Verfügung:

  • + (Addition)
  • - (Subtraktion)
  • * (Multiplikation)
  • / (Division)
  • < (Vergleich Kleiner)
  • > (Vergleich Größer)
  • <= (Vergleich Kleiner gleich)
  • >= (Vergleich Größer gleich)
  • == (Vergleich Gleich)
  • != (Vergleich Ungleich)
  • && (Logische Verknüpfung Und)
  • || (Logische Verknüpfung Oder)
  • ! (Logischer Operator Nicht)

Weitere Typkategorien und Methoden

Zusätzlich zu den oben beschriebenen Operatoren existieren noch weitere Möglichkeiten, in Formeln bestimmte Variablen oder Methoden aufzurufen:


MethodeBeschreibungBeispiel
datafieldWert aus einem Datenfelddatafield("C68F6...D3DE7")
datafieldAsNumberWert aus einem Datenfeld als NumberdatafieldAsNumber("C68F6...D3DE7")
sessionWert aus einer bestehenden Session des aktuell angemeldeten Benutzerssession("sessionValue")
sessionAsNumberWert aus einer bestehenden Session des aktuell angemeldeten BenutzerssessionAsNumber("sessionValue")
sharedStateWert aus dem aktuellen VerarbeitungskontextsharedState("sharedStateValue")
sharedStateAsNumberWert aus dem aktuellen VerarbeitungskontextsharedStateAsNumber("sharedStateValue")
requestAsNumberWert aus dem aktuellen RequestrequestAsNumber("rq_requestValue")
absAbsolutbetragabs(-1)

Bei den Typangaben mit Suffix AsNumber wird, soweit technisch möglich, versucht, die eingehenden Werte zu casten. Ohne diesen Cast wird zum Beispiel bei der Verwendung von String-Datenfeldern eine Exception auftreten. Boolean-Werte true und false werden entsprechend zu 1 bzw. 0 gecastet.

Optional ist es möglich, dass als zweiter Methodenparameter ein Fallback angegeben werden kann, der verwendet wird, wenn der erste Parameter null oder leer sein sollte. Bei diesem Fallbackvalue kann es sich wiederum auch um eine Formel handeln.

//liefert -1, wenn der Zugriff auf die SharedState-Variable sharedStateValue null zurückliefert oder der Wert nicht gesetzt ist.
sharedState("sharedStateValue", -1)

//liefert 5, wenn der Zugriff auf die Request-Variable rq_custom null zurückliefert oder der Wert nicht gesetzt ist.
requestAsNumber("rq_custom", (10/2))

//liefert 0, wenn das Datenfeld null enthält oder nicht gesetzt wurde.
datafield("C68F6...D3DE7", 0)

Fehlerbehandlung

Zum Abfangen potenzieller Fehler (z.B. Teilen durch 0) existieren folgende Methoden, die innerhalb einer Formel verwendet werden können:


MethodeBeschreibungBeispiel
zeroOnErrorRückgabe von 0 im FehlerfallzeroOnError(10/0) == 0
oneOnErrorRückgabe von 1 im FehlerfalloneOnError(10/0) == 1
fallbackOnErrorIm Fehlerfall wird der als fallback definierte Wert zurückgeliefertfallbackOnError(10/0, 2) == 2

Rundungsfunktionen

Innerhalb von Formeln ist es möglich, Zahlenwerte zu runden. Der Parameter scale beschreibt hierbei immer die Anzahl der Nachkommastellen


MethodeAnmerkungen
roundLongBuchhalterisches Runden
roundLongHalfAwayFromZeroentspricht roundLong
roundLongHalfEven
roundLongHalfUp
roundLongHalfDown
round(scale)Buchhalterisches Runden auf scale Nachkommastellen (roundLong entspricht round(0))
roundLongHalfAwayFromZero(scale)entspricht round(scale)
roundLongHalfEven(scale)
roundLongHalfUp(scale)
roundLongHalfDown(scale)

Fallunterscheidungen

Innerhalb von Formeln können Fallunterscheidungen vorgenommen werden, um Vorbedingungen abprüfen zu können und anhand deren Ergebnis bestimmte Formeln oder Werte zu verwenden.

case(<booleanExpression>, <Formel für true>, <Formel für false>)

Für den boolschen Ausdruck bestehen hierbei folgende Regeln:

  • null == false
  • leer == false
  • 0 == false
  • false == false
  • !true == false
  • !false == true
  • 1 == true

Werden logische Operatoren zum Berechnen verwendet, wird false zu 0 und true zu 1. Folglich ergibt sich:

5 > 0 + 0 > -1 == 2

Beispiele für die Verwendung der Funktion calculate() auf Ansichtsseiten

Ein Berechnungsaufruf über calculate() besitzt immer drei Parameter:

  • $ProcessingContext - Der aktuelle Verarbeitungscontext. Wert ist immer fix.
  • Die aktuelle Datarange - $DC für Tabellen und Ansichtsseiten.
  • Formel - Beliebig geschachtelte Formel, bestehend aus den o.g. Methoden und Operatoren.

Einfache Addition zweier Werte

Einfaches Beispiel einer Addition, deren Werte aus Datenfeldern gelesen werden. Um ein Datenfeld anzusprechen, können Sie entweder GUID des Datenfeldes oder den Namen der Kontrolle in Hochkommatas angeben.

## Der Methode calculate() zu übergebende Parameter:
## $ProcessingContext (Fester Wert)
## $DC 
## '<Name der Kontrolle des 1. Summanden>'
## <Operator>
## '<Name der Kontrolle des 2. Summanden>'
$CalcUtil.calculate($ProcessingContext, $DC, 'dataField("integervcontrol1") + dataField("integervcontrol2")')

##Gleiches Beispiel, jedoch wird hier die GUID des Datenfeldes (nicht der Kontrolle) verwendet
$CalcUtil.calculate($ProcessingContext, $DC, 'dataField("3BB...5B3") + dataField("C95...950")')

Weitere Beispiele

Die in den oberen Abschnitten beschriebenen Methoden lassen sich beliebig kombinieren und schachteln, um Werte aus verschiedenen Quellen (Session, Request, ...) kombinieren zu können.

## Kombination aus Datenfeld und Sessionwert.
$CalcUtil.calculate($ProcessingContext, $DC,'dataField("3BB...5B3") + session("calcutil_example")')

## Kombination aus Datenfeld und Requestwert.
$CalcUtil.calculate($ProcessingContext, $DC, 'dataField("floatcontrol02E5") + requestAsNumber("rq_calcUtil")')

## Kleiner-Vergleich auf Requestwert.
#set($term = '(dataField("B5F472ED66DCA878683B52CE8F979F4F1DDA172B") * 2) + session("calcutil_value") <
requestAsNumber("rq_calcUtil")')
$CalcUtil.calculate($ProcessingContext, $DC, $term)

## Fallunterscheidung auf Requestwert
#set($term = '(dataField("B5F472ED66DCA878683B52CE8F979F4F1DDA172B") * 2)')
$CalcUtil.calculate($ProcessingContext, $DC, "case(requestAsNumber('rq_calcUtil') <= 100, $term, -1)")

Aggregatsfunktionen für Tabellen

Über $CalcUtil ist es auch möglich, Werte aus Spalten einer Tabellen zu verarbeiten. Es stehen hierbei die in der folgenden Tabelle aufgelisteten Rechenoperationen zur Verfügung. Die Aufrufe der Methoden für Tabellen besitzen hierbei immer zwei Parameter:

Tabellenobjekt

Zugriff auf Tabelle - entweder per Tabellenname oder Tabellen-GUID. WICHTIG: Es handelt sich hierbei NICHT um den Namen und die GUID der Tabellenkontrolle direkt, sondern um die Werte des Attributs tablerecords bei Ansichtstabellen bzw. shapedtablebase bei frei gestalteten Tabellen. Sie erhalten den Wert, in dem Sie im Intrexx Manager über das Kontextmenü der Seite, auf der sich die Tabelle befindet, die Option Elemente anzeigen wählen. Navigieren Sie darin zur gewünschten Tabelle. Innerhalb der Kontrolle existiert der Abschnitt tablerecords bzw. shapedtablebase. Über die Taste F4 oder Enter können Sie den gewünschten Eigenschaftendialog öffnen.

Formel

Beliebig geschachtelte Formel. Zugriff auf Spaltenwerte über row(<Spaltenname>) bzw. rowAsNumber(<spaltenname>)

$CalcUtil.calculate($ProcessingContext, $DC, 'sum(table("8E9...1B3"), row("integervcontrol3621234C"))')
$CalcUtil.calculate($ProcessingContext, $DC, 'sum(table("8E9...1B3"), row("integervcontrol3621234C"))')
Es ist wichtig zu beachten, dass die Werte beim Aufrufen der Seite berechnet werden. Besitzt die Tabelle Navigationselemente und werden diese verwendet, aktualisieren sich NICHT die Werte der Velocity-Anweisungen und -Berechnungen, da die Tabelle dynamisch per AJAX nachgeladen wird. Sollte also gewünscht sein, Tabellenberechnungen auch nach einer Navigation innerhalb der Tabelle durchzuführen, muss das entsprechende VTL-Include (respektive die VM-Datei) ebenfalls per AJAX nachgeladen werden. Als Workaround wird geraten, die zu berechnende Tabelle so aufzubereiten, dass keine Navigation notwendig ist.
MethodeBeschreibung
sumBerechnet die Summe der Spaltenwerte aus jenen Daten, die auf der aktuellen Seite angezeigt werden.
minBerechnet das Minimum der Spaltenwerte aus jenen Daten, die auf der aktuellen Seite angezeigt werden.
maxBerechnet das Maximum der Spaltenwerte aus jenen Daten, die auf der aktuellen Seite angezeigt werden.
countBerechnet die Anzahl der Datensätze, die auf der aktuellen Seite angezeigt werden.

Beachten Sie, dass es sich bei den folgenden Methoden um "teure", d.h. rechenintensive Operationen handelt. Bei sehr großen Datenbeständen können entsprechende Verzögerungen auftreten.

MethodeBeschreibung
totalSumBerechnet die Summe der Spaltenwerte aller Datensätze.
totalMinBerechnet das Minimum der Spaltenwerte aller Datensätze.
totalMaxBerechnet das Maximum der Spaltenwerte aller Datensätze
totalCountBerechnet die Anzahl aller Datensätze.
Beachten Sie bitte: Befindet sich in einer Tabelle kein Datensatz, liefern die o.g. Methoden die Zahl 0 als Rückgabewert.
## Beispielausgabe eines Infotextes unterhalb einer Artikeltabelle
#set($sum = 'totalSum(table("8E9F10DCB24CBB4B27FF67A3230CE7753521E1B3"), row("integervcontrol3621234C"))')
#set($count = 'totalCount(table("8E9F10DCB24CBB4B27FF67A3230CE7753521E1B3"), row("floatvcontrol256AC41"))')
Es wurden $CalcUtil.calculate($ProcessingContext, $DC, $count) Artikel in 
einem Gesamtwert von $CalcUtil.calculate($ProcessingContext, $DC, $sum) € bestellt