What it does 

pn_questionnaire lets editors build multi-step questionnaires entirely in the TYPO3 backend. Every part of a questionnaire is a record: the questionnaire itself, its questions, the answer options, the visibility conditions between them, the result pages and the advice blocks on those pages. Answers decide which questions appear next and which advice the visitor ends up with.

Typical use cases:

• Step-by-step decision trees that route a visitor to the right service
• Scored self-assessments — health checks, sustainability scans, skills tests
• Guided quizzes with a personalised result at the end
• Multi-path flows where earlier answers determine which questions follow

Features 

• Five question types: single choice, multiple choice, yes/no, scale (radio buttons or a range slider) and informational screens without input
• Visibility conditions per question, on a specific answer or on the value of a scale question, combined with AND/OR
• Result pages selected by score range, by a specific answer, by a scale answer, by a combination, or as a catch-all
• Advice blocks shown conditionally per answer or score, with the option to invert a condition so a block appears when an answer was not given
• Group headings that give a long result a nested heading structure; a heading appears only when at least one block in its group is visible
• Outcomes rendered inline, or as a redirect to a page, an external URL or the detail view of a record from another extension
• Anonymous result storage with a retrieval link, and a mail-to-self form with a rate limit
• Usage counters per questionnaire for starts and completions
• A frontend aimed at WCAG 2.2 AA, working without JavaScript

Integration 

• Configured per plugin instance through a FlexForm; TypoScript sets the site-wide defaults
• Fluid templates, partials and layouts overridable from a site package
• BEM class names on semantic markup — no design imposed
• English, Dutch and German labels included

Compatibility 

One codebase serves all three versions; each is verified with a full run-through. Privacy is a design constraint rather than a feature: a stored result holds no name, no IP address and no e-mail address, not even hashed.

Answering a question 

What is visible here:

• The progress bar with the percentage beside it. It counts the questions already answered, not the one on screen: 20% means one of five questions is behind the visitor.
• The asterisk before the question text marks it as required; the message below appears when the visitor tries to continue without answering.
• The three answer options of a single choice question, and the Next button, whose label can be changed per plugin instance.

The result page 

What is visible here:

• The result headline and body text from the result page record, followed by the advice blocks that matched the visitor's answers.
• Four group headings, each with the blocks that belong under it. A heading appears only when at least one of its blocks is visible.
• Bewaar je uitslag — the retrieval link, with the date it expires and a copy button, plus a link to the privacy statement.
• Mail je uitslag naar jezelf — the mail form. The address is used for that one mail and is not stored.

Quick start 

1. Install the extension (see Composer below) and run the Database Analyser in the Install Tool.
2. Load the TypoScript: on TYPO3 v13 and v14 add the Site Set proudnerds/pn-questionnaire to the site configuration, on v12 include the static template Questionnaire / Test / Decision tree. See Loading the TypoScript.
3. Create a Questionnaire record in the List module — a dedicated sysfolder keeps things tidy.
4. Add questions, answer options and at least one result page to that record. See Building a questionnaire.
5. Place the Questionnaire / Decision Tree plugin on a page and select the questionnaire record in its FlexForm.

Composer 

composer require proudnerds/pn-questionnaire

TYPO3 picks the extension up automatically; there is nothing to activate by hand.

Classic mode 

Install Questionnaire / Test / Decision tree from the TYPO3 Extension Repository through Admin Tools > Extensions, then activate it there.

Both routes 

After the first install, run the Database Analyser in the TYPO3 Install Tool to create the seven tables, and load the TypoScript as described below.

Upgrading 

Run the Database Analyser again after any update that adds a field; the changelog says so per release. Version 1.1.0 for instance added introduction_footer_text to the questionnaire table. Existing records and plugin settings keep working as they are — no migration wizard is needed.

Loading the TypoScript 

The TypoScript itself lives in Configuration/TypoScript/setup.typoscript and constants.typoscript — a location every supported TYPO3 version understands. It is offered through two routes, both pointing at those same two files:

Site Sets were introduced in TYPO3 v13.1 and are ignored by v12, which is why the static template exists. The files in Configuration/Sets/PnQuestionnaire/ contain nothing but an @import of the files above.

dependencies:
  - proudnerds/pn-questionnaire

name: proudnerds/pn-questionnaire
label: Questionnaire / Test / Decision tree

