The cellium_dsl module provides a Domain Specific Language (DSL) for defining UI layouts in Cellium.

How the DSL works

The DSL uses Erlang tuples to represent widgets and their properties. A UI layout is defined as a recursive structure of these tuples.

There are three main forms of DSL elements:

1. Standard leaf widgets: {Tag, Props}
   • Example: {button, [{id, my_button}, {label, "Click Me"}]}
2. Widgets with a primary value or containers: {Tag, Props, Arg3}
   • For containers like vbox or hbox, Arg3 is a list of child DSL elements.
   • For widgets like button or text, Arg3 is the primary value (e.g., label string).
3. Custom widgets: {custom, Module, Props}
   • Allows using a custom module that implements a new(Id) function.

Recursive State Handling

The DSL transformation is state-aware. When calling from_dsl/2, you provide a Model which may contain a widget_states map.

During the recursive traversal of the DSL:

1. An Id is determined for each widget (either from Props or auto-generated).
2. The widget is created.
3. If the Model contains state for that Id, it is "injected" into the widget's internal map using inject_state/3. This allows the DSL to preserve UI state across re-renders.

Sizing and Expansion

The DSL handles layout properties that control how widgets occupy space:

• width: Sets the fixed width of a widget.
• height or size: Sets the fixed height (or primary dimension) of a widget.
• expand: Indicates if a widget should grow to fill available space in its parent container.
• Constraints: Fixed-size widgets should not exceed the available dimensions of their parent container.
• Defaults: If neither a fixed size nor expand is specified, the DSL automatically applies a default {size, 1}.

Special Cases

Certain tags have specialized behavior in the DSL:

Containers (vbox, hbox, box, frame, dialog)

These tags use the third element of the tuple as a list of children.

Tabs (tabs)

The tabs widget only renders the child corresponding to the active_tab property.

Radiogroup (radiogroup)

The radiogroup tag uses the third element of the tuple as the list of options.

Dropdown (select)

The select tag represents a dropdown widget. It can take options as the third element or in the Props list.

Leaf Widgets with Primary Values

Tags like header, text, button, etc., can take their primary display value as the third element for brevity.