Loop layouts

This page discusses loop layouts. For an overview of Workshop embedding features, see the embedding overview page.

Loop layouts allow you to loop over an object set, displaying an embedded module for each object in the set by using that object as an input. Each embedded module in the loop layout functions independently from the other embedded module instances in the loop layout, with its own variable scope and layout state. You can use a loop layout for more control over the display of an object set than what is offered by other object set display widgets, such as the object table or object list. While other object set display widgets come with a fixed set of features, the loop layout allows any feature combination available in Workshop to be used for the display of each object in the object set.

Below is an example of a loop layout to create interactive ticket cards for each object in three object sets (one per column), to create a kanban style application. Each ticket card is an embedded module instance populated with an object from the object set provided to the column's loop layout. In this embedded module, full layout control is available, and the builder can configure exactly what to display, and what actions are available for each object, offering greater flexibility than what is offered by other object set display widgets.

Configuration

The Loop layout configuration allows a builder to select an object set to loop over, and a module to embed for each object in the selected object set, along with controls for sorting and paging style.

Object set to loop through

The first configuration made in a loop layout is the “object set to loop through” variable input. This object set will be looped through in the loop layout, with each object from this set used to display an instance of the child embedded module configured in the “module selection” step.

Sort

Property sorts may be applied to the object set being looped through to determine the order in which the objects will be displayed in the looped layout.

A custom sort may be achieved by returning a static object set with the desired sort order in the object set definition from a function backed object set variable.

For object sets of a single object type that are not static object sets, a primary key sort will be applied behind any user configured sorts to ensure a consistent ordering of objects. This may cause the loop layout to fail to display if the primary key is not sortable.

Paging style

• Limit: This paging style will display only a single page which displays up to the first X objects, where X is the value configured in the “Max items to display” configuration.
• Paged: This paging style will display pages of objects of size X, where X is the value configured in the “Max items per page” configuration. Loop layouts are currently limited to paging through the first ten thousand objects.

Display

• List: This display option will display the objects in a list. There are no additional configuration options.
• Grid: This display option will display the objects in a grid. Additionally, a max number of columns and min card width in pixels may be configured.

With either option, a consistent height for each row may be achieved by configuring an absolute or max height on the top level section in the selected child module.

Module selection

Loop layout module selection works similarly to embedded module widget module selection, requiring selection of a child module via the Compass resource selector; however, the selected module for a loop layout must have a module interface object set variable.

Interface variable for object from object set to loop through

In this configuration, a builder must select which module interface object set variable from the child module will be mapped to the objects from the "object set to loop through" variable. Refer to configuring the module interface for the selected module for more information.

If this variable value is changed in the child module, for instance through a “set variable value” event, unexpected behavior may occur.

Interface configuration

Other than the module interface variable input described above, loop layout variable mapping works the same way as the embedded module interface configuration for all other module interface variables.

Unlike the "object set to loop through" variable, these additional variables may be changed in the child module template. Each variable will be the same variable reference for each looped instance, allowing variable state to be shared across looped instances and the parent module.

Layout settings

Padding

This is the same padding configuration offered on other Workshop layouts. The configured padding will be applied around each instance of the embedded module in the loop layout.

Inner border style

If padding is applied to the loop layout, a border style may be selected which will be applied to each instance of the embedded module in the loop layout.

Sharing variables

The interface configuration in loop layouts allows variable values to be shared across loop layout embedded modules. This may be useful to share something like the state of a selected object. In this use case, each embedded module has the ability to have an event set the value of the shared "selected object" variable, which can then be used in the parent module.

Limitations

Loop layout paging limit

Loop layouts are currently limited to paging through the first ten thousand objects; this limit may change in the future.

Dynamic values

Any variable values that are dynamic per module instance must be derived from the passed in object. The passed in object is the only way that each module instance is differentiated. Additional variables may be passed to every module instance in the loop layout and these variables will be shared across instances.