The retrieval route 

Storing results produces a link of the form /{plugin-page}/saved-result/{token}. An extension cannot register route enhancers itself, so the site configuration has to import the shipped one:

imports:
  - resource: 'EXT:pn_questionnaire/Configuration/Routing/SavedResult.yaml'

Without that import the retrieval link still works, but as a query-string URL. See The retrieval route for the details.

Backend search on TYPO3 v14 

On v12 and v13 the records of this extension declare their backend search fields explicitly. TYPO3 v14 dropped that mechanism and derives searchability from the field type instead, so on v14 a search in the list module covers every text-like field of these tables rather than a curated subset. The extension follows each version's own convention; nothing needs configuring.

View paths 

Override the template paths per site package using the constants. You only need to place the files you want to override; TYPO3 merges these with the extension defaults using indexed path arrays, where index 1 overrides index 0.

plugin.tx_pnquestionnaire_questionnaire {
  view {
    templateRootPath = EXT:your_sitepackage/Resources/Private/Templates/PnQuestionnaire/
    partialRootPath  = EXT:your_sitepackage/Resources/Private/Partials/PnQuestionnaire/
    layoutRootPath   = EXT:your_sitepackage/Resources/Private/Layouts/PnQuestionnaire/
  }
}

Plugin defaults 

These settings have a FlexForm counterpart. The value here is what a plugin instance uses as long as its own field is untouched.

plugin.tx_pnquestionnaire_questionnaire.settings {
  show_score          = 0
  show_answer_summary = 0
  introduction_screen = 1
}

What the progress bar measures 

The counter above the bar reads "step X of Y" either way — that number is the visitor's position and does not change with this setting. Under completed it therefore says "step 1 of 5" next to an empty bar, which is intentional: the step is the one being answered, the bar is what lies behind it.

Stored results and mail 

Fallbacks for the fields on the Storing and mailing the result tab of the plugin. Storing and mailing themselves are switched on per plugin instance only; there is no TypoScript equivalent for the two on/off fields, by design — a site-wide default that starts writing visitor data would be the wrong default.

plugin.tx_pnquestionnaire_questionnaire.settings {
  db_save_result_storage_pid   =
  db_save_result_lifetime_days = 365
  mail_from_address            =
  mail_from_name               =
}

Domain record outcomes 

The Domain record outcome type redirects the visitor to the detail view of a record from another extension. One target can be configured per site, and it takes both TypoScript and a TCA override.

plugin.tx_pnquestionnaire_questionnaire.settings {
  domain_record_target {
    pageUid    = 42    # UID of the page that hosts the detail plugin
    extension  = News  # Extension name (CamelCase, no vendor prefix)
    controller = News
    action     = detail
    argument   = news  # Argument name the action expects
    plugin     = Pi1   # Plugin name as registered with ExtensionUtility
  }
}

$config = &$GLOBALS['TCA']['tx_pnquestionnaire_result_page']['columns']['record_uid']['config'];
$config['type'] = 'group';
$config['allowed'] = 'tx_news_domain_model_news';
$config['foreign_table'] = 'tx_news_domain_model_news';
$config['size'] = 1;

Plugin settings (FlexForm) 

These live on the plugin instance, so the same questionnaire record can behave differently on different pages. The Editor Guide describes what they do in practice; the reference below names the fields.

Concepts 

Step 1 — Create a questionnaire record 

1. Open the List module and navigate to the folder where questionnaire records should be stored. A dedicated sysfolder keeps the list module tidy.
2. Create a new Questionnaire record.
3. Fill in the Title. This is an internal label, never shown to the visitor.

4. On the Introduction screen tab, optionally fill in:

   Introduction text

   Appears before the first question, above the start button.

   Text below the start button

   A closing remark — for instance how long the questionnaire takes, or what happens with the answers.

   Both are only shown when the introduction screen is enabled in the plugin settings, and both may be left empty.

5. Save the record.

A questionnaire record carries the standard TYPO3 access fields as well: hide it to take the questionnaire offline, or set a publish date and an expiry date to have it appear and disappear on its own. A hidden or expired questionnaire renders nothing in the frontend.

Step 2 — Place the plugin on a page 

