public final class UIFragment

Encapsulates an XML or JSON template for a UI component hierarchy. The UI can be defined using XML. The XML is compiled into a view at runtime. Custom components may be injected into the template using special placeholder tags (i.e. tags where the tag name begins with ‘$’.

Supported Tags

• border - A container with layout=BorderLayout

• y - A container with layout=BoxLayout Y

• x - A container with layout=BoxLayout X

• flow - A container with layout=FlowLayout

• layered - A container with layout=LayeredLayout

• grid - A container with layout=GridLayout. Accepted attributes rows and cols

• table - A container with layout=TableLayout. Accepted attributes rows and cols. May have zero or more nested tags.

• label - A Label

• button - A button

Layout Variant Tags

BorderLayout and BoxLayout include some variant tags to customize their behaviour also:

• borderAbs, borderAbsolute - BorderLayout with center absolute behaviour. This is the same as ``

• borderTotalBelow - BorderLayout with Total Below center behaviour. This is the same as ``

• yBottomLast, ybl - BoxLayout with Y_BOTTOM_LAST setting.

• xNoGrow, xng - BoxLayout X with No Grow option. This is the same as ``

Supported Attributes

• uiid - The UIID of the component. I.e. Component#getUIID()

• id - The ID of the component so that it can be retrieved using #findById(java.lang.String)

• name - The name of the component (i.e. Component#getName()

• constraint - The layout constraint used for adding to the parent. Supports north, south, east, west, center, when parent is border

• rows - Used by grid only. Represents number of rows in grid or table.

• cols - Used by grid only. Represents number of columns in grid or table.

• behavior, behaviour - Used by Border Layout only. Specifies the center behaviour. Accepts values “scale”, “absolute”, and “totalBelow”.

• noGrow - Used by `` only. Specifies that BoxLayout should be X_AXIS_NO_GROW. Accepts values “true” and “false”.

• bottomLast - Used by `` only. Specifies that BoxLayout should use Y_AXIS_BOTTOM_LAST option. Accepts values “true” and “false”

Example XML Notation

`Form f = new Form("Test", new BorderLayout());
String tpl = ""
    + ""
    + ""
    + "";

f.setFormBottomPaddingEditingMode(true);
TextField searchField = new TextField();
searchField.addActionListener(e->{
   Log.p("Search field action performed");`);
Button submit = new Button("Submit");
submit.addActionListener(e->{
    Log.p("Button action performed");
});

UIFragment template = UIFragment.parseXML(tpl)
    .set("button", submit)
    .set("search", searchField);
f.add(BorderLayout.CENTER, template.getView());
f.show();
}

JSON Notation

When trying to express a UI structure inside a Java String, the XML notation may be a little bit verbose and cumbersome. For this reason, there is an alternative JSON-based notation that will allow you to express a UI structure more succinctly.

A JSON object (i.e. curly braces) denotes a Container. If this object includes properties corresponding to the constraints of BorderLayout (e.g. center, east, west, north, south, or overlay), then the container will use a BorderLayout, and the associated properties will represent its children with the appropriate constraint.

E.g.:

`{center:'Center Label', south:'South Content'`}

Will create a Container with labels in its BorderLayout#CENTER and BorderLayout#SOUTH positions.

To make things even more succinct, it supports single-character property keys for the BorderLayout constraint values. E.g. The following is equivalent to the previous example:

`{c:'Center Label', s:'South Content'`}

**Other Layouts**:


- **Flow Layout** - `{flow:[...]`}

- **Grid Layout** - `{grid:[...], cols:3, rows:2`}

- **Box Layout X** - `{x:[...]`}

- **Box Layout Y** - `{y:[...]`}

- **Layered Layout** - `{layered:[...]`}

- **Table Layout** - `{table:[['A1', 'B1', 'C1'], ['A2', 'B2', 'C2'], ...]`}

**Layout Variants**

BoxLayout and BorderLayout include variant shorthands to customize their behaviour.


- **xNoGrow, xng** - Same as `{x:[...], noGrow:true`}

- **yBottomLast, ybl** - Same as `{y:[...], bottomLast:true`}

- **centerAbsolute, centerAbs, ca** - Same as `{center:[...], behavior:absolute`}

- **centerTotalBelow, ctb** - Same as `{center:[...], behavior:totalBelow`}

**Embedding Placeholders/Parameters**

The notation for embedding placeholder components (which must be injected via `com.codename1.ui.Component)`),
is similar to the XML equivalent.  Just place the parmeter name, prefixed with '$'.  E.g.

`$submitButton`

Example JSON Notation

`Component view = UIFragment.parseJSON("{n:['Hello', 'World', $checkbox], c:[y, {class:'MyTable', table:[['Username', $username], ['Password', $password]]`, {flow:['Some text'], align:center}], s:$submit}")
    .set("username", new TextField())
    .set("password", new TextField())
    .set("submit", new Button("Submit"))
    .set("checkbox", new CheckBox("Check Me"))
    .getView();
}