Controls

Controls are the visual representation of parts of forms, usually associated with form fields.

They are identified by name which can include a namespace (colon separated as in ae:my-example).

Controls are documents of type control-form and consist of a template, style, and controller script.

When a field is defined in a form and no explicit control name is specified, the control name is derived from the field type. For example, a field of type select will use the control select.

Usage

Controls are most often used inside the form definition (which is defined as FormDown). The control name is put into a styling directive in front of a fields label or fields definition.

Styling directives are enclosed in curly braces {} and can contain multiple key-value pairs separated by |. The key-value pairs are separated by =. The key is the name of the parameter and the value is the value of the parameter. If the value contains spaces, it must be enclosed in quotes. Multiple styling directives can be put right after each other.

If the first key is not followed by a =, the value is assumed to be either a built-in styling tag or the control name to use.

// A simple text field. This will use the control `text`
[Name][name]

// A number field. This will use the control `number`
[Age][age]
[age]: number

// The `hidden` directive is built-in and will hide the field. It is part of a small group of built-in directives.
{hidden} 
[Height][height]

// Render any occurrence of `height` as a number field with a unit of cm. This will use the control `number`.
// The only exception is any label that has explicitly overridden the control.
[height]: number <unit=cm>

// A standalone control. This will use the control custom-control

// Rendering a field with a different control. This will use the control my:custom-control where my must match the // namespace of the control and custom-control is the name of the control. {my:custom-control another-param="value"} [Name][name]

Built-In Styling Directives

The following built-in styling directives are available:

• hidden and hide: Hides the field.
• show: Shows the field (only makes sense in combination with if).
• readonly: Makes the field read-only.
• editable: Makes the field editable (only makes sense in combination with if).

The can be used with if to conditionally show or hide fields.

[Show Field][showField]
[showField]: Switch

// A field that is only shown if the field `showField` is true
{show if showField}
[Another Field][anotherField]

[Show other Field][showOtherField]
[showOtherField]: Select
  - FIRST: First
  - SECOND: Second

// A field that is only shown if the field `showOtherField` is `FIRST`
{show if showOtherField=='FIRST'}
[Yet Another Field][yetAnotherField]

Lookup Rules

As controls are identified by name, the lookup rules are are more complex than for layouts, but similar to designs.

Controls can be limited as to which types of fields they support, which cardinality, or standalone mode. These are checked when a control matching the namespace and name is found.

The search inside control folders are always sorted by created.at date, so in case of multiple controls with the same name, the one created first is used.

The lookup rules are as follows:

1. If the form of the document being rendered has a child document of type control-form with matching name (and namespace), then that document is used as the control.
2. With the Form of the document as a starting point, we look for a folder on each level to each successive parent with the type control-folder and look for a child document of type control-form matching the controls namespace and name.
   1. If the current ancestor we investigate is a form-folder, we look through any referenced control-folder from the styling section of the folder.
   2. If the current ancestor we investigate is an application-form, we look through any referenced control-folder from the styling section of the application.
   3. If we reached the root we look through any referenced control-folder from the styling section of root.
3. Then we lookup the control in the System Control folder (controls-folder) of the system folder
4. If there is nothing found still we ignore the name of the control and use the default control for the field type from the default folder in the system control folder

Lookup Graph

This flowchart visually represents the lookup rules for controls.

flowchart TB__NEWLINE__ start("Look for control with namespace and name") --> lookForMatchingChild("Check for matching 'control-form' as child of the document's form")__NEWLINE__ lookForMatchingChild -->|Found| useControl__NEWLINE__ lookForMatchingChild -->|Not Found| checkNextAncestor__NEWLINE__ checkNextAncestor("Look in next ancestor.") --> checkType("Check type of current ancestor")__NEWLINE__ checkType -->|form-folder| checkInStylingSection__NEWLINE__ checkType -->|application-form| checkInStylingSection__NEWLINE__ checkType -->|root| checkInStylingSection__NEWLINE__ checkType -->|unknown| checkNextAncestor__NEWLINE__ checkType -->|none| lookInSystemControlFolder__NEWLINE__ checkInStylingSection(Look at all 'control-folder's from styling section) --> |Found| useControl__NEWLINE__ checkInStylingSection --> |Not Found| checkNextAncestor__NEWLINE__ lookInSystemControlFolder("Look in system control folder") --> |Found| useControl__NEWLINE__ lookInSystemControlFolder("Look in system control folder") --> |Not Found| lookInDefaultControls__NEWLINE__ lookInDefaultControls("Look in `default` folder under the system controls folder") -->| Found| useControl__NEWLINE__ lookInDefaultControls -->|Not Found| nonFound("End: No control found")__NEWLINE__ useControl --> endControlFound("End: Control Found")__NEWLINE__ endControlFound("End: Control Found")