Creating and using UI components

What are UI components ?

The goal of a UI component is to isolate a set of UI elements that work together as a feature. After it has been defined, a UI component can be used in any UI view or any UI component. It is the UI equivalent of creating a C# utility class that is used by multiple other classes.

UI components are very similar to UI views. They have fields, computeds, methods, event rules and can display UI elements using a UI template. However, they are not dependent on a Datasource. Instead, like C# methods, they receive data through parameters. They can also feature content slots that can be used to customize what they will display when they are called.

Using a UI component

UI components can be added to the UI template of UI views and UI components using tags corresponding to their names.

Warning

UI component names are in kebab case when used in a UI template.

<vertical-layout>
    <text>Using a UI component</text>

    <!-- This will display the UserUIComponent here -->
    <user-ui-component />
</vertical-layout>

When a component has parameters, they can be passed as attributes. The name of the attributes must match the name of the parameters.

Warning

UI component parameters names are in kebab case when used in a UI template.

<vertical-layout>
    <text>Using a UI component</text>

    <!-- This will display the UserUIComponent here -->
    <user-ui-component name="@Fields.Name" age="@Fields.Age" />
</vertical-layout>

Note

Bindable properties (@Title, @Properties, @Fields, ...) from the UI view or UI component can be used as parameters passed to the called UI component.

Accessing the view model of parent UI views

As seen above, in order to be reusable anywhere, a UI component is not directly dependant on a Datasource and uses parameters to get data from the element that calls it.

However, a UI component can access by code to the view model, and therefore the data, of its parent UI views.
This simplifies the creation of more specialized UI components that can directly read values from a UI view data source.

Warning

Always keep in mind that when doing so, the UI component becomes way less reusable as it could generate errors if used in UI views with a data source that contains different properties that the ones the UI component expects to find.

GetParentViewModel method

This method returns the view model of the UI view using the UI component. This works even when the UI component is nested inside another UI component.
It is possible to get a typed view model using the generic version of the method.

GetMainViewModel method

This method is very similar to GetParentViewModel but it returns the view model of the topmost UI view of the view in which the UI component is used.
It also has a generic version to get a typed view model.