Questionnaires

A questionnaire asks a longer list of questions, spread over pages, and collects the answers for you to read or download. Use one for a survey, an application or a members' feedback round. By the end of this chapter you will have a questionnaire with a link you can send to people, and a spreadsheet of what they answered.

A form is one page of fields that anyone who finds it can send as often as they like. A poll asks one question and counts the answers. A questionnaire sits between them: many questions, several pages, one answer per person, behind a link.

Questionnaires are a feature: a package you add to the site and list in site.config.ts. A site that was created with questionnaires chosen already has this, so go straight to “Make a questionnaire”.

Turn questionnaires on

  1. In your site's folder, install the package:
pnpm add @jamiemcconnell/cms-questionnaires
  1. Open site.config.ts, import questionnaires and list it under features:
site.config.ts
import { defineConfig } from '@jamiemcconnell/cms';
import { questionnaires } from '@jamiemcconnell/cms-questionnaires';

export default defineConfig({
  // …the rest of your settings stay as they are…
  features: [questionnaires()],
});
  1. Restart the site. In development, stop pnpm dev with Ctrl+C and run it again. No migration is needed. Questionnaires now appears in the admin's sidebar.

Make a questionnaire

  1. In the admin, open Questionnaires and choose New questionnaire.
  2. Type a Name, which only editors see, and a Title, which is the heading respondents read.
  3. Give the first page a Page title, and write the first question and pick its Type.
  4. Choose Create questionnaire. It opens on its Questions tab.
  5. Choose Add a question to add more, and Add a page to start another. A questionnaire has one to twenty pages, each with a title, an optional intro and its questions.
  6. Choose Save.

A question is one of these types:

  • Single choice, as radio buttons or as a drop-down, with two or more options.
  • Several choices, as checkboxes, with the fewest and the most a respondent may pick.
  • Short text and Long text, a line or a paragraph of written answer with a length limit.

Any question can be Required and can carry a line of Help. Options and questions keep their identity when you rename or reorder them. You can edit a questionnaire that already has responses: each response keeps the wording it was given, so nothing already stored changes.

Set it up

The Settings tab holds:

  • the Name, Title and an Intro shown above the first page;
  • whether to ask for the respondent's name and email, each Off, Optional or Required. A signed-in respondent has them filled in and can change them;
  • “Who can answer”, described below;
  • “Closed now”, and a Closes date in the site's time zone;
  • “Email each response to”, one address per line, up to ten. Leave it empty for no email;
  • the Thank-you message shown once a response is in, and the Closed message shown instead of the questions when the questionnaire is closed.

The email for each response is one of the site's emails, and its wording is under Content → Emails. It is only sent once the site has a real email provider (Going live).

Send the link

Every questionnaire has its own link of the form /q/<token>, shown under its name and on the list, with a Copy button. The token is long and random, so only the people you send the link to can find it. The page is not indexed by search engines and is never cached. To retire a link, close the questionnaire.

How a questionnaire looks comes from one template, under Content → Templates → Questionnaire, so every questionnaire is styled once.

Or put it on a page

A Questionnaire block, from the Questionnaires group of the block picker, shows a questionnaire inside any page. Pick it in the block's Questionnaire field. Its link is then as public as that page. The words on its buttons, the step text and the messages are fields of the block.

Who can answer, and how often

Left on Everyone, anyone with the link can answer. “Who can answer” narrows it to an audience, such as signed-in visitors or a group. A visitor who is not allowed sees a short message, or a link to sign in. The questions of such a questionnaire are only ever sent to someone it admits.

When you ask for the email, an address can answer once, and a second try is told so. The address is not verified, so this only stops casual repeats. A response without an email, because you do not collect it or it was left empty, is never limited.

What respondents see

The questionnaire shows one page at a time, with a strip of the pages and a line such as “Page 2 of 3”. Next checks the page and shows what is missing under each question. Back keeps every answer. The last page has Submit. After a response the respondent sees the thank-you text in place.

Nothing is saved part-way, so leaving the page loses the answers. Answering needs script, and runs a CSRF token and a proof-of-work check against bots, as forms do.

Read and download the responses

The Responses tab lists every response with its time, name, email and first answers. A row opens the response grouped by page, with Delete for spam or a data request. Download CSV gives one row for each response and one column for each question, in the questionnaire's current order, ready for a spreadsheet. A question you removed since, or relabelled, keeps its column.

Names, emails and answers are personal data. Deleting a response, or a questionnaire, removes them.