Form

The Form component (forms) embeds a Markel Forms instance within the page. It reads structured form configuration data from the Layout Service response — including field definitions, metadata, session IDs, and anti-forgery tokens — serializes it to JSON, and initialises the markelForms.init() JavaScript client which renders the form dynamically on the front end.

Unlike most BSTools5 components, Form does not use a standard datasource template (Helium/Beryllium). Instead, the rendering reads its data from Sitecore Forms items that define the form structure, field types, validation rules, and submission actions. The component also supports optional Google Address Autocomplete integration via an API key configured in application settings.

Examples

Live Example

Below is a live forms rendering. The component reads its form definition from the Sitecore Forms datasource, serializes the field structure to JSON, and passes it to markelForms.init() on the client. The form rendered below includes standard field types (text inputs, dropdowns, checkboxes) along with built-in validation and submission handling. Note that the form requires a valid Form Item ID datasource — without one, the container div will render empty.

Usage Notes

Notes

  • The Form component does not use a standard datasource template (Helium/Beryllium). Its datasource is a Sitecore Forms item that defines the entire form structure including field types, validation rules, conditional logic, and submission actions.
  • The rendering injects two scripts into the BodyBottom section: /assets/markel-forms.js (the shared forms library) and a per-instance initialisation call to markelForms.init(apikey, "", googlekey, null, jsonData, id).
  • The API Key used in the init call comes from SitecoreOptions.ApiKey and authenticates the form submission against the Layout Service.
  • The optional Google Address Autocomplete API Key is read from BSTools5:GoogleAddressAutocompleteApiKey in application configuration. When provided, address fields in the form will offer Google Places autocomplete.
  • The component serializes the entire form definition (fields, metadata, session ID, anti-forgery token, page item ID, context item ID) via Json.Serialize(ReadFields<Form>()) and passes the resulting JSON directly into the client-side initialiser.
  • Each form instance renders inside a unique <div id="{htmlId}"> container. The HTML ID is derived from the rendering’s unique identifier so multiple forms can coexist on the same page.
  • In Experience Editor, an <edit-label> is shown reminding authors they may need to save the page to see the form render correctly.
  • Form validation, multi-step navigation, and conditional field visibility are handled entirely by the markel-forms.js client library — no server-side round trips occur after initial load.

Control Properties

Control Properties

Rendering Parameters

ParameterTypeDescription
HeadingSizeDroplinkControls the heading level (h1–h6) used for the section title when the form is wrapped in a titled grid.
TextAlignmentDroplinkSets the text alignment class for the form container.
HideTitleHeadingCheckboxWhen checked, the section title above the form is visually hidden (sr-only).
Small / Medium / LargeDroplinkBootstrap column width at each breakpoint for the form’s grid column.
OffsetSmall / OffsetMedium / OffsetLargeDroplinkColumn offset at each breakpoint.
PaddingTop / PaddingBottom / PaddingStart / PaddingEndDroplinkSpacing utilities applied to the form column.
AddClassSingle-Line TextAdditional CSS class(es) appended to the column wrapper for custom styling.

Datasource Fields (Form Model)

FieldTypeDescription
htmlPrefixStringOptional prefix applied to all rendered field HTML IDs to avoid collisions when multiple forms are on the same page.
formSessionIdObjectIdentifies the current form session for multi-step forms and anti-replay protection.
formItemIdObjectThe Sitecore item ID of the Forms definition item that drives the form’s structure.
pageItemIdObjectThe item ID of the hosting page, used for contextual submission routing.
antiForgeryTokenObjectServer-generated token embedded in the form for CSRF protection on submission.
metadataObjectAdditional form metadata (tracking, analytics context, form version info).
fieldsList<Field>The ordered collection of form field definitions including type, label, validation rules, conditions, and default values.
contextItemIdStringThe context item ID passed to submit actions for item-aware processing.

Application Configuration

SettingSourceDescription
SitecoreOptions:ApiKeyappsettings / envThe Sitecore API key used to authenticate form submissions against the Layout Service endpoint.
BSTools5:GoogleAddressAutocompleteApiKeyappsettings / envGoogle Places API key enabling address autocomplete on supported form fields. Optional — when empty, autocomplete is disabled.

Template properties

Control properties