# Class UIFragment

java.lang.Object
com.codename1.ui.UIFragment

public final class UIFragment extends Object

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();
    }

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `UIFragment.ComponentFactory`
  A factory for converting XML elements to Components.
  `static class`
  `UIFragment.DefaultComponentFactory`
  Default component factory that is used in templates.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Component`
  `findById(String id)`
  Gets a component in the template by its ID.
  `UIFragment.ComponentFactory`
  `getFactory()`
  Gets the component factory that is currently set for this fragment.
  `Container`
  `getView()`
  Gets the view that is generated by this template.
  `static UIFragment`
  `parseJSON(String json)`
  Parses a JSON string into a template.
  `static UIFragment`
  `parseXML(InputStream input)`
  Parses input stream of XML into a Template
  `static UIFragment`
  `parseXML(String xml)`
  Parses XML string into a Template
  `UIFragment`
  `set(String paramName, Component param)`
  Sets a parameter component in this template.
  `UIFragment`
  `setFactory(UIFragment.ComponentFactory factory)`
  Sets the component factory to be used.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### parseXML

    public static UIFragment parseXML(InputStream input)

    Parses input stream of XML into a Template

    ###### Parameters

    - `input`: InputStream with XML content to parse

    ###### Returns

    The corresponding template, or a RuntimeException if parsing failed.

  - ### parseXML

    public static UIFragment parseXML(String xml)

    Parses XML string into a Template

    ###### Parameters

    - `xml`: XML string describing a UI.

    ###### Returns

    The corresponding template, or a RuntimeException if parsing failed.

  - ### parseJSON

    public static UIFragment parseJSON(String json)

    Parses a JSON string into a template.

    ###### Parameters

    - `json`: A JSON string representing a UI hierarchy.

    ###### Throws

    - `IOException`

  - ### getView

    public Container getView()
    Gets the view that is generated by this template.

  - ### set

    public UIFragment set(String paramName, Component param)

    Sets a parameter component in this template. Templates that include "parameter" tags will inject these parameters into the resulting view.

    ###### Parameters

    - `paramName`: The name of the parameter.

    - `param`: The component to inject into the template.

    ###### Returns

    Self for chaining.

  - ### findById

    public Component findById(String id)

    Gets a component in the template by its ID.

    ###### Parameters

    - `id`: The ID of the component.

    ###### Returns

    The component with matching ID.

  - ### getFactory

    public UIFragment.ComponentFactory getFactory()

    Gets the component factory that is currently set for this fragment.

    ###### Returns

    the factory

  - ### setFactory

    public UIFragment setFactory(UIFragment.ComponentFactory factory)

    Sets the component factory to be used.

    ###### Parameters

    - `factory`: the factory to set

    ###### Returns

    Self for chaining