README

Compact FAQ extension using Content Blocks (Record Types + Content Elements), Site Set, SCSS, and vanilla JS. Requires TYPO3 14.

First of all many thanks to the hole TYPO3 community, all supporters of TYPO3. Especially to TYPO3-Team and Gedankenfolger GmbH.

TYPO3 13 support is maintained on the 13.x branch.

Features:

FAQ Item record type (question, answer (RTE), categories, color variant)
FAQ content element: select items from a storage folder; options for open-first, single-open-only, and grouping by category with optional category headings
Accessible accordion markup and deep-linking via configurable URL parameter
schema.org FAQPage structured data output via brotkrueml/schema
SCSS (BEM) and no jQuery
Template and partial overrides from your site package without forking the extension

Install

1. Require via Composer

composer require gedankenfolger/gedankenfolger-faq

Activate the extension in the TYPO3 backend (Extensions module) if not done automatically.

2a. Include TypoScript via Site Set (recommended)

Add the set to your site configuration:

# config/sites/my-site/config.yaml
sets:
  - gedankenfolger/gedankenfolger-faq

2b. Include TypoScript via Classic Static Template

For installations without Site Sets, include the static template in your TypoScript template record:

Web > Template > Edit > Includes > Include Static (from extensions) → Gedankenfolger FAQ

3. SCSS compilation

ws_scss is bundled as a dependency and compiles Resources/Public/Scss/faq.scss automatically. To use the pre-compiled CSS instead, set faq.scss.default = 0 and faq.css.default = 1.

Usage

Create FAQ items under the record type "FAQ Item".
Insert the "FAQ" content element, point it to a storage folder with your FAQ items via "Storage folder".
Configure behaviour and style via site settings (SiteSet) or the TypoScript constant editor (Classic).

Options

Open first: opens the first FAQ initially if none is open yet.
Open single only: ensures only one FAQ can be open at a time (per component instance).
Group by category: groups items by their assigned sys_category.
Show category titles: when grouping is enabled, renders category headings above each group.

Behavior and accessibility

