On TYPO3 v13 and v14 — Site Set 

Add the set to any site that should use the questionnaire plugin by adding it to dependencies in the site's config.yaml:

# config/sites/your-site/config.yaml
dependencies:
  - proudnerds/pn-questionnaire

The set name is defined in Configuration/Sets/PnQuestionnaire/config.yaml:

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

TYPO3 automatically includes setup.typoscript and constants.typoscript from the set directory when the dependency is active.

Troubleshooting — TypoScript from the set is not loaded

If the set is listed in dependencies but the TypoScript is still not applied, check the root TypoScript template in the TYPO3 backend:

1. Go to Web → Template, select the root page, open the template record.
2. On the Options tab, make sure "Clear constants" and "Clear setup" are both unchecked.

When either flag is checked, TYPO3 discards all TypoScript that was loaded by Site Sets before evaluating the template's own content — effectively wiping setup.typoscript entirely. Unchecking both flags lets the Site Set TypoScript survive and be extended by the template.

On TYPO3 v12 — static template 

The extension registers Configuration/TypoScript/ as a selectable static template in Configuration/TCA/Overrides/sys_template.php. Go to Web → Template, open the root template record and add Questionnaire / Test / Decision tree (pn_questionnaire) to Include static (from extensions).

Include it before any site package that overrides the view path constants, otherwise those overrides are undone again.

Do not combine the static template with a site package that already imports EXT:pn_questionnaire/Configuration/TypoScript/setup.typoscript directly — the values are identical so setup stays correct, but a second pass over the constants can override a site package's view path overrides depending on include order.

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 path overrides 

Override the default template paths per site package using the constants:

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/
  }
}

TYPO3 merges these with the extension defaults using indexed path arrays (index 1 overrides index 0). You only need to place the files you want to override.

Default FlexForm values 

These defaults apply when a new plugin instance is inserted. Editors can override them per placement.

plugin.tx_pnquestionnaire_questionnaire.settings {
  show_score          = 0   # 0 = hidden, 1 = visible
  show_answer_summary = 0
  introduction_screen = 1
}

Step 1 — TypoScript 

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
  }
}

Step 2 — TCA override 

The extension ships record_uid as a plain number, because it cannot know which table your site links to. The site package names that table, and turns the field into a record browser while it is at it. Create Configuration/TCA/Overrides/tx_pnquestionnaire_result_page.php in your site package:

$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;

type and allowed give you the record browser; foreign_table is what Extbase needs to resolve the record. Both table names must match the TypoScript target.

Do not leave allowed empty on a group field. TYPO3 throws RuntimeException 1482250512 while compiling the form, which takes down the entire result page editing form — not just this one field — even for result pages that use a different outcome type. That is why the shipped default is a number and not an unconfigured group.

The DomainRecordResolverService reads the foreign_table value from $GLOBALS['TCA'] at runtime to derive the table name — so a single source of truth is maintained between TypoScript and TCA.

The table 

tx_pnquestionnaire_saved_result holds one row per completed run.

No identifying data is stored — no name, no IP address, no e-mail address, not even hashed. 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>. An extension cannot register route enhancers itself, so the site configuration has to import it:

# config/sites/your-site/config.yaml
imports:
  - resource: 'EXT:pn_questionnaire/Configuration/Routing/SavedResult.yaml'

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 is db_save_result_lifetime_days in TypoScript, default 365, overridable per plugin instance through the FlexForm. 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 (mail_from_address / mail_from_name), then the installation's default sender.

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 — if the site runs behind a reverse proxy, reverseProxyIP has to be configured or every visitor looks like the same client. And the FlexForm has a Switch off the send limit checkbox intended for testing an installation; it should be off on a live site, because the limit is what prevents the form from being used to send mail to other people's addresses in bulk.

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 Count usage 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 the Editor Guide recommends making such questions required.

Default paths (from extension) 

Resources/Private/
├── 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

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">

Available ViewHelpers:

Key template variables 

Form field naming 

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

name="tx_pnquestionnaire_questionnaire[answers][]"

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 RTE 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.

Add the missing levels to the heading.options list of the preset your site already uses:

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' }