1. Edit the page where the questionnaire should appear.
2. Add a new content element and pick Questionnaire / Decision Tree from the plugins tab.
3. On the Configuration tab, select the questionnaire record in the Questionnaire field.
4. Adjust the remaining settings if needed — see Plugin settings (FlexForm).
5. Save.

Step 3 — Add questions 

Inside the questionnaire record, open the Questions tab and click Create new Question.

Questions are shown in the order they appear in the list. Drag and drop to reorder, and hide a question to take it out of the flow without deleting it.

Step 4 — Add answer options 

For Single choice, Multiple choice and Yes / No questions, open the Answer Options tab of the question and add one option per selectable answer.

Drag and drop answer options to reorder them.

Step 5 — Add conditions (branching) 

A condition makes a question only visible when a specific previous question was answered in a specific way. This is how a decision tree is built. There are two condition types.

Q1: What is your situation?
    → "Employed"           → show Q2a (work questions)
    → "Self-employed"      → show Q2b (entrepreneur questions)
    → "Looking for work"   → show Q2c (job-seeker questions)

Step 6 — Add result pages 

Open the Result Pages tab of the questionnaire and click Create new Result Page.

Each result page answers two questions: when does it apply, and what happens then.

Step 7 — Add advice blocks 

Advice blocks are conditional content sections within an inline result page. They show personalised advice depending on the visitor's score or a specific answer, within the same result. They are only available when the outcome type is Inline.

Advice blocks appear in the order of the list, and only those whose condition is met are rendered.

Question types 

Scale questions have a Scale display field:

Tips and rules of thumb 

What the visitor gets 

With storing on, the result page gains a link the visitor can save or share. Opening it later brings back the same result, without a login and without the visitor's session.

Nothing identifying is stored: no name, no IP address, no e-mail address, not even in hashed form. What is stored is the given answers, the score and a random code that appears in the link. Someone without the link cannot find the result, and the answers cannot be traced back to a person.

Two consequences worth knowing:

• The result disappears once the retention period expires. Say so in the text around the link if visitors are likely to rely on it.
• The link is the only key. A visitor who loses it cannot recover the result, and neither can an administrator.

Point settings.privacy_link at the page where your organisation explains this. The extension only links to it — the text itself is yours to write, and it should mention the retention period and that no personal data is stored.

With mailing on, the result page shows a form asking for an e-mail address. The visitor receives the full result plus the retrieval link. The address is used to send that one mail and is not stored — not in the database, not in a log, not on the stored result.

The table 

tx_pnquestionnaire_saved_result holds one row per completed run.

The crdate timestamp is the only field that could in theory be correlated with an access log, which is a reason not to extend the retention period beyond what is needed.

The retrieval route 

Configuration/Routing/SavedResult.yaml provides a route enhancer producing /{plugin-page}/saved-result/{token}. The site configuration has to import it; see The retrieval route.

Without that import the retrieval link still works, but as a query-string URL. The first segment follows the site language — saved-result, bewaarde-uitslag, gespeichertes-ergebnis. Add a locale to the localeMap for another language, or override the whole PnQuestionnaireSavedResult key after the import to change the wording. The token requirement is pinned to [0-9a-f]{32} so the enhancer never claims an unrelated URL on a page without the plugin.

After a domain change or a change to this route, the stored result_url values are stale. They can be regenerated from the tokens — the URL is derived data, not a source.

Retention and purging 

The retention period comes from settings.db_save_result_lifetime_days, falling back to settings.db_save_result_lifetime_days. It is applied when a result is stored, by writing expires .

Expired rows are removed by a console command:

vendor/bin/typo3 pnquestionnaire:purgesavedresults
vendor/bin/typo3 pnquestionnaire:purgesavedresults --dry-run

Register it as a scheduler task to keep the table clean. Unlike a backend deletion, the command removes rows for real rather than flagging them deleted — a stored result that has expired should not linger in the recycler.

The result mail 

The mail is sent as HTML and plain text, using the installation's own SystemEmail layout, so it inherits the styling already configured for TYPO3 mails.

Rich text inside the mail runs through lib.parseFunc_pnQuestionnaireMail , a copy of lib.parseFunc with forceAbsoluteUrl on. A relative href is a dead link in a mail client, and no Fluid ViewHelper can reach inside stored rich text — <f:format.html> hands the HTML straight to parseFunc. The nested parseFunc references for lists, preformatted text and table cells are repointed one by one; without that a link inside a list would still come out relative.

