Table of Contents

Layout directives

Layout directives are special attributes which can be used on template nodes in order to apply a specific layout behavior.

Width

Sets the width of the element.

Directive name : layout:width

Values :

Value Effect
n Sets the width of the element to n pixels (n is an integer).
fill Adapts its width to fill the remaining horizontal space of its parent.
auto Adapts its width to its content.

Example :

<form-field property-name="CustomerName" layout:width="25" />

In this example, the rendered form-field element should have a width of 25px.

Min-Width

Sets the minimum width of the element.

Directive name : layout:min-width

Values :

Value Effect
n Set the minimum width of the element to n pixels (n is an integer).

Example :

<form-field property-name="CustomerName" layout:min-width="25" />

In this example, the rendered form-field element should have at least a width of 25px.

Max-Width

Sets the maximum width of the element.

Directive name : layout:max-width

Values :

Value Effect
n Set the maximum width of the element to n pixels (n is an integer).

Example :

<form-field property-name="CustomerName" layout:max-width="10" />

In this example, the rendered form-field element should have a maximum width of 10px.

Height

Sets the height of the element.

Directive name : layout:height

Values :

Value Effect
n Sets the height of the element to n pixels (n is an integer).
fill Adapts its height to fill the remaining vertical space of its parent.
auto Adapts its height to its content.

Example :

<form-field property-name="CustomerName" layout:height="25" />

In this example, the rendered form-field element should have a height of 25px.

Note

If the element height is set to fill and the element preferred size (i.g., the sum of all its children minimum size) is greater than the available space, a vertical scroll will be available.

Warning

If the element height is set to fill and its parent height is also set to fill, you should also add the layout:min-height directive on the element to be sure that its content will not be shrunk if there is not enough available space.

Min-Height

Sets the minimum height of the element.

Directive name : layout:min-height

Values :

Value Effect
n Set the minimum height of the element to n pixels (n is an integer).

Example :

<form-field property-name="CustomerName" layout:min-height="25" />

In this example, the rendered form-field element should have at least a height of 25px.

Max-Height

Sets the maximum height of the element.

Directive name : layout:max-height

Values :

Value Effect
n Set the maximum height of the element to n pixels (n is an integer).

Example :

<form-field property-name="CustomerName" layout:max-height="10" />

In this example, the rendered form-field element should have a maximum height of 10px.

Margin

Sets the margin of the element.

Directive name : layout:margin

Values : none, small, medium, large, extralarge

If you use one value (ex: layout:margin="large"), margin will be set according to this value on all sides of the element.

If you want to specify each side, you have to use a four values string separated with space (ex: layout:margin="large none small none") to set respectively top, right, bottom then left sides values.

Example :

<form-field property-name="CustomerName" layout:margin="medium" />

In this example, the rendered form-field element should have medium margin on all sides.

<form-field property-name="CustomerName" layout:margin="large none small none" />

In this example, the rendered form-field element should have a large margin on top side, a small margin on bottom side, and no margin for the other sides.

Padding

Sets the padding of the element.

Directive name : layout:padding

Values : none, small, medium, large, extralarge

If you use one value (ex: layout:padding="large"), padding will be set according to this value on all sides of the element.

If you want to specify each side, you have to use a four values string separated with space (ex: layout:padding="large none small none") to set respectively top, right, bottom then left sides values.

Example :

<form-field property-name="CustomerName" layout:padding="large" />

In this example, the rendered form-field element should have large padding on all sides.

<form-field property-name="CustomerName" layout:padding="large none small none" />

In this example, the rendered form-field element should have a large padding on top side, a small padding on bottom side, and no padding for the other sides.

Align self horizontal

Specifies the element's horizontal alignment if its parent is a vertical or horizontal layout.

Directive name : layout:align-self-horizontal

Values :

  • left : The element horizontally aligns to the left boundary of its parent (default).
  • right : The element horizontally aligns to the right boundary of its parent.
  • center : The element horizontally aligns at the center of its parent.
  • stretch : The element stretches horizontally to match its parent's width.
  • space-between : Distribute elements evenly. The first element is on the left boundary of its parent, last item on the right. Space separates each element.
Warning

In the large majority of cases, horizontal alignment must be set on the parent <vertical-layout> or <horizontal-layout>. The layout:align-self-horizontal directive must only be used in the very rare cases where one specific element inside a <vertical-layout> or <horizontal-layout> must be aligned in a different way than its siblings.

Example :

<group-box>
  <form-field property-name="CustomerName" />
  <form-field property-name="Address" layout:align-self-horizontal="right" />
  <form-field property-name="ZipCode" layout:align-self-horizontal="@Fields.ZipAlign" />
</group-box>

