Polls

A poll asks visitors one question and counts the answers. You decide who may vote, how often, and who gets to see the results. By the end of this chapter you will have a poll on a page that takes votes and shows the totals.

A poll is one question. For several questions use a form, which keeps what people send instead of counting it, or a questionnaire for a longer list over several pages.

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

Turn polls on

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

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

Make a poll

  1. In the admin, open Polls and choose New poll.
  2. Type a Name, which only editors see, and check the Key. The key is filled in from the name. Blocks refer to the poll by it.
  3. Type the Question exactly as visitors should read it.
  4. Pick the Answer type: Single choice (radio buttons), Multiple choice (checkboxes) or Free text (one typed answer).
  5. For a choice poll, list two to twenty Choices in the order visitors should see them. Tick “Offer an “Other…” choice” to add a choice with a text box. For Multiple choice you can also set the fewest and the most a voter may pick.
  6. Choose Create poll.

Choices keep their identity when you rename or reorder them, so fixing a typo costs no votes. Free text answers and Other write-ins are for you: visitors never see them.

Put the poll on a page

  1. Open the page in the editor and add a Poll block, from the Polls group of the block picker.
  2. In the block's Poll field, pick your poll.
  3. Publish the page. Publishing checks that the poll exists.

The block draws the question and the voting form, and the poll's own settings decide everything else. The words on the button and in every message, such as the thank-you and “already voted”, are fields of the block, so they can be in your own voice. The controls follow the form look set under Settings → Theme.

A Poll results block shows the bars for a poll anywhere else, such as a page of its own.

Decide who may vote, and how often

These settings are on the poll's Settings tab, under Voters.

“Who can vote” narrows the poll 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. You can also ask voters for their name and their email address: each can be Off, Optional or Required.

“One vote per” decides what counts as one voter:

  • Browser is the default. A cookie in the visitor's browser remembers that they voted. It is soft: clearing cookies or using another browser allows another vote, though a limit of ten votes an hour from one address slows that down.
  • Email address needs the email to be Required. The address is not verified, so this only stops casual repeats. A visitor who comes back signed out sees the ballot again and is told on voting that the address has already voted.
  • Account means the visitor must sign in, and each account votes once whatever browser or address it uses. This is the strong option.

Show the results

Under “Who sees the results”, three boxes decide when the counts are shown: Before voting, After voting and When the poll closes. By default the counts show after a visitor has voted and once the poll has closed. You always see every count in the admin.

The server decides, not the page: a visitor who may not see the results is never sent them. Choices appear as bars, shown as a percent, a count or both (the “Show results as” field of the block), and right after voting the visitor's own picks are marked. “Other” counts as one choice in public.

In the admin each poll has three tabs. Results shows the counts, the write-ins and the written answers. Votes lists every vote with its name, email and account if you asked for them, lets you delete one (for spam), exports them with Export CSV, and has Reset votes to clear them all. Settings holds everything above.

After a vote

Under “After voting” you choose between two behaviours:

  • “Show a thank-you on the page” replaces the ballot with the thank-you text and, when the results are visible, the bars.
  • “Go to a page” sends the visitor to the poll's success page. Every poll set to this gets one, which you edit like any page under Content → Callback pages. Visitors can only reach it by voting. Add a Poll results block to it to show how everyone voted: the link the visitor arrives by proves they have voted, so the results show to them there even when After voting is the only box ticked. You can also pick another callback page for the poll.

Open and close a poll

Under “Opens and closes”, set Opens and Closes dates in the site's time zone. Leave them blank for a poll that opens straight away and stays open. “Closed now” closes the poll at once, whatever the dates say.

Changing a poll that has votes

Once a poll has votes, its answer type is fixed and a choice with votes cannot be removed. You can still relabel, reorder and add choices. Choose Reset votes on the Votes tab to clear every vote, which frees both.

How it behaves on the page

Voting needs script. The page asks for a CSRF token and a proof-of-work check, as forms do, so a visitor with JavaScript switched off is told so. Pages that hold a poll stay cached for everyone, and the block asks the server for the visitor's own state once the page loads. That can show as a brief change from the ballot to “already voted”.