CLUSTER element

Use the CLUSTER element to lay out related information on a screen. Clusters generally show field and label pairs in a number of columns. Clusters can also include layout elements, such as other clusters and lists, for more complex layouts. Clusters attributes can render data from data sources, such as server interface property values, externalized string values, or page parameter values. Fields can accept data and sent it to other data targets, such as server interface properties, or page parameters.

Attributes

The CLUSTER element has the following attributes.

Table 1. Attributes of the CLUSTER element
Attribute Name	Required	Default	Description
`TITLE`	See note in description.		A reference to an externalized string that contains the title string for this cluster. Avoid redundant titles when you use clusters for layout only. Note: The `TITLE` attribute is required for collapsible clusters and optional otherwise.
`NUM_COLS`	See note in description.	`1`	Using a single column for forms is recommended. Multi-column forms are more prone to misinterpretation and interrupt the vertical momentum of moving down the form. However, it makes sense to place short and logically related fields on the same row, such as First name and Last name. For more information about building forms, see the IBM Carbon Design System v10. For content panels under 672 px, which is the Carbon Design System medium breakpoint, the cluster is responsive and breaks into a single column full-width layout. For content panels larger than 672 px, you can use `NUM_COLS`. `NUM_COLS` sets the number of columns to display in the cluster, where a cluster column includes both the label and the field. To maintain consistent grid layout, clusters with three columns are divided into four, but only three columns are displayed. Clusters with more than four columns are divided into 8, but only the specified number of columns is displayed. Although you can use other numbers of columns, use 1, 2, 4, and 8-column clusters when you want to fill all available horizontal space. Use multiple nested or sibling clusters to achieve layouts of varying column spans. Note: The `NUM_COLS` attribute is required when a cluster contains a field element that has the `ADDRESS_DATA` domain data type. The `NUM_COLS` attribute is optional for all other domain data types.
`TAB_ORDER`	No	`COLUMN`	The order to lay out elements in a multi-column cluster. The elements can be ordered by `ROW` or `COLUMN` (default). If a `CLUSTER` has `NUM_COLS` set to 2 or more and contains a mix of `LIST` and `FIELD` elements, the `TAB_ORDER` must be set to `ROW`.
`SHOW_LABELS`	No	`true`	Set to `true` (default) to show labels at the side of the field values or `false` to show no labels.
`LAYOUT_ORDER`	No	`LABEL` (for read-only fields only)	For clusters with input or editable fields, labels display over the fields according to IBM Carbon Design System guidelines. For clusters with read-only fields only, you can also use `LAYOUT_ORDER`. `LAYOUT_ORDER` sets whether labels display to the left or to the right of fields. Set the attribute value to `LABEL` to show labels to the left (default) or `FIELD` to show labels to the right. Labels and field values are laid out horizontally where the available space in the column is at least `8rem` wide for labels and `16rem` wide for field values. Where not enough space is available, values wrap under labels.
`WIDTH`	No		The percentage width of the containing area of the cluster. By default, this attribute is not set and a cluster fills 100% of its container up to the maximum width of the Carbon Grid. On extra large screens, the cluster might not always occupy 100% of the viewing area. The maximum width prevents columns that contain inputs and text from being too wide and having excessive white space. For more information about the Carbon Grid maximum width, see https://v10.carbondesignsystem.com/guidelines/2x-grid/implementation. If needed, you can override the Carbon Grid maximum width by setting this attribute to 100 to force the cluster to always occupy 100% of its container, regardless of screen size. If you want to set the cluster width to a size value other than 100% of its container, you can set this attribute to the correct percentage. The value that you set applies only to sizes over the medium breakpoint. Under the median breakpoint, the width is always 100%.
`STYLE`	No		The class name of the CSS style to associate with this cluster for formatting.
`DESCRIPTION`	No		A reference to an externalized string that provides more details about the cluster than the title alone. It is displayed under the title on the page.
`LABEL_WIDTH`	No		For clusters with input or editable fields, labels use 100% of the available width of the field, according to IBM Carbon Design System guidelines. For clusters with read-only fields, you can use LABEL_WIDTH. `LABEL_WIDTH` specifies the percentage of the width of a cluster column for the label. By default, labels display at least 8rem wide. The max-width of read-only cluster labels is 12rem. This attribute applies even if `SHOW_LABELS` is set to `false`. You can, for example, use action controls instead of text labels. You might want to control the width of these action control columns and you can do that by setting the `LABEL_WIDTH` attribute. The specified width is applied to every other column. Whether it starts with the first or second column depends on the `LAYOUT_ORDER` attribute. The `LABEL_WIDTH` attribute does not apply to code table hierarchy fields when `SHOW_LABELS` is set to `false`, or when the `FIELD` attribute `CONFIG` has a value of `CT_DISPLAY_LABELS`. For more information about code table hierarchies, see the `CONFIG` attribute in FIELD element.
`BEHAVIOR`	No	`EXPANDED`	Where suitable, configure clusters to be collapsible to avoid the extra visual noise and interaction complexity that clusters can add to screens. Avoid nesting collapsible clusters inside other collapsible clusters. Collapsible clusters can be initially expanded or collapsed on a page by setting the `EXPANDED` or collapsed `COLLAPSED` attributes. To remove the collapsible function from a cluster, set the attribute to `NONE`. This attribute is applicable only when the property `ENABLE_COLLAPSIBLE_CLUSTERS` is not set or is set to `true` in curam_config.xml. For more information, see General configuration. This feature is not supported on clusters that contain Charts, Evidence Review Widgets, Evidence Comparison Widgets, or Evidence Tab Container Widgets.
`SUMMARY`	No		A reference to an externalized string that contains the summary of this cluster. The `SUMMARY` attribute describes the purpose and structure of a cluster.
`SCROLL_HEIGHT`	No		Specifies the maximum height of a scrollable cluster in pixels.

Child elements

The CLUSTER element must contain one of the following elements; ACTION_SET, FIELD, WIDGET, CONTAINER, CLUSTER, or LIST.

Table 2. Child Elements of the CLUSTER Element
Element Name	Cardinality and Description
`CONDITION`	0..1. Affects whether the cluster is displayed.
`TITLE`	0..1. The `TITLE` element is displayed over the `CLUSTER`.
`DESCRIPTION`	0..1 The DESCRIPTION element element has the same behavior as the `DESCRIPTION` attribute but allows the description to be built up from a number of sources. If both are specified, the element takes precedence over the attribute.
`ACTION_SET`	0..1. The action set can contain `ACTION_CONTROL` elements of any type. The action controls are displayed over or under the entire cluster.
`FIELD`	0..n. The `FIELD`, `CONTAINER`, `WIDGET`, `CLUSTER`, and `LIST` elements can be freely intermingled.
`WIDGET`	0..n. The `FIELD`, `CONTAINER`, `WIDGET`, `CLUSTER`, and `LIST` elements can be freely intermingled.
`CONTAINER`	0..n. The `FIELD`, `CONTAINER`, `WIDGET`, `CLUSTER`, and `LIST` elements can be freely intermingled.
`CLUSTER`	0..n. The `FIELD`, `CONTAINER`, `WIDGET`, `CLUSTER`, and `LIST` elements can be freely intermingled.
`LIST`	0..n. The `FIELD`, `CONTAINER`, `WIDGET`, `CLUSTER`, and `LIST` elements can be freely intermingled.