Configure a layout

The layout module works in tandem with user input fields. It gives more control over how the inputs are presented and grouped on screen.

In places that support it, you can provide a layoutConfig, an example is given below.

You might notice the field labels disappear once a layoutConfig is defined. That’s because they are not shown by default when using layoutConfig. Set extraOptions.showFieldLabel to true on each field to show the labels. Or set forceShowFieldLabel on the "field" or "other-fields" layout elements. 
{
    "layoutConfig": {
      "type": "basic",
      "elements": [
        {
          "type": "basic",
          "extraClasses": [
            "flow-flex-col"
          ],
          "elements": [
            {
              "name": "file",
              "type": "field"
            },
            {
              "name": "duration",
              "type": "field"
            }
          ]
        },
        {
          "name": "slots",
          "type": "field",
          "extraClasses": [
            "flow-flex-col"
          ]
        }
      ],
      "extraListClasses": [
        "flow-flex-row"
      ]
    }
}

Layout Elements

The layout is built up with layout elements.

field

The most basic element has type "field" and will render the user input field for which the name is provided in the "name" property:

{
  "type": "field",
  "name": "duration"
}

If the field that is being rendered has type COMPOUND, it can accept a layoutConfig of its own. This layoutConfig can be defined on the field config’s extraOptions.compound.layoutConfig, but it can also be defined on the field layout element as part of the main layout, as shown below.

{
  "type": "field",

  // in the example person is a COMPOUND field with
  // a personName and personRole field of its own
  "name": "person",

  // note that this layout should only reference fields
  // that are part of the COMPOUND person field
  "layoutConfig": {
      "type": "basic",
      "elements": [
          { "type": "field", "name": "personName" },
          { "type": "field", "name": "personRole" }
      ]
  }
}

When defined in both places, the layoutConfig of the layout element is preferred over the field config.

field-label

Renders the label of the user input field for which the name is provided in the "name" property. By default, a <label> html tag is used.

// this will render <label>Duration</label> if the duration
// field has label "Duration".
{
  "type": "field-label",
  "name": "duration"
}

field-with-label

For convenience, this translates into a basic layout element with two elements: a field-label and a field layout element.

extraFieldClasses will become the extraClasses on the field, and extraLabelClasses will become the extraClasses of the field-label.

{
  "type": "field-with-label",
  "extraFieldClasses": [
    "col-xs-7"
  ],
  "extraLabelClasses": [
    "col-xs-5",
    "control-label"
  ]
}

other-fields

This is a convenient layout element which will gather all fields that are not yet rendered elsewhere in the layout (and also don’t have hidden=true), and render them using a "field" layout element. This allows you to define layouts where not each field is placed explicitly.

The shortest layout possible would look like the snippet below, and it will render each field one after the other.

{
    "type": "other-fields"
}

You can pass the configuration of the "field" layout element in via the fieldLayoutElement property. The following example will show the field labels:

{
    "type": "other-fields",
    "fieldLayoutElement": {
        "forceShowFieldLabel": true
    }
}

You can also pick the layout element type which should be used to render each field (default "field"). Valid values are "field" or "field-with-label".

{
    "type": "other-fields",
    "fieldLayoutElement": {
        "type": "field-with-label"
    }
}

basic

Another element has type "basic". It will render a layout element for each element in its "elements" property.

{
  "type": "basic",
  "elements": [
    {
      "name": "file",
      "type": "field"
    },
    {
      "name": "duration",
      "type": "field"
    }
  ]
}

Note that the "elements" array can also contain another "basic" (or other) layout element, so more complex nesting is possible.

content

Renders some text or some other basic content.

Will not render child layout elements! If you need children, use the basic layout element with a tagName.

{
    "type": "content",
    "text": "This is cool"
}
{
    "tagName": "h4",
    "type": "content",
    "text": "Title"
}
{
    "type": "content",
    "icon": "icon-magic"
}
{
    "type": "content",
    "tagName": "a",
    "href": "https://www.limecraft.com",
    "text": "cool link"
}

Generic Layout Element properties

Each layout element has a few properties to tweak the layout and styling.

The scope column indicates for what layout element types the config property can be used.

Property Description Scope Example

extraClasses

These classes will be applied on the layout element

all

["deeppink"]

extraListClasses

These classes will be applied on the element representing the list of child layout elements

all

["orange"]

tagName

The tag to use for the layout element.

all

["h3"]

forceShowFieldLabel

Force showing the label. An alternative to setting extraOptions.showFieldLabel on each field. Mostly here to be backwards compatibility. It’s advised not to rely on it.

"field" and (through fieldLayoutElement) "other-fields"

true

Field labels

Showing the field labels can be enabled on the field config itsself via extraOptions.showFieldLabel. It is however also possible to force rendering it from the layout config. The following properties can be used on "field" layout elements, and through fieldLayoutElement on "other-fields" too.

Property Description Example

forceShowFieldLabel

Force showing the label. An alternative to setting extraOptions.showFieldLabel on each field.

true

forceFieldLabelClasses

The classes classes to apply on the element containing the label. This overwrites the field setting extraOptions.extraLabelClasses.

["flow-flex-grow-left"]

forceFieldValueClasses

The classes to apply on the element containing the value. This overwrites the field setting extraOptions.extraValueClasses.

["flow-flex-grow-left"]

'forceWrapperClasses'

The classes to apply on the element containing the field and value. This overwrites the field setting extraOptions.extraWrapperClasses.

["flow-flex-grow-left"]

Examples

List of labeled fields

At the time of writing, this is the default layout.

list of labeled fields 
{
    "type": "other-fields",
    "fieldLayoutElement": {
        "forceShowFieldLabel": true,
        "removeDefaultFormClasses": false
    }
}

Multiple columns

An example with two columns, by using flow-flex-col and flow-flex-row classes.

Layout with columns 
{
  "type": "basic",
  "elements": [
    {
      "name": "name",
      "type": "field",
      "extraClasses": [
        "flow-flex-col"
      ],
      "forceShowFieldLabel": true
    },
    {
      "type": "basic",
      "elements": [
        {
          "name": "role",
          "type": "field",
          "forceShowFieldLabel": true
        },
        {
          "name": "age",
          "type": "field",
          "forceShowFieldLabel": true
        }
      ],
      "extraClasses": [
        "flow-flex-col"
      ]
    }
  ],
  "extraListClasses": [
    "flow-flex-row"
  ]
}