The sender falls back through three levels: the plugin's FlexForm, then TypoScript, then the installation's default sender. See settings.mail_from_address.

The send limit 

Configuration/Services.yaml defines a rate limiter for the mail form: three sends per hour, counted separately per recipient address and per client address. It uses the Symfony rate limiter that ships with the core, so there is no custom counting.

Two things to be aware of:

• The per-client limit is only as reliable as the proxy configuration. Behind a reverse proxy, reverseProxyIP has to be configured or every visitor looks like the same client.
• settings.mail_rate_limit_disabled switches the limit off. It is meant for testing an installation and should be off on a live site.

The form's protection against cross-site submission relies on FE.cookieSameSite being lax or stricter. That is a requirement, not a detail.

Usage counters 

With settings.statistics_enabled on, the questionnaire record keeps two tallies: starts , incremented when a visitor begins, and completions , incremented on a completed run. They are plain counters on the questionnaire record — no per-visitor data is involved.

Inverted conditions 

negate_condition on tx_pnquestionnaire_advice_block inverts a specific_answer condition. It is applied in ResultResolverService , at the point where the block's trigger answer is matched against the given answers. An absent answer counts as "not given", so an inverted block also appears for a question the visitor never answered — which is why Step 7 — Add advice blocks recommends making such questions required.

Overriding templates 

The extension uses standard TYPO3 Fluid template path merging. Copy any file from the extension's Resources/Private/ tree into your site package at the path configured in View paths, and TYPO3 uses your version instead. For purely visual changes no PHP is involved at all.

Layouts/
└── Default.html
Templates/
└── Questionnaire/
    ├── Intro.html
    ├── Question.html
    └── Result.html
Partials/
├── AnswerTypes/
│   ├── SingleChoice.html
│   ├── MultipleChoice.html
│   ├── YesNo.html
│   ├── Scale.html
│   └── Informational.html
├── AdviceBlock.html
├── ButtonLabel.html
└── Progress.html

ButtonLabel.html resolves one button label: it renders the FlexForm override when it is filled and the translated standard text otherwise. Progress.html renders the progress bar and is shared by the question steps and the result page.

Custom ViewHelper namespace 

The extension provides one custom ViewHelper. Declare its namespace in any template that uses it:

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      xmlns:pnq="http://typo3.org/ns/ProudNerds/PnQuestionnaire/ViewHelpers"
      data-namespace-typo3-fluid="true">

Key template variables 

Form field naming 

Answer inputs must use this exact name attribute for Extbase to map them to processAction(array $answers) :

name="tx_pnquestionnaire_questionnaire[answers][]"

And the hidden question UID field:

name="tx_pnquestionnaire_questionnaire[questionUid]"

Heading levels, and why the RTE needs Heading 4 and Heading 5 

The result page builds a heading hierarchy from three sources, only two of which the templates control:

That last row is the catch: the deepest level comes out of a rich text field, so it is the RTE configuration — not the extension — that decides whether an editor can produce a valid document. An installation therefore needs both Heading 4 and Heading 5 available in the preset used for tx_pnquestionnaire_advice_block.body_text :

• Heading 5 for a sub-heading inside a grouped block, whose title is already an h4.
• Heading 4 for a sub-heading inside an ungrouped block, whose title is an h3.

Which one an editor needs depends on whether the block sits in a group, and that can change after the fact — moving a block into a group shifts its title from h3 to h4, so any sub-heading in its body has to move down a level too. Offer both and the editor can always pick the level one step below the block title.

If the preset stops at Heading 3, every sub-heading an editor creates lands at the same level as — or above — the title of the block it belongs to, which breaks the document outline (WCAG 1.3.1). The extension deliberately does not set richtextConfiguration on the field to force this: that would override whatever preset the site assigns through page TSconfig, for every installation.

editor:
  config:
    heading:
      options:
        - { model: 'paragraph', title: 'Paragraph' }
        - { model: 'heading2', view: 'h2', title: 'Heading 2' }
        - { model: 'heading3', view: 'h3', title: 'Heading 3' }
        - { model: 'heading4', view: 'h4', title: 'Heading 4' }
        - { model: 'heading5', view: 'h5', title: 'Heading 5' }

Styling 

