Hub and Spoke Task List Forms

These example snippets will get you started building a hub and spoke task list form. We've added them to the site as community content, so feel free to change or develop them in any way you like. If you come up with any new functionality or improvements, add them back into the community using the upload form.

What is a task list form?

A task list (or hub and spoke) form presents a list of pages and sections up front, so the person filling it out can see how long the form is and the sort of information they'll be expected to provide.

The GOV.UK Design System includes them as a design pattern: https://design-system.service.gov.uk/patterns/task-list-pages/ (opens new window). You can also find a working example related to this page.

In the example we've built, the first section of the form is active and ready to fill out, and each section in the list only unlocks once all of the pages in the previous section have been completed. Pages within a section can be completed in any order. Pages that have been completed can be returned to and edited.

If sections have the same name, they will be grouped together, and become active at the same time.

Import the form group

In the downloads area you'll find a form blueprint and a set of snippets. These have been designed so that they shouldn't need to be edited, and can be used to build a task list form without having to do a great deal of scripting work yourself. The zip file also includes a copy of the example form on this page.

Extract the zip file, then import the group in the usual way by right-clicking on an existing group and choosing "Import forms..."

Version 2
In March 2024 we released v2 of the form group. This adds the "title" property to sections and allows sections with the same name to be grouped together so that they can be completed at the same time. If you are already using the first version of the hub and spoke blueprint you can continue to do so and importing the new version won't affect your existing forms.

When you import the new form group you'll see a new blueprint and a new example form. The three snippets are exactly the same as in version 1. If you choose to overwrite your existing snippets, they'll appear in the new form group.

Creating a form from the blueprint

To create a new form, right-click on the "Hub blueprint" and pick "Create a form using..."

This will create a new form in the forms designer, which you can name and save in a group of your own.

Add pages to your form

For now, ignore the hub page. Add pages to your form in the usual way, including whichever fields you need in your form design. You can remove the example page 1 if you like - we've included it to show the structure of a typical page.

Don't add any navigation buttons to your form, these are provided by the snippets.

Hub - page top snippet

The "Hub - page top" snippet should be added to the top of every page of your form.

The fields should not be edited. They do the following:

Calculate whether or not this page is the last in a section (used in the navigation buttons in the snippet added to the bottom of the page)
Provides a back link which always navigates back to the hub page
Displays the page title, which is set on the hub page (see below)

Hub - page bottom snippet

The "Hub - page bottom" snippet should be added to the bottom of every page of your form.

The fields should not be edited. They do the following:

Removes data for any pages which have been flagged as disabled (see below) then navigates to the next enabled page
Marks the page as complete and checks if the entire section is complete

The default behaviour of the "Save and continue" button is to navigate to the next page in the section that hasn't been filled out already. For example, if a user fills out a page in the middle of a section first, it will be skipped over when they go back and fill out the previous page. The final page in a section always returns to the hub.

Edit the hub page

The hub page acts as the central point of your form. It describes the structure of your form and, when all the sections are complete, displays the submit button.

Page data variable

The only field that needs to be edited on the hub is the pageData variable at the top of the page:

This variable builds up the structure of your form and is updated by the fields in the snippets that are added to each page:

It's made up of an array of sections, and each section has an array describing one or more pages. The image above shows a form with two sections, called "About you" and "Your job". The first section has a single page called "Your name", the second section has two pages.

Sections

Each section entry must include the following:

section - This is the name of the section. Sections with the same name will become active together
title - The title of the section is displayed as the section title on the hub page
sectionCompleted - This should always be false in the initial design. As sections are completed, this value is changed to true by the various snippets and actions added to your pages
pages - One or more pages that will appear in the section

Submit and actions

The hub page includes two conditional layouts:

The first one is displayed while for form is being filled out. It will appear if any of the sections are still flagged as sectionCompleted: false. Feel free to update the guidance text or add new fields here. Action fields should not be placed in this layout as they won't be triggered.

Once all of the sectionCompleted properties in your pageData are true, the second conditional layout is shown. It includes a submit button and confirmation message. You can add any actions you need here (for example, starting a workflow or sending an email). These actions will be triggered when the submit button is pressed.

Publish and test your form

Once you've added your pages with the snippets, and updated the pageData field and added any actions, your form is ready to test.

Advanced - Enabling and disabling pages

So far we've assumed that all of the pages in a section are enabled and a user works down the list of sections and pages. Pages can also be enabled or disabled dynamically.

At least one page in every section must be enabled. It is not possible to disable an entire section, or to have a section where all pages are disabled.

Enabling a disabled page

If you want a page to start as disabled and to only be enabled if a user fills out another field with a certain value, do the following.

Mark the page as enabled: false

In the pageData variable, start the page as enabled: false

Changing the enabled flag

The "Hub - set page enabled" snippet is used to change the enabled status of a page. In theory it could be added to any page of your form, but it makes most sense to add it to the page where a decision point is reached, that will then determine whether or not another page is enabled.

Place the snippet into the "Hub - page bottom" layout in between the button and script action (note, it must be placed above the standard script action):

The snippet has the following logic.

setPageEnabled - This is a custom function included in the blueprint and should not be edited
helper - Passed to the custom function and must always be included
page - The name of the page you'd like to change the enabled state of
true/false - Some logic that returns true or false. In the example above, if the value of the EXTRADETAILS field is yes, the logic will return true, anything else will return false. The example form in the download area shows this logic working

When a page is changed to enabled: true it will be included in the task list and will count towards the list of pages that need to be completed before a section is flagged as complete and the form can be submitted.

Disabling a page

Disabling a page works in exactly the same way as enabling one.

Add the "Hub - set page enabled" snippet to a page that has the field on it that determines whether or not another page should be enabled or not. Then add logic to the snippet that will return false based on the value of another field.

When you disable a page all of the data for that page is also removed from the form session. That means if a user fills out a page, then changes their mind and does something to disable it, all of the information they entered is also removed.

Last modified on 11 March 2024