Form group elements

A FormGroupElement represents a form control with an associated label and description texts. It helps with automatic styling of forms based on a general form layout.

Form groups elements wrap around other view elements and are represented as a <div> tag with the css class form-group.

Element and builder

The ViewElement implementation for a checkbox element is a FormGroupElement and has a corresponding FormGroupElementBuilder. A FormGroupElementBuilder can also be created via the BootstrapViewElements.bootstrap.builders#formGroup factory method.

FormGroupElement attributes

A FormGroupElement can easily be customized through a variety of attributes.

Attribute	Description
formLayout	Specifies the layout of the form group. A layout can specify a grid, a type and whether labels should be rendered.
required	Defines whether the form group should be marked as required.
detectFieldErrors	Whether the form group should look for field errors in the thymeleaf context.

Attribute

Description

formLayout

Specifies the layout of the form group. A layout can specify a grid, a type and whether labels should be rendered.

required

Defines whether the form group should be marked as required.

detectFieldErrors

Whether the form group should look for field errors in the thymeleaf context.

Thymeleaf model writer

The FormGroupElementModelWriter is responsible for writing a form group and its child elements to the Thymeleaf model. Depending on the configuration of the form group, additional markup or elements may be added.

Required: If a form group is required, an additional <sup class="required">*</sup> tag will be added to the label.
Connecting label & control: The FormGroupElementModelWriter will attempt to automatically link the label and control of the form group if the label has not yet specified a target.
Additional text elements: FormGroupElements support additional help, description and tooltip blocks. If these controls are present, they will be added at a specific position.

A tooltip will be added inside the label, the description block before the control and the help block after the control. These blocks will also be referenced by the control element via an aria-describedby attribute.
FormLayout: A FormLayout can be defined on the FormGroupElement to specify in which direction the containing elements should render.

If the form layout is of type INLINE, the label, help and description block will have an additional sr-only class added. Additionally, if no placeholder has been set on the control element, the label will be added as a placeholder.
Errors: If the form group should detect field errors, it will attempt to look up the property in the template context to check for binding errors. The property will be looked up by using the control name that is specified on the form control. Should any errors be present, the form group will be rendered in an error validation state.

Examples

Creating a form group

import static com.foreach.across.modules.bootstrapui.ui.factories.BootstrapViewElements.bootstrap;

bootstrap.builders.formGroup()
                   .build();

Label & Control

import static com.foreach.across.modules.bootstrapui.ui.factories.BootstrapViewElements.bootstrap;

bootstrap.builders
    .formGroup()
    .label( bootstrap.builders
                    .label( "Author" )
                    .add( IconSet.iconSet( FONT_AWESOME_BRANDS_ICON_SET ).icon( "apple" ) )
    )
    .control(
            bootstrap.builders
                    .textbox()
                    .controlName( "author-name" )
    )
    .build()

Configurable text elements

import static com.foreach.across.modules.bootstrapui.ui.factories.BootstrapViewElements.bootstrap;

bootstrap.builders
    .formGroup()
    .label( "Author" )
    .control( bootstrap.builders.textbox() )
    .tooltip( "This is a tooltip. I appear as a part of the label." )
    .descriptionBlock( "This is a description block. I come before the control and after the label." )
    .helpBlock( "This is a help block. I come after the control." )
    .build()

Child elements

import static com.foreach.across.modules.bootstrapui.ui.factories.BootstrapViewElements.bootstrap;

bootstrap.builders.formGroup()
     .label( "Author" )
     .control( bootstrap.builders.textbox() )
     .add( bootstrap.builders
                   .link()
                   .url( "https://google.com" )
                   .text( "Click here for more information" ) )
     .build()

Field errors

Given the following builder configuration for a form group that belongs to a form element.

import static com.foreach.across.modules.bootstrapui.ui.factories.BootstrapViewElements.bootstrap;

bootstrap.builders.formGroup()
     .label( "My number" )
     .tooltip( bootstrap.builders.tooltip().text( "another tooltip" ) )
     .required()
     .detectFieldErrors( true )
     .control(
             bootstrap.builders.textbox()
                               .controlName( "number" )
                               .text( "1" )
     ).build();

« File upload Form group Hidden field »