Developer Documentation

You can style and format Mobilengine form elements using the dedicated form style language to create a .syl-extension stylesheet.

Styling in the Mobilengine universe shares features both with external CSS stylesheets and in-line CSS references: stylesheets must be separately uploaded, but instead of using identifiers or classes, you need to reference the styles defined in the external stylesheets within the controls in the form.

To make the magic happen, write up a stylesheet that defines one or more collections of formatting choices, reference it in your forms, and publish it as just another solution artifact.

This section introduces you to how Mobilengine form styling works so that you can tackle the Rocky Jupiter forms well-prepared.

Mobilengine styles are similar to CSS in that they share the so-called box model as the basis of laying out and rendering elements. The user interface is rendered as a series of rectangular boxes that contain one another: outermost is the form canvas that contains a box for each control, which in turn contain specific control parts such as label and control as boxes. Controls that contain other controls (think chapter or table) open a new canvasJust like in CSS, each rectangular box in the hierarchy is further made up of boxes nested in one another. These have the same names as their CSS counterparts, and their order, going from outside in: margin, border, padding, and content.

To demonstrate the boxes and how they're nested, consider the following form with four textview controls: each control is assigned a different style, that is, a collection of styling options, using the style attribute, which must contain a reference to a style defined in the solution stylesheet to work.

All stylesheets are text files with the .syl extension, and have the styles {} object as their root that contains one or more stylename-of-style{} objects. These are the collections of styling options mentioned earlier. The style objects are themselves made up of element-name{} objects that specify the formatting for one or more controls or form elements that you apply the given style to in your form.

It sounds more complex than it really is. If you're even slightly familiar with CSS, the only interesting bit is that the style option tags use camel case, and that vaélues are assigned using the = sign.

So there's four style objects in the stylesheet, which might seem a lot to begin with, but all four are basically the same collection with tweaked values. All four manipulate the same formatting options of the same textview control:

Whatever formatting option a style object doesn't explicitly specified will be overridden by the default value for that option. More on defaults later.

Each style object is linked to one of the textviews in the form, so when you save the stylesheet and the form above and publish, this is what you will see on your device.

The distance between the textview controls (their margin) varies, and so does the width and color of their borders. The text in the controls is also at varying distances from the border inside the textviews, which is what the padding determines.

So far so good, right? No real biggies here - let's move on.

Your style objects so far have a nested object with the name of a form element, and apply a number of formatting options to it. It all seems crystal clear, but there are a number of complicating factors that in fact make your job easier or widen your range of styling options. The whole things is summarized in a handy diagram.

First of all, you don't need to explicitly list all the controls in your form just to override their defaults and apply the same formatting to each one. By using the all wildcard (line 21 in the stylesheet below), you can specify the same formatting options (called 'properties') for each control or control part within an element in a single swoop.

That brings us to the second interesting feature: controls are made up of control parts such as label and the control itself, among others. You can take granular control of the distinct parts that make up a particular control in your forms: in the example stylesheet below, both the First and Second style definitions specify different properties for the label and the control within nested textviews. If you want to style an element as a single unit, just include the properties as direct children of the element - this is what happens to the numberbox control in lines 6-9 below.

The third and perhaps most interesting feature of Mobilengine styling syntax is the existence of special properties, such as content in line 16 below, that are only available for certain types of form elements (you can only specify content for controls with child controls, for example), and that must always point to one (or more) other style definitions instead of being nested collections of further properties.

The associated form references the Chapter style definition in its root element, so all the controls will have their listed defaults overwritten.

Save the stylesheet and the form, and publish as usual, then open on your mobile device. The left and right parts of the textviews are displayed differently, the textbox plays by its own rules, and so do the chaptertitle and the numberbox as a whole at the bottom.

You've been coloring backgrounds and borders like there's no tomorrow, but so far only using a straightforward hexadecimal representation of RGB color codes (such as in line 7 below). The styling language accepts comma-separated non-hexadecimal RGB codes as well (see line 14 below), and hexadecimal RGBA codes too, so you can go ahead and create semi-transparent backgrounds (see line 33 in the stylesheet excerpt below).

Form styling wouldn't be complete without text formatting options: the styling language supports

All of the above have been put to good use in the over-the-top-formatted little demonstration form and its stylesheet.

It's just two textviews,

but because their control parts have been styled quite differently, the effect is a bit like looking at a two-column two-row table. Save, publish, and observe.

Knowing about default styles is crucial because every single styling property has a default value that gets applied to your form elements and their parts implictly. All style definitions do is just selectively override these defaults.

To have a look at the default style property values, use the mebt default-sylMobilengine Build Tool command. This will save a copy of the default stylesheet in your current folder so you can pore over it at your leisure.

style definitions in uploaded stylesheets are merged with the default stylesheet before styles and formatting are applied to the user interface. This effectively means that the style properties that aren't explicitly styled in one of your style definitions are governed by the default stylesheet. The same merging of style definitions goes on whenever you assign more than one style to a special style property: style property values are merged into a single style definition with the later definition in the comma-separated list overwriting any conflicting property values.