Wizards

Fast-gov-uk have some handy tools for building GDS Question pages - also known as Wizard on the interwebs.

The following is a simplified implementation of the Equality Survey -

 1@fast.wizard
 2def equality(step=0, data=None):
 3    return forms.Wizard(
 4        "equality",
 5        forms.Question(
 6            ds.Radios(
 7                name="permission",
 8                label="Do you want to answer the equality questions?",
 9                choices={
10                    "yes": "Yes, answer the equality questions",
11                    "no": "No, skip the equality questions"
12                },
13            ),
14            cta="Continue",
15        ),
16        forms.Question(
17            ds.Radios(
18                name="health",
19                label=(
20                    "Do you have any physical or mental health conditions or illness "
21                    "lasting or expected to last 12 months or more?"
22                ),
23                choices={"yes": "Yes", "no": "No", "skip": "Prefer not to say"},
24            ),
25            predicates={"permission": "yes"},
26            cta="Continue",
27        ),
28        forms.Question(
29            ds.Radios(
30                name="ability",
31                label=(
32                    "Do any of your conditions or illnesses reduce your ability "
33                    "to carry out day to day activities?"
34                ),
35                choices={"alot": "Yes, a lot", "little": "Yes, a little", "not": "Not at all", "skip": "Prefer not to say"},
36                required=False,
37            ),
38            predicates={"permission": "yes", "health": "yes"},
39            cta="Continue",
40        ),
41        forms.Question(
42            ds.Fieldset(
43                ds.Radios(
44                    name="sex",
45                    label="What is your sex?",
46                    choices={"female": "Female", "male": "Male", "skip": "Prefer not to say"},
47                ),
48                ds.Radios(
49                    name="gender",
50                    label=(
51                        "Is the gender you identify with the same as "
52                        "your sex registered at birth?"
53                    ),
54                    choices={"yes": "Yes", "no": "No", "skip": "Prefer not to say"},
55                ),
56                legend="Sex and gender identity",
57                name="sex-and-gender",
58            ),
59            predicates={"permission": "yes"},
60            cta="Continue",
61        ),
62        backends=[forms.DBBackend(db=fast.db)],
63        step=step,
64        data=data,
65    )

1. The wizard decorator “registers” this function as a wizard rendered at /wizards/equality. You can easily render this at a different url - @fast.wizard("/not-equality") would render the wizard at /wizards/not-equality.

2. The equality function must return a Wizard object (see below) and it must accept step and data arguments. You can think of Wizards as a series of Forms. The step argument identifies a form within a Wizard. Each Form can be empty or filled and when they are filled, the data argument would contain the values that we can use to populate our form fields.

3. The Wizard class is used to define a wizard. A Wizard comprises of one or more Question objects - which are a subclass of Form - and so they look like forms and they work like forms.

25. Except, unlike Form objects, Question objects accept an argument called predicates. This is a dictionary that defines the names of fields and the values they must have if this particular Question is to be shown to our user. In our example, we are saying that each Question following the first “permission” question would render only if the user clicked “Yes, answer the equality questions”.

62. Like Form objects, Wizard objects accepts a list of backends that define what happens when a Wizard is processed upon submission. These backends are the same as the ones in Form.