Forms

Overview

Data Hub forms are a fundamental part of the application, and the forms frameworks created makes form rendering, state population and error display easier and consistent.

Form generation

As with other parts of Data Hub the handling of forms relies on a number of nunjucks macros that take formatted data and transform it into rendered HTML.

In the case of forms this is more complex than collections or details screens as there many more stages and pieces of work that need to be carried out.

Describing form contents

At it's simplest, a form is a collection of fields, of different types, populated with values and with associated error details.

A collection of functions have been created that accept a form 'definition', it's values and errors. The form defition lists the fields to be displayed, including properties such as:

• Name
• Label
• Macroname
• Type
• Related setttings
• Option data for multi-select fields

These form definitions for an entity are stored in a file named 'macros.js' or as files below a folder named 'macros'. Each definition contains top level form related properties for things like if the form should use 'POST' or 'GET', any hidden field details and other things such as the text to use on the save button. The field defitions are contained in a 'children' property.

# Example form

const exampleEditForm = {
  method: 'post',
  buttonText: entityId ? 'Save and return' : 'Add entity',
  hiddenFields: {
    id: entityId,
  },
  children: [
    {
      macroName: 'TextField',
      name: 'name',
      label: 'Entity name',
    },
    {
      macroName: 'TextArea',
      name: 'description',
      label: 'Description',
      placeholder: 'Enter some text here',
    }
  ]
}

Typically you'll find that the labels for a form are held in a seperate file and a map function will be used after a form definition to pull the label into each child field. Also note that a central file of common field defitions has been created in a property named 'globalFields' in a top level 'macros.js' file. When adding fields to a form look here first, though be careful when using this for fields that require options to be loaded from the backend.

Field types

There is a wide range of fields, of which examples can be see in the component gallery. Each of the different form field types has a corresponding nunjucks macro located under src/templates/_macros/form. The field type is defined by using the 'macroName' property. In some cases additional properties are required for the field, more documentation for these can be found in the nunjucks macro file.

The major field types are:

• TextField A simple plain textfield.
• TextArea A simple
• DateFieldSet
• MultipleChoiceField
• Typeahead

Nesting field definitions

Some fields allow nested definitions, this means you can define one field type that may contain related children. The nested field types include:

• AddAnother The add another field allows 1 or more children fields to be defined and then an 'add' button is added to the markup. When the user presses 'add another' the fieldset is duplicated. This is useful for forms that require the user to select multiple values such as multiple advisers or multiple countries.

• Fieldset If a collection of fields needs to be logically created then fieldset uses a HTML fieldset, with a children property set to contain an array of fields within the fieldset and the label property used for the legend.

Other special considerations

There are some other field helpers that should need a special mention.

Conditional fields allow a field to be set to only display when another field has a given value, this is especially useful when used in combination with a multiple choice field set to yes or no. You can set the field of interest to only be shown when the value is set to yes or no. This behaviour is enabled via client side javascript, so changes to visibility happen in real time without a server call needed.

TBD: Find a good example of a conditional field.

How does the state get injected?

How are errors displayed

Handling form data

Routing patterns

Handling form post

Handling errors

Filter forms

Sort forms

Style variations