Download the PHP package goldnead/statamic-assessments without Composer

Assessments for Statamic

A questionnaire with points per answer and result levels by score. The visitor answers, leaves an email address and sees a result right away. The result becomes a contact event in LeadHub and a trigger in Automations, so it can set a tag, start a sequence or unlock an offer — the part a quiz is actually for.

No certificate, no file upload, no course required.

Requirements

What it does

• Three question types. Single choice (the chosen option's points), multiple choice (the sum of the chosen options), scale (value × points per step). Every question is required.
• Result levels. Ordered ranges of points, inclusive on both ends, each with a key, a name, a text and optionally a redirect. The editor refuses overlaps and gaps always, and refuses to publish levels that do not cover every achievable score.
• Public pages under /a/{handle} (the form) and /a/{handle}/r/{token} (the result), wrapped in the site's layout, with plain shipped templates you can publish and replace. Or draw the form yourself with the tags.
• One event, AssessmentCompleted, and two optional bridges: the address becomes a LeadHub contact without consent with a timeline event assessment.completed; the Automations addon gets a trigger assessments.completed filterable by assessment and level.
• Control Panel under Tools → Assessments: listing, editor, responses per assessment with CSV export. Three permissions. German and English, light and dark.
• Brand-scoped through goldnead/statamic-brand-context. Handles are unique across brands because the public URL names nothing else.

Installation

The third command copies the compiled Control Panel assets to public/vendor/statamic-assessments/. Without it the CP pages render without their JavaScript.

Optional siblings, used when installed and never required:

Building an assessment

Tools → Assessments → Create assessment. Title, handle (the public address), intro and closing text, whether to ask for a name, and the published switch. Then the questions:

Below the questions the editor shows the range a visitor can score with them — say 1 to

22. The result levels have to sit next to each other inside that range:

A gap (8 then 10) or an overlap (8 then 8) is refused on save. A draft may cover less than the range; a published assessment may not. If a question is edited after publishing and a score falls outside every level anyway, the visitor gets the nearest end rather than nothing.

A level with a redirect sends the visitor to that URL instead of the result page — a course page, a booking link, a sales page for that segment.

From code

create() and update() throw an InvalidArgumentException for levels that overlap or leave a gap, for a scale that does not end above where it starts, and — when published is on — for levels that do not cover the range.

update() with questions updates a question that carries its id, creates one that does not, and deletes the ones no longer listed. Ids are what stored responses key their answers by, so the Control Panel sends them back on every save. On top of that every response keeps a snapshot of the question texts and chosen labels as they were at submit time, so a question rewritten or removed later never blanks an older result.

The public side

The form posts email, optionally name, and answers[{question_id}]: an option index for single choice, a list of indexes for multiple choice, the value for a scale. Every question is validated against the question as it is now — an index that does not exist or a scale value off the end is a 422, not a zero. The address has to be a real one (email:rfc,strict, with a dot in the domain).

After a submit the visitor is redirected to the result page, or to the level's redirect. A JSON client (Accept: application/json) gets score, result_key, result_label, result_url and redirect back instead.

Two things about the result URL, both on purpose:

• It is permanent and shareable. The token is 40 random characters minted on the server; nothing the client sends becomes part of it. Whoever has the link sees the level, the score and the answers — not the email address, which is why the address is not on that page.
• The same address may answer as often as it likes. Every submit is its own response, its own result URL and its own AssessmentCompleted event. An automation that should fire only once per person says so in its own enrollment policy.

Templates

resources/views/assessment.antlers.html and result.antlers.html, rendered through Statamic's own view with the site's layout (configurable). When the site has no such layout the addon's own shell is used. Publish them to change them:

Both templates get their variables under assessment: (assessment:questions, assessment:action, …); only title is also in the cascade, for the layout's <title>. Nothing else goes in flat, so the site's own url or name inside the layout stays untouched. The shipped styling is a small inline stylesheet driven by custom properties on .assessment; turn it off with styles => false and keep the class names.

Tags

The tag pairs hand their variables over flat, since they run inside a template of your own. form and url render nothing for an unpublished or unknown handle. result renders nothing without a valid token, and never the email address.

Bridges

Both are off the moment the sibling is not installed, and can be switched off in config.

LeadHub. On AssessmentCompleted the address is ingested with source = assessment:{handle}, type = assessment.completed, and a payload of score, result_key, result_label, assessment, assessment_title and the readable answers. No consent is set: answering a questionnaire is not agreeing to mail. The contact id LeadHub reports is written back onto the response.

Automations. The trigger assessments.completed (group "Assessments") with two optional fields, assessment and result_key, both empty for "any". Output: response.{id,email,name,score,result_key,result_label,assessment,assessment_title,answers,completed_at}.

A failure in either bridge is logged and never fails the submit; the response is stored first.

Control Panel

The responses page shows the latest 500; the export streams all of them, ;-separated, UTF-8 with BOM, one column per question with the answer labels. A cell that starts with =, +, -, @, a tab or a carriage return is prefixed with ', so a name typed as =HYPERLINK(...) opens in Excel as text rather than as a formula.

Configuration

Events

Tables

assessments, assessment_questions, assessment_responses. Responses store the answers by question id, a readable snapshot of them (answers_readable: question, chosen labels, points), the score and the level key as they were at the time — a rule or a question edited later does not rewrite what somebody was told.

Development

License

Proprietary. See LICENSE.md.