Markup uses native <details>/<summary> for accessible accordion behavior.
Deep-linking via hash (#faq-{uid}) opens the targeted item and, when single-open-only is enabled, closes siblings within the same component.
JavaScript is lightweight and instance-scoped via data attributes on the wrapper: data-open-first, data-open-single-only, and data-faq-parameter.

Settings / Constants

All settings can be configured via Site Set settings (recommended) or the TypoScript constant editor.

Constant	Default	Description
`faq.parameterName`	`faq`	URL parameter name used for deep-linking
`faq.schemaEnabled`	`1`	Output schema.org FAQPage markup
`faq.partialRootPath`	(empty)	Override path for partials (see below)
`faq.css.default`	`1`	Load pre-compiled default CSS
`faq.scss.default`	`1`	Load and compile default SCSS via ws_scss
`faq.color.default`	`#ffffff`	Default text color
`faq.bgcolor.default`	`#2f3b4a`	Default background color
`faq.color.primary`	`#000000`	Primary text color
`faq.bgcolor.primary`	`#005bbb`	Primary background color
`faq.color.secondary`	`#000000`	Secondary text color
`faq.bgcolor.secondary`	`#6c757d`	Secondary background color
`faq.color.tertiary`	`#000000`	Tertiary text color
`faq.bgcolor.tertiary`	`#b35f00`	Tertiary background color
`faq.font.family`	system-ui, …	Font family

Template Overrides

Templates and partials can be overridden from your site package without modifying the extension. Only the files you actually want to change need to be created — all others fall back to the extension defaults.

Template override

Set file = directly in your sitepackage TypoScript to replace the main template:

tt_content.gedankenfolger_faq {
    file = EXT:my_sitepackage/Resources/Private/Extensions/GedankenfolgerFaq/frontend.html
}

Available template:

frontend.html – main content element template

Partial overrides

Set faq.partialRootPath to a directory in your sitepackage. Only the partials you place there will be used; all others fall back to the extension defaults.

Via Site Set (config/sites/my-site/config.yaml):

settings:
  faq.partialRootPath: 'EXT:my_sitepackage/Resources/Private/Extensions/GedankenfolgerFaq/Partials/'

Via TypoScript constant editor:

faq.partialRootPath = EXT:my_sitepackage/Resources/Private/Extensions/GedankenfolgerFaq/Partials/

Available partials:

Frontend/Layout0/Faqs.html
Frontend/Layout0/FaqsByCategories.html
Frontend/Layout100/Faqs.html (Bootstrap accordion)
Frontend/Layout100/FaqsByCategories.html (Bootstrap accordion)
Frontend/Schema.html

CLI Commands

This extension provides two TYPO3 CLI commands for setting up and inspecting Playwright test pages. Both commands are intended for development and testing environments only.

`gedankenfolger-faq:setup-test-pages`

Creates a hidden page tree with one test page per content element option variant, plus a SysFolder with FAQ items and categories. UIDs are stored in sys_registry for later retrieval.

ddev typo3 gedankenfolger-faq:setup-test-pages

Options:

Option	Description
`--pid=<uid>`	Parent page UID. Auto-detected from the first site configuration if omitted.
`--site=<identifier>`	Site identifier to use for root page detection (e.g. `main`). Only relevant if multiple sites exist.
`--reset`	Delete existing test pages before creating new ones. Required if the page tree already exists.

If test pages already exist without --reset, the command exits with a notice and does nothing.

`gedankenfolger-faq:test-pages`

Reads the stored UIDs from sys_registry and outputs them as JSON. Primarily used by playwright.config.ts to resolve page UIDs at test runtime.

ddev typo3 gedankenfolger-faq:test-pages

Example output:

{
    "rootUid": 42,
    "folderUid": 43,
    "variants": {
        "default": 44,
        "open-first": 45,
        "open-single-only": 46,
        "grouped": 47,
        "grouped-titles": 48
    }
}

Returns {} with exit code 1 if no test data is found. Run setup-test-pages first.

Playwright Tests

End-to-end tests for all content element option variants are included in tests/playwright/faq.spec.ts. They require a running TYPO3 installation with this extension installed and active.

1. Install Playwright

In your TYPO3 project root (requires Node.js):

npm install --save-dev @playwright/test @types/node
npx playwright install chromium

2. Create test pages

ddev typo3 gedankenfolger-faq:setup-test-pages

3. Run tests

npx playwright test --config packages/gedankenfolger_faq/playwright.config.ts

Adapt to your environment

The config uses two environment variables that default to the ddev development environment:

Variable	Default	Description
`TYPO3_BASE_URL`	`https://typo314.ddev.site`	Frontend URL of your TYPO3 installation
`TYPO3_CLI`	`ddev typo3`	Command to invoke the TYPO3 CLI

Override them for non-ddev setups:

TYPO3_BASE_URL=https://my-site.local TYPO3_CLI="php vendor/bin/typo3" \
  npx playwright test --config packages/gedankenfolger_faq/playwright.config.ts

Reset test pages

ddev typo3 gedankenfolger-faq:setup-test-pages --reset

Changelog

See CHANGELOG.md — generated with git-cliff from Conventional Commits.

Acknowledgements

This extension builds on the following open source projects:

Notes

⚠️ Required sitepackage configuration

Disable e-mail spam protection

The sitepackage must set config.spamProtectEmailAddresses = 0.
Without this setting, e-mail links in the FAQ schema (JSON-LD) appear as obfuscated href="#" and are worthless for search engines.
This setting affects the entire site.

Notice on Logo / Trademark Use

The logo used in this extension is protected by copyright and, where applicable, trademark law and remains the exclusive property of Gedankenfolger GmbH.

Use of the logo is only permitted in the form provided here. Any changes, modifications, or adaptations of the logo, as well as its use in other projects, applications, or contexts, require the prior written consent of Gedankenfolger GmbH.

In forks, derivatives, or further developments of this extension, the logo may only be used if explicit consent has been granted by Gedankenfolger GmbH. Otherwise, the logo must be removed or replaced with an own, non-protected logo.

All other logos and icons bundled with this extension are either subject to the TYPO3 licensing terms (The MIT License (MIT), see https://typo3.org) or are in the public domain.

For full license terms covering all graphic assets, see LICENSE-ICONS.

gedankenfolger / gedankenfolger-faq

Maintainers

Package info

Statistics

Security