Generic Component XML

LIVE DEMO

The component XML element enables you to create any UI component by specifying its fully qualified class name (FQN). Component properties are defined using nested property elements, similar to action configuration.

Usage Example

The simplest use case is defining a regular component instance directly in XML:

<component id="button" class="io.jmix.flowui.kit.component.button.JmixButton">
    <properties>
        <property name="text" value="Save"/>
        <property name="icon" value="ARCHIVE" type="ICON"/>
    </properties>
</component>

The framework instantiates the component class and applies the declared properties through matching setter methods. In this example, the text property maps to setText(), and the ICON property parser converts ARCHIVE to an icon instance for setIcon().

You can also subscribe to the generic component in the view controller the same way as for standard declarative components:

@Autowired
protected Notifications notifications;

@Subscribe(id = "button", subject = "clickListener")
public void onButtonClick(ClickEvent<JmixButton> event) {
    notifications.show("Saved!");
}

The same mechanism can be used for a custom component with setters that accept converted values:

<component id="testComponent" class="com.company.onboarding.component.TestComponent">
    <properties>
        <property name="stringsList" value="a b ,c"/>
        <property name="stringsSet" value="a b ,c"/>
        <property name="stringsArray" value="a b ,c"/>
        <property name="strings" value="a b ,c"/>
        <property name="dataContainer" value="productsDc" type="CONTAINER_REF"/>
    </properties>
</component>

In this example, the TestComponent class defines setters for stringsList, stringsSet, stringsArray, strings, and dataContainer. Jmix converts the string values from XML and resolves the productsDc data container before invoking the matching setters.

Property Configuration

  • The name attribute value is converted to a setter method name, for example:

    • text → setText()

    • dataLoader → setDataLoader()

  • The framework searches for a method with the matching name and a single input parameter to set the value.

    If multiple methods share the same name, there is no guarantee that the intended one will be used to set the value.

  • The found method’s input parameter type is used to convert the string value from the value attribute into the actual value.

    Built-in conversion supports String, Class, boolean and numeric types, enums, List, Set, and arrays. Varargs setters also work because they are handled as array parameters. Collection and array items are split by spaces or commas before conversion.

  • The type attribute indicates that string value must be converted by one of the pluggable PropertyParser beans:

    Type Parser Description

    ICON

    IconPropertyParser

    Converts a string to an Icon instance

    CONTAINER_REF

    DataContainerPropertyParser

    Resolves a data container by ID

    LOADER_REF

    DataLoaderPropertyParser

    Resolves a data loader by ID

Property Parsers

When string values cannot be directly converted using the parameter type, pluggable PropertyParser beans handle the transformation.

Currently, there are three implementations:

  • IconPropertyParser. Converts strings to Icon instances.

    • If the passed string contains : delimiter, a new Icon is created using the icon collection and icon name values.

    • Otherwise, the string is treated as a VaadinIcon constant name.

      Examples:

    • "PLUS" → VaadinIcon.PLUS icon.

    • "myicons:custom" → Icon from the custom collection "myicons" with the name "custom".

  • DataContainerPropertyParser. Returns a data container with the given ID from the corresponding view’s ViewData object.

  • DataLoaderPropertyParser. Returns a data loader with the given ID from the corresponding view’s ViewData object.