Note that CKEditor replaces this list as a whole rather than merging it, so if you override it in a separate file, repeat the entries you want to keep. Also check that h5 is present in the allowTags list of the processing configuration — otherwise the tag is stripped on save. The default EXT:rte_ckeditor/Configuration/RTE/Processing.yaml allows h1 through h6.

BEM class reference 

Overriding the progress bar colour 

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

/* In your site package */
.pn-questionnaire__progress-fill {
    color: #your-brand-color;
}

Questionnaire.js 

Loaded via f:asset.script in Layouts/Default.html and initialises on DOMContentLoaded by looking for [data-questionnaire] in the DOM.

<input type="range"> always has a value, so required validation passes automatically for scale slider questions.

ScaleRange.js 

Loaded conditionally via f:asset.script only when a scale question renders as a range slider (scale_display = range). TYPO3 deduplicates it automatically — safe to use across multiple scale questions on the same page.

The <output> element is server-rendered with the correct initial value, so the slider is usable without JavaScript.

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

Replacing the JavaScript 

Point f:asset.script in your layout override to a different file, or load your own script that initialises a class targeting [data-questionnaire].

Action flow 

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

All five actions are registered as uncached in ext_localconf.php.

Condition evaluation logic 

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:

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 visitor's numeric answer for the reference question satisfies the configured operator and threshold:

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

Supported operators: >=, <=, >, <, =