In this example, the CustomerName form field should stay left aligned whereas the Address form field should align to the right of the group box. The ZipCode form field should also align according to the ZipAlign field value.

Align self vertical

Specifies the element's vertical alignment if its parent is a vertical or horizontal layout.

Directive name : layout:align-self-vertical

Values :

  • top : The element vertically aligns to the top boundary of its parent (default).
  • bottom : The element vertically aligns to the bottom boundary of its parent.
  • center : The element vertically aligns at the center of its parent.
  • stretch : The element stretches vertically to match its parent's height.
Warning

In the large majority of cases, vertical alignment must be set on the parent <vertical-layout> or <horizontal-layout>. The layout:align-self-vertical directive must only be used in the very rare cases where one specific element inside a <vertical-layout> or <horizontal-layout> must be aligned in a different way than its siblings.

Example :

<horizontal-layout>
  <form-field property-name="CustomerName" />
  <form-field property-name="Address" layout:align-self-vertical="bottom" />
  <form-field property-name="ZipCode" layout:align-self-vertical="@Fields.ZipAlign" />
</horizontal-layout>

In this example, the CustomerName form field should stay top aligned whereas the Address form field should align to the bottom of the horizontal layout. The ZipCode form field should also align according to the ZipAlign field value.

Visible

Specifies the element's visibility.

Unlike the <if> node, the element will be mounted. If the visibility of the element can change frequently, it is better to use this directive instead of the <if> node for better performance.

This directive is equivalent to CSS display: none / display: block. When set to false, the element is completely removed from the layout and does not take up any space.

Directive name : layout:visible

Values :

  • true : The element is visible.
  • false : The element is hidden and removed from the layout (equivalent to CSS display: none).

Example :

<horizontal-layout layout:visible="false">
  <form-field property-name="CustomerName" />
  <form-field property-name="Address" />
  <form-field property-name="ZipCode" />
</horizontal-layout>

In this example, the horizontal layout is hidden and does not take up any space in the layout.

Visibility

Specifies the element's visibility behavior.

This directive provides fine-grained control over element visibility and layout behavior, offering three distinct modes.

Directive name : layout:visibility

Values :

  • visible : The element is visible and occupies space in the layout (default).
  • hidden : The element is invisible but still occupies space in the layout (equivalent to CSS visibility: hidden).
  • collapsed : The element is invisible and does not occupy space in the layout (equivalent to CSS display: none).

Example :

<horizontal-layout>
  <form-field property-name="CustomerName" />
  <form-field property-name="Address" layout:visibility="hidden" />
  <form-field property-name="ZipCode" layout:visibility="collapsed" />
  <form-field property-name="Phone" layout:visibility="@Fields.PhoneVisibility" />
</horizontal-layout>

In this example:

  • CustomerName is visible (default behavior)
  • Address is hidden but still takes up space in the horizontal layout, creating a gap
  • ZipCode is collapsed and does not take up any space in the layout
  • Phone visibility is determined by the PhoneVisibility field value
Note

Relationship with layout:visible directive:

  • layout:visible="false" is equivalent to layout:visibility="collapsed"
  • layout:visible="true" is equivalent to layout:visibility="visible"

Use layout:visibility when you need the three-state behavior, or layout:visible for simple show/hide scenarios.

Warning

Do not use both layout:visible and layout:visibility on the same element. Using both directives simultaneously may result in unpredictable behavior. Choose one directive based on your needs.

Lazy visible

Specifies whether the element should be mounted only when it becomes visible for the first time.

Use this directive when the element is expensive to initialize and may stay hidden for a while. Unlike layout:visible, the element is not mounted until the value becomes true.

After the element has been mounted once, subsequent visibility changes behave like layout:visible: the element stays mounted and is shown or hidden without being recreated.

Directive name : layout:lazy-visible

Values :

  • true : The element is mounted and visible.
  • false : The element is not mounted yet. If it has already been mounted once, it is hidden and removed from the layout.

Example :

<vertical-layout layout:lazy-visible="@Fields.ShowAdvancedSection">
  <form-field property-name="Address" />
  <form-field property-name="ZipCode" />
</vertical-layout>

In this example, the advanced section is not mounted until ShowAdvancedSection becomes true for the first time. After that first display, the section remains mounted and is only shown or hidden according to the field value.

Warning

layout:lazy-visible is not supported on elements rendered inside a repeat node. The directive is ignored in that context. Use layout:visible, layout:visibility, or <if> depending on whether you need toggling or conditional creation.

Note

Relationship with other visibility mechanisms:

  • Use layout:lazy-visible when initial rendering should be deferred until first display.
  • Use layout:visible or layout:visibility when the element should always be mounted and only toggled in the layout.
  • Use the <if> node when the element must be created and destroyed each time the condition changes.