Fieldset

A fieldset property is a single property that represents a group of other properties. Usually this grouping is also visible on the user interface due to different styling.

A fieldset in this context is not the same as an HTML fieldset element. Fieldsets can be rendered in many different ways, a HTML fieldset is one of the rendering options.

Creating a fieldset property

You can render any property as a fieldset by setting the BootstrapUiElements.FIELDSET as the viewElementType for the relevant rendering mode (usually FORM_WRITE and FORM_READ).

Properties mapped to an @Embedded type will automatically be rendered as a fieldset and do not need the viewElementType set.

Fieldset members

Because a fieldset is a collection of other properties, you will need to specify which properties make up the fieldset. Specifying the properties of fieldset is done by setting the EntityAttributes.FIELDSET_PROPERTY_SELECTOR to a valid EntityPropertySelector.

If you do not specify a property selector, all child properties will be selected by default. For example: if your fieldset property is address, the default selector will be address.*.

Example: creating a custom fieldset property

entities.withType( WebPage.class )
        .createOrUpdateFormView( fvb -> fvb
                .properties( props -> props
                        .property( "url-settings" )
                        .displayName( "URL settings" )
                        .viewElementType( ViewElementMode.FORM_WRITE, BootstrapUiElements.FIELDSET ) (1)
                        .attribute(
                                EntityAttributes.FIELDSET_PROPERTY_SELECTOR, (2)
                                EntityPropertySelector.of( "url", "urlGenerated" )
                        )
                )
                .showProperties( "*", "url-settings", "~url", "~urlGenerated" ) (3)
        )

1	Create a new property `url-settings` that renders as a fieldset on a form. Create the property directly on the form view, for layouting purposes.
2	Select existing properties `url` and `urlGenerated` as members of the fieldset.
3	Add `url-settings` to the form view, but remove `url` and `urlGenerated` as standalone controls.

Fieldset rendering

A fieldset property is rendered using a ViewElementFieldset object. A ViewElementFieldset holds 4 containers:

title: Holds elements that make up the title of the fieldset. This corresponds to the property name and optional tooltip.
header: Holds elements that should be rendered before the actual members of the fieldset. Usually a description message code that has been configured for the property.
body: Holds the actual members of the fieldset. These are usually other form groups of the individual properties.
footer: Holds elements that should be rendered after the actual members of the fieldset. Usually a help message code that has been configured for the property.

How the actual properties are rendered is determined by the template attribute. This is a Function that takes the ViewElementFieldset as input parameter, and returns a single ViewElement that should be rendered.

If no custom template has been configured, the output will be an HTML fieldset element.

Configuring a custom template

A custom template for a fieldset property can be set as a ViewElementFieldset.TEMPLATE attribute on the property descriptor.

.properties( props -> props
        .property( "url-settings" )
        ...
        .attribute(
                ViewElementFieldset.TEMPLATE,
                ViewElementFieldset.template( fieldset -> {
                    // only render the body of the fieldset but wrap it in a div
                    NodeViewElement membersOnly = new NodeViewElement( "div" );
                    membersOnly.addCssClass( "members-only" );
                    membersOnly.addChild( fieldset.getBody() );
                    return membersOnly;
                } );
        )
)

Default templates

A number of default template functions are available for building layouts:

Template Example styling

Template	Example styling
Render fieldset as HTML `fieldset` element. `ViewElementFieldset.TEMPLATE_FIELDSET`
Render fieldset as `section` element with heading (`h1`, `h2`, `h3`). `ViewElementFieldset.TEMPLATE_SECTION_H1` `ViewElementFieldset.TEMPLATE_SECTION_H2` `ViewElementFieldset.TEMPLATE_SECTION_H3` `ViewElementFieldset.structureTemplate(…)`
Render fieldset as Bootstrap panel. `ViewElementFieldset.TEMPLATE_PANEL_DEFAULT` `ViewElementFieldset.TEMPLATE_PANEL_PRIMARY` `ViewElementFieldset.TEMPLATE_PANEL_INFO` `ViewElementFieldset.TEMPLATE_PANEL_SUCCESS` `ViewElementFieldset.TEMPLATE_PANEL_WARNING` `ViewElementFieldset.TEMPLATE_PANEL_DANGER` `ViewElementFieldset.panelTemplate(…)`
Render only the members of the fieldset. `ViewElementFieldset.TEMPLATE_BODY_ONLY`

Render fieldset as HTML fieldset element.

ViewElementFieldset.TEMPLATE_FIELDSET

Render fieldset as section element with heading (h1, h2, h3).

ViewElementFieldset.TEMPLATE_SECTION_H1 ViewElementFieldset.TEMPLATE_SECTION_H2 ViewElementFieldset.TEMPLATE_SECTION_H3

ViewElementFieldset.structureTemplate(…)

Render fieldset as Bootstrap panel.

ViewElementFieldset.TEMPLATE_PANEL_DEFAULT ViewElementFieldset.TEMPLATE_PANEL_PRIMARY ViewElementFieldset.TEMPLATE_PANEL_INFO ViewElementFieldset.TEMPLATE_PANEL_SUCCESS ViewElementFieldset.TEMPLATE_PANEL_WARNING ViewElementFieldset.TEMPLATE_PANEL_DANGER

ViewElementFieldset.panelTemplate(…)

Render only the members of the fieldset.

ViewElementFieldset.TEMPLATE_BODY_ONLY

CSS styling

The default templates add CSS classes to the markup identifying the different content elements. See the generated markup or javadoc for ViewElementFieldset for all details.