If the scale question has not been answered yet, the condition returns false (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

Trigger type matching:

Adding a new question type 

1. Add the new type value to the type select field in Configuration/TCA/tx_pnquestionnaire_question.php (both the items array and the types array)
2. Add the type constant to Classes/Domain/Model/Question.php
3. Create Resources/Private/Partials/AnswerTypes/YourType.html
4. Add the mapping in QuestionnaireController::questionAction() in $answerTypePartialMap

No other changes are required.

Adding a new outcome type 

1. Add the new outcome value to the outcome_type select field in the result page TCA
2. Add the outcome constant to Classes/Domain/Model/ResultPage.php
3. Handle the new outcome in QuestionnaireController::handleRedirectOutcome() or resultAction()

Custom result resolver logic 

To replace or extend the result matching logic, create a service that extends or wraps ResultResolverService and reconfigure it in Configuration/Services.yaml.

Custom scoring logic 

Replace ScoringService with your own implementation via Configuration/Services.yaml service aliasing. Your service only needs to implement the same method signature:

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

Template-only customisation 

For purely visual changes — copy any Fluid template from Resources/Private/ into your site package at the configured override path. TYPO3's path merging ensures your version takes precedence. No PHP changes needed.

Condition type: Specific answer 

1. Open the Visibility Conditions tab of the question that should be conditionally shown
2. Click Create new Condition
3. Set Condition type to Specific answer
4. Select the Reference question — the earlier question whose answer determines visibility
5. Select the Reference answer — the specific answer option that must have been chosen
6. Save

Condition type: Scale value 

Use this when the reference question is a Scale / Rating question and you want to show or hide based on the numeric value the visitor selected.

1. Open the Visibility Conditions tab
2. Click Create new Condition
3. Set Condition type to Scale value
4. Select the Reference question (must be a scale question)
5. Choose an Operator: >=, <=, >, <, or =
6. Enter a Value to compare against
7. Save

Example: Show a follow-up question only if the visitor rated satisfaction >= 8.

Multiple conditions 

You can add more than one condition per question. Each condition has an Operator field:

Conditions are evaluated in the order they appear in the list (top to bottom, by sort order).

Rules 

• Conditions can only reference questions that appear earlier in the questionnaire. It is your responsibility to ensure this.
• A question with no conditions is always shown.
• Skipped questions do not count toward progress or score.
• For Scale value conditions: if the referenced question has not been answered yet, the condition fails and the dependent question stays hidden.

Example 

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

Q2a has a condition: type = Specific answer, reference question = Q1, reference answer = "Employed". Q2b has a condition: type = Specific answer, reference question = Q1, reference answer = "Self-employed". Q2c has a condition: type = Specific answer, reference question = Q1, reference answer = "Looking for work".

Trigger — when does this result apply? 

See §11 for all trigger types.

Outcome — what happens when it applies? 

See §12 for all outcome types.

Inverting a condition 

Invert condition turns a Specific answer condition around: the block appears when the visitor did not choose that answer.

This is useful for advice that only applies to people who skipped something. Take a question about organ donation with one option "I have already registered my choice". Attach a block to that option, tick Invert condition, and everyone who did not register gets the reminder — while the people who did are spared a message that does not apply to them.

Watch out: an unanswered question counts as "not given". If the question is optional, or the visitor never reached it, the answer is absent — so an inverted block will appear. Whether that is what you want depends on the text. A reminder ("don't forget to arrange this") is fine for someone who skipped the question. A statement that assumes a situation ("since you have not arranged this yet") is not. Make the question required if you need the distinction to be reliable.

Grouping blocks under a heading 

A long result page reads better in sections. Set Condition type to Group heading above other blocks to turn a block into a heading, then set Part of group on every block that belongs underneath it.

What to keep in mind:

• A group heading has no condition of its own. It appears automatically when at least one block in its group is visible, and disappears when none are. You never have to maintain the heading's visibility by hand.
• A group heading has no body text — only a headline.
• The headline of a grouped block moves one heading level deeper than an ungrouped one. That matters for the rich text in the body: sub-headings inside a grouped block belong on Heading 5, not Heading 4. Using the wrong level skips a level in the document outline, which screen readers and search engines both read as an error.
• Blocks that are not part of any group keep their normal level and can sit before, between or after the groups.

Tab: Settings 

Tab: Button labels 

The navigation buttons carry a standard text that follows the language of the site. Each of them can be given an own text here, per plugin instance — useful when the questionnaire is a checklist rather than a test, or when the tone of the page asks for something else than "Next".

The standard text of each field is shown in grey as long as the field is empty, and an empty field keeps that standard text. There is no need to fill in all of them.

The last two only appear once their function is switched on in Storing and mailing the result: the copy button belongs to the retrieval link, the send button to the mail form.

Tab: Storing and mailing the result 

Leaving a field empty is meaningful here: the extension then falls back to its own standard text or to the installation's setting. You only fill in what you want to deviate from.

Keeping and sharing the result 

With Store the result 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 who does not have 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 Link to the privacy statement 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.

Mailing the result 

With Allow mailing the result 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 mail uses the layout of your TYPO3 installation and is sent as both HTML and plain text. Opening text of the mail and Closing text let you replace the standard lines; leave them empty to keep the defaults.

Leave "Switch off the send limit" off on a live site. The limit is what stops the form from being used to send mail to other people's addresses in bulk. Switching it off is meant for testing an installation, where repeated attempts would otherwise be blocked.

Scale display 

Scale questions have a Scale display field that controls how the input is rendered:

Scale and informational questions are score-neutral — they never add to the total score.

Inline outcome fields 

Multiple links in a result? The result page supports one CTA button. If you need multiple links, add them as hyperlinks inside the Body text field.

Questionnaire structure 

• Start with a sketch on paper of the question flow and the possible outcomes before building in the backend
• Use descriptive internal titles on questionnaire and result page records — editors will thank you later
• Store questionnaire records in a dedicated sysfolder to keep the list module tidy

Conditions 

• Only reference questions that appear above the current question in the list
• Test the branching by going through the questionnaire as a visitor — condition mistakes are easy to miss in the backend
• Use the Start over button during testing to reset the session — it only appears after the first answer has been submitted

Result pages 

• Always add a catch-all result as the last entry — without it, visitors who don't match any specific trigger will see an error message
• For score-based questionnaires, make sure your score ranges cover all possible totals with no gaps

Scoring 

• Scores can be positive or negative (e.g. +2 for a healthy choice, -1 for a risk factor)
• Score is only displayed to the visitor if Show score on result is enabled in the plugin settings
• Advice blocks with score-range conditions work regardless of whether the score is displayed

Reuse 

• The same questionnaire record can be placed on multiple pages — useful for embedding the same tool in different contexts
• Each placement has its own FlexForm settings, so you can show the score on one page but not another