The extension ships a minimal CSS file (Resources/Public/Css/Questionnaire.css) that only defines the progress bar. Everything else is unstyled — apply all visual design in your site package.

The progress bar fill uses currentColor, which inherits from the nearest element with an explicit color value:

.pn-questionnaire__progress-fill {
    color: #your-brand-color;
}

JavaScript 

All behaviour is progressive enhancement: the questionnaire works without JavaScript through standard HTML form submissions.

Adding a language 

1. Copy Resources/Private/Language/locallang.xlf to a new file named {language-code}.locallang.xlf in the same directory.
2. Add target-language="{language-code}" to the <file> element.
3. Add a <target> element with the translation for each <trans-unit> .

TYPO3 picks the translation up automatically, based on the active frontend language. The Dutch translation (nl.locallang.xlf) can serve as a reference; German (de.locallang.xlf) is shipped as well.

The backend labels live in locallang_be.xlf and follow the same pattern.

How the parts fit together 

QuestionnaireController
    │
    ├── QuestionnaireRepository     → loads the configured questionnaire
    ├── SessionService              → stores / retrieves visitor answers
    ├── ConditionEvaluatorService   → filters questions to the visible subset
    ├── ProgressService             → calculates step X of Y, prev/next uids
    ├── ScoringService              → sums answer option scores
    ├── ResultResolverService       → picks the first matching result page
    │                                 and filters the advice blocks
    └── DomainRecordResolverService → builds the redirect URL for record outcomes

GET  /page  →  introAction()      render intro screen
GET  /page  →  questionAction()   render current question
POST /page  →  processAction()    store answer, redirect to next or result
GET  /page  →  resultAction()     resolve result, render or redirect
POST /page  →  resetAction()      clear session, redirect to intro

Service layer 

All business logic lives in Classes/Service/. The services are autowired through Configuration/Services.yaml.

Condition evaluation 

Each condition has a condition_type that determines how it is evaluated.

specific_answer (default) passes when the visitor selected a specific answer option for the reference question. Multiple conditions are folded together in list order:

result = evaluate(condition_1)
for each condition_2, condition_3, ...:
    if operator == AND → result = result && evaluate(condition)
    if operator == OR  → result = result || evaluate(condition)

scale_range passes when the numeric answer for the reference question satisfies the configured operator and threshold:

stored_value [operator] scale_value
e.g. 7 >= 5  → true

Supported operators are >=, <=, >, < and =. When the scale question has not been answered yet the condition returns false, so the dependent question stays hidden.

A question is shown when the final combined result is true.

Result page selection 

foreach resultPage in questionnaire.resultPages (ordered by sort_order):
    if matches(resultPage, sessionAnswers, totalScore):
        return resultPage  ← first match wins
return null  ← no catch-all configured

Session data format 

Answers are stored in the TYPO3 frontend session under the root key tx_pnquestionnaire.

tx_pnquestionnaire
└── q_{questionnaireUid}
    └── answers
        ├── "{questionUid}" → ["{answerOptionUid}"]   ← single choice
        ├── "{questionUid}" → ["{uid1}", "{uid2}"]    ← multiple choice
        └── "{questionUid}" → ["{scaleValue}"]        ← scale (raw number)

All values are stored as strings; the SessionService methods handle the conversion.

Extending the extension 

public function calculateTotal(array $visibleQuestions, array $sessionAnswers): float

Highlights per version 

Authors 

Created and maintained by ProudNerds:

• Jacco van der Post
• Emile Blume

Sponsor 

Development was funded by Gemeente Almere, the municipality of Almere, for their own websites. They made it possible to release the result as open source. Our thanks to them.

Icons 

The backend icons in Resources/Public/Icons/, ext_icon.svg included, come from Tabler Icons and are used under the MIT licence. They are committed to the repository; download-icons.sh only exists to refetch them and is excluded from the distribution package.

Support 

When reporting a bug, please include the TYPO3 and PHP version, the extension version, the relevant plugin and TypoScript settings, and — for a problem in the frontend — the browser console output.

Contributing 

Pull requests are welcome. Keep to the conventions of the code that is there: PSR-12, strict types, constructor injection, PHPStan level 5 clean, and Fluid rather than hand-written HTML in the templates.

License 

The extension is licensed under GPL-2.0-or-later. This manual is published under the Open Publication License.