Admin Guide — pn_questionnaire 

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.