The OFBiz scripting languages (screen widgets and minilang) support the use of Uniform Expression Language (UEL) expressions. See the PDF attachment for more on UEL.

OFBiz adds the following extensions to the UEL:

  1. OFBiz supports nested expressions
  2. ${someList[]} - appends a list element. It is converted internally to ${someList['add']}
    - so that syntax could be used as well.
  3. ${someList[+0]} - inserts a list element at the specified index. It is converted internally to ${someList['insert@0']} - so that syntax could be used as well.
  4. OFBiz supports variable creation (auto-vivify). In the expression ${someMap.anotherMap.mapElement} if someMap or anotherMap don't exist, they are created.
  5. OFBiz has a number of built-in UEL functions (API)

The OFBiz scripting languages do not support deferred expression evaluation (#{} expressions).

UEL and the <set> Element

Due to the unique way UEL is implemented in OFBiz, there can be some confusion on where the brackets are needed. Generally speaking, the field and from-field attributes don't require brackets, and the value attribute does require brackets. Here are some examples to illustrate:

<!-- The field and from-field attributes support UEL syntax without using enclosing brackets -->
<set field="someMap[mapKey]" value="Hello World!"/>
<set field="helloWorldText" from-field="someMap[mapKey]"/>

<!-- Brackets can be used to make the value attribute behave like the from-field attribute -->
<set field="someMap[mapKey]" value="Hello World!"/>
<set field="helloWorldText" value="${someMap[mapKey]}"/>

Operator Substitutions

OFBiz supports logical operator substitutions to make it easier to embed UEL expressions in XML.

<!-- The expression ${foo && bar} without operator substitution -->
<set field="booleanResult" value="${foo &amp;&amp; bar}"/>
<!-- The expression ${foo && bar} with operator substitution -->
<set field="booleanResult" value="${foo @and bar}"/>

Operator

Substitution

&&

@and

||

@or

<

@lt

>

@gt

<=

@lteq

>=

@gteq

Handling Missing Variables

The expression ${foo + bar} will throw an exception if either variable is missing. OFBiz provides a variable name modifier that performs substitutions for missing variables in expressions. When a variable name modifier is used in an expression, OFBiz will try to find the variable. If the variable doesn't exist, a new object of the type specified in the modifier will be substituted for the variable.

<!-- This expression will throw an exception if either variable is missing -->
<set field="integerResult" value="${foo + bar}"/>
<!-- This expression will work even if either variable is missing -->
<set field="integerResult" value="${foo$integer + bar$integer}"/>

Modifier

Substitution

$null

null

$string

Empty String

$boolean

Boolean false

$integer

Integer zero

$long

Long zero

$double

Double zero

UEL and the Document Object Model (DOM)

OFBiz combines XPath UEL extensions and built-in functions to make it possible to work with Document Object Model documents:

<!-- Read the Example component UI label file into a DOM Document -->
<set field="document" from-field="dom:readXmlDocument('component://example/config/ExampleUiLabels.xml')"/>
<!-- Get a List of property Elements from the Document -->
<set field="elementList" from-field="document['//property']"/>
<!-- Iterate through the property Element List -->
<iterate entry="element" list="elementList">
  <log level="always" message="Property Key: ${element['@key']}"/>
  <log level="always" message="First Value: ${element['value[1]']}"/>
</iterate>

You can use the DOM extensions to implement simple web page scrapers and mashups:

<!-- Read this Wiki page into a DOM Document -->
<set field="document" from-field="dom:readHtmlDocument('http://docs.ofbiz.org/display/OFBTECH/Unified+Expression+Language+(JSR-245)+in+OFBiz')"/>
<!-- Get a list of wiki-content DIV Elements from the Document -->
<set field="wikiDivList" from-field="document[&quot;//DIV[@class='wiki-content']&quot;]"/>
<!-- Convert this section of the page to an HTML String -->
<set field="wikiContent" from-field="dom:toHtmlString(wikiDivList[0], 'UTF-8', true, 2)"/>
<log level="always" message="Wiki content: ${wikiContent}"/>

HTML element names are always upper case, and attribute names are always lower case. Keep that in mind when creating XPath expressions for HTML documents.

UEL Tips and Tricks

The ${ofbiz.home} identifier is used in OFBiz documentation to represent the home folder for OFBiz. If you need access to the OFBiz home folder context variable, the correct expression used to be ${env.ofbiz.home}, but that has been replaced with the preferred ${sys:getProperty('ofbiz.home')} expression introduced with the Uniform Expression Language. For more information, see built-in UEL functions (API).

If you want an expression to be kept as a String, you can either surround it with quotes, or convert it to a String with the UEL function str:toString(Object). The function can also be used when an ID is unintentionally localized - ID 10000 is displayed as 10,000.

If you need to display an expression as-is (you don't want it evaluated) you can escape expression evaluation with a backslash: \${someExpression}.