Basic Concepts

The Mobilengine form language

The form language is an XML-based declarative language for describing a dynamic user interface for Mobilengine forms running in the browser. form is the root element of a form, which contains controls and various other elements.

controlSample.fls.xml

<form
xmlns='http://schemas.mobilengine.com/fls/v1'...>
  <textbox
    label="This is a text box.
          Click into it to edit the text."
    text="Hello World!"/>
...
</form>

Figure 196. A textbox control with some default text

All elements in Mobilengine forms are in the http://schemas.mobilengine.com/fls/v1 namespace.

Controls

Data input and data display controls are the basic building blocks of forms, and so the language as well. Controls are specific user interface elements that are displayed as a unit (such as textboxes or datepickers), and may contain child controls. Controls are declared in the language as XML elements.

controlSample.fls.xml

...
<chapter title="This is a heading">
  <checkbox text="The text is displayed to the right"/>
  <checkbox label="The label is displayed to the left"/>
</chapter>
...

Figure 197. The chapter control includes both checkboxes

Fields

Fields define the behavior (such as their display width) of the control elements that they are declared as XML attributes for. Fields are static - their values cannot be changed at runtime.

controlSample.fls.xml

...
<textview text="This textview is default width"/>
<textview width="5 em"
  text="This textview isn't very wide"/>
...

Figure 198. The textview at the bottom has a declared width of only 5 em

Properties

Properties store the data that is displayed and manipulated in the user interface, declared as XML attributes of a control. Their values can change during runtime.

Some properties, such as the title of chapter or popup controls, specify what is displayed in the form. The value of these properties can change only through data-binding.

propertySample.fls.xml

...
<chapter label="The title is non-user-editable,
                but can be data-bound: "
  title='{tbFoo.text}'/>
  <textbox id="tbFoo" text="FOO!"/>
</chapter>
...

Figure 199. The chapter control's title property is data-bound to the tbFoo textbox control's text property

Other properties, like the text of a textbox control, are directly user-editable, and store the actual form data that is submitted with a form. The value of such properties can change through either data-binding, or user input.

propertySample.fls.xml

...
<textbox id="tbBar"
  text='{SELECT GROUP_CONCAT(c.column_2, "-")
        FROM nonceWords c}'/>
...

Figure 200. The tbBar textbox has default text data-bound to it, but is also directly user-editable

Properties can be set up as both the source and (if they aren't read-only, such as selectedText or rows) the target of data-binding.

propertySample.fls.xml

...
<textbox id="tbBaz" text="BAZ!"/>
<textview id="tvYolo"text='{tbBaz.text}'/>
<textview text='{LOWER(tvYolo.text)}'/>
...

Figure 201. tvYolo's text property is both the source and target of data-binding

Traits

Declared as XML elements with child elements, traits mark places in the XML hierarchy where structured content is allowed, such as child controls, validators, or let elements that declare variables.

controlSample.fls.xml

...
<chapter title="This is a heading">
  <checkbox text="The text is displayed to the right"/>
  <checkbox label="The label is displayed to the left"/>
</chapter>
...

Figure 202. The two checkbox controls are declared as child elements of the chapter control

Elements

A special type of XML elements that are not displayed in the user interface, but affect form functionality in various ways. if elements dynamically show or hide one or more controls, let elements declare variables, and validator elements attach validation rules to one or more controls.

controlSample.fls.xml

...
<textbox text="This textbox is required.">
  <validation>
    <validator cond='{text != ""}'
      message="Please enter some text."/>
  </validation>
</textbox>
...

Figure 203. If the validation rule declared in the validator element is not met, an error message is displayed

Data-binding

Data-binding adds dynamic behavior to the user interface. The values of control properties are assigned in the language using data-binding expressions.

Data-binding expressions can reference and manipulate data from reference tables or other control properties. Data-bound value assignment is dynamic: whenever the input data changes, as a result of user input, for example, all dependent data-binding expressions are recalculated, and their target properties are assigned the recalculated values.

The sample below shows a very simple data-binding scenario, where the user-input in two textbox controls is data-bound into the text property of a textview control below them.

daqSample.fls.xml

...
<textbox id="input1"
  text="tobacconist"/>
<textbox id="input2"
  text="hovercraft"/>
<textview
  text='{"A(n) "
        || input1.text
        || " in a "
        || input2.text
        || "."}'/>
...

Figure 204. The textview at the bottom concatenates the text properties of the textboxes above it

When the value of a user-editable property is assigned by data-binding, user changes will overwrite the data-bound values, but all user input is lost whenever a dependency of the data-binding expression in the property changes and the expression is re-evaluated.

In the sample below, the text of the the tbAlicetextbox is data-bound into the tbBobtextbox.

propertySample.fls.xml

...
<textbox id="tbAlice" text="Alice"/>
<textbox id="tbBob" text='{tbAlice.text}'/>
...

The user can overwrite the data-bound text in tbBob,

Figure 205. User input overwrites data-bound value

but if the source of the data-binding changes, the user input is lost.

Figure 206. Recalculated data-bound value overwrites user input

Developer Documentation

Form Language Reference Guide