MVEL for Layout Templating

The MobileUI Framework uses the MVEL template engine to enable a programmable adaptation and comfortable styling of XML layouts. The MVEL template engine allows the application of the MVEL expression language for this purpose.

Basic Templating

MVEL Templates are comprised of orb-tags inside a plaintext document. Orb-tags denote dynamic elements of the template which the engine will evaluate at runtime.

A Simple Template

Hello @{person.getSex() == 'F' ? 'Ms.' : 'Mr.'} @{person.name}

This e-mail is to thank you for your interest in MVEL Templates 2.0.

This template shows a simple template with a simple embedded expression. When evaluated the output might look something like this:

Hello Ms. Sarah Peterson

This e-mail is to thank you for your interest in MVEL Templates 2.0.

Escaping the @ Symbol

Naturally, since the @ symbol is used to denote the beginning of an orb-tag, you may need to escape it, to prevent it from being processed by the compiler. Thankfully, there is only one situation where this is necessary: when you actually need to produce the string ‘@{’ as output in your template.

Since the compiler requires a combination of @ and { to trigger the orb recognition, you can freely use @ symbols without escaping them. For example:

Email any questions to: foo@bar.com

@{date}
@include{'disclaimer.html'}

But in the case where you need an @ symbol up-against an orb-tag, you will need to escape it by repeating it twice:

@{username}@@@{domain}

That’s two @’s to escape one symbol, and the third @ being the beginning of the tag. If this looks too messy, you can always use the alternate approach of using an expression tag, like this:

@{username}@{'@'}@{domain}

Orb Tags

This page contains a list of all orb-tags available out-of-the-box in the MVEL 2.0 templating engine.

@{} Expression Orb

The expression orb is the most rudimentary form of orb-tag. It contains a value expression which will be evaluated to a string, and appended to the output template. For example:

Hello, my name is @{person.name}

@code{} Silent Code Tag

The silent code tag allows you to execute MVEL expression code in your template. It does not return a value and does not affect the formatting of the template in any way.

@code{age = 23; name = 'John Doe'}
@{name} is @{age} years old.

This template will evaluate to: John Doe is 23 years old.

@if{}@else{} Control Flow Tags

The @if{} and @else{} tags provide full if-then-else functionality in MVEL Templates. For example:

@if{foo != bar}
    Foo not a bar!
@else{bar != cat}
    Bar is not a cat!
@else{}
    Foo may be a Bar or a Cat!
@end{}

All blocks in MVEL Templates must be terminated with an @end{} orb, except in cases of an if-then-else structure, where @else{} tags denote the termination of the previous control statement.

@foreach{} Foreach iteration

The foreach tag allows you to iterate either collections or arrays in your template. Note: that the syntax for foreach has changed in MVEL Templates 2.0 to standardize the foreach notation with that of the MVEL language itself.

@foreach{item : products} 
- @{item.serialNumber}
@end{}

MVEL 2.0 requires you specify an iteration variable. While MVEL 1.2 assumed the name item if you did not specify an alias, this has been dropped due to some complaints about that default action.

Multi-iteration

You can iterate more than one collection in a single foreach loop at one time by comma-separating the iterations:

@foreach{var1 : set1, var2 : set2}
    @{var1}-@{var2}
@end{}

Delimiting

You can automatically add a text delimiter to an iteration by specifying the iterator in @end{} tag.

@foreach{item : people}@{item.name}@end{', '}

This would return something like: John, Mary, Joseph.

@include{} Include Template File

You may include a template file into an MVEL template using this tag.

@include{'header.mv'}

This is a test template.

You may also execute an MVEL expression inside an include tag by adding a semicolon after the template name:

@include{'header.mv'; title='Foo Title'}

@includeNamed{} Include a Named Template

Named templates are templates that have been precompiled and passed to the runtime via a TemplateRegistry, or templates that have been declared within the template itself. You simply include:

@includeNamed{'fooTemplate'}
@includeNamed{'footerTemplate', showSomething=true}

You may also execute MVEL code in an @includeNamed{} tag, just as with the @include{} tag.

@declare{} Declare a Template

In addition to including external templates from external files, and passing them in programmatically, you can declare a template from within a template. Which allows you to do things like this:

@declare{'personTemplate'}
    Name: @{name}
    Age:  @{age}
@end{}

@includeNamed{'personTemplate'; name='John Doe'; age=22}

@comment{} Comment tag

The comment tag allows you add an invisible comment to the template. For example:

@comment{
This is a comment
}
Hello: @{name}!

MVEL Templates in MobileUI

MVEL templating can be used in MobileUI's layout files. Templates are rendered once, when the app is started for the first time. Their output is cached for performance. Whenever you change a configuration (e.g. the language or orientation), the MobileUI Framework will detect this. Layouts are then re-rendered and cached with the new configuration parameters.

Reference

The device variable is a pre-defined object with a list of properties describing the current device and configuration.

Please refer to the JavaDocs of io.nevernull.mobileui.core.template.DeviceTemplateVariables to find the properties, you can use in your template.

Example:

<TextView text="Report all bugs to @{device.isIos?'Apple':'Google'}!"/>