README

faqextensions

faqextensions extends Contao's FAQ bundle with popular, recommended and helpful FAQ lists. Visitors can rate answers, and editors can highlight recommendations.

Features

• Most frequently viewed FAQ list: sorts answers by their view counter.
• Recent FAQ list: sorts answers by their last modification (tstamp).
• Recommended FAQ list: shows only recommended answers, sorted by question or modification date in ascending or descending order.
• Helpful FAQ list: sorts answers by helpful votes minus unhelpful votes.
• All four lists support category selection, an item limit, pagination and an optional FAQ reader module.
• The standard FAQ reader and FAQ page display voting links when enabled.
• Backend labels, help texts and voting messages are available in 18 languages.

Languages

Complete translations cover all 14 languages shipped with Contao 5.7 Core: Czech (cs), German (de), English (en), Spanish (es), Persian (fa), French (fr), Italian (it), Japanese (ja), Dutch (nl), Polish (pl), Russian (ru), Slovenian (sl), Swedish (sv) and Turkish (tr). All official FAQ bundle languages are covered as well. Latvian (lv), Portuguese (pt), Slovak (sk) and Serbian (sr, Cyrillic) remain available, bringing the extension's total to 18 languages.

The scope follows the language directories of the official Contao 5.7 Core and FAQ bundle. Contao's frontend allows additional languages; those do not all have official Core translations.

Regional locale variants such as de-CH, fr-CA and pt-BR use the base-language catalogue through Symfony's locale fallback. Serbian uses the supplied Cyrillic translation; script variants are not transliterated. Persian voting pages use right-to-left text direction. English remains the fallback for unsupported languages. The backend language follows the user's Contao preference; voting links use the language of the page they appear on.

Requirements

• Contao 5.7 or newer within Contao 5 (^5.7)
• PHP 8.3 or newer
• Contao FAQ bundle

The Contao comments bundle is optional.

Installation

Install hschottm/faqextensions through the Contao Manager or Composer, then run the database migrations:

composer require hschottm/faqextensions:^5.1
php vendor/bin/contao-console contao:migrate

Version 5.1 supports Contao 5.7. For Contao 5.3, use version ~5.0.0 from the contao53 branch.

Usage

1. Create FAQ categories and answers in the Contao backend.
2. Enable Recommended for answers you want to highlight, or Show helpful to display the voting controls.
3. Create one of the additional FAQ list modules, select its categories and configure the item limit and pagination.
4. Set the categories' redirect pages to pages containing a FAQ reader, or select a reader module in the list to display the answer on the same page.
5. Include the module in your page layout or as a frontend module content element.

Views are counted when the FAQ reader or FAQ page executes. Responses served from the page cache do not execute PHP and therefore do not increment counters.

Preventing repeated ratings

Voting links open a confirmation page. A rating is counted only after a CSRF-protected POST, so prefetching a link or a crawler visiting it does not vote. The confirmation page is never cached. The first submitted vote is final; submitting again, including the opposite rating, does not change the counters.

• Anonymous visitors are recognized by a signed, random browser cookie named faqextensions_voter, valid for one year from the last voting-page visit.
• Logged-in frontend members are additionally recognized by their member account, including when they use another browser. Browser and account claims are linked when a rating is submitted, preventing a second vote through logging in or out.
• A transaction and a unique database constraint protect the counters against duplicate and concurrent requests. Existing aggregate vote counts are retained.
• Only keyed hashes of browser/account identifiers and a timestamp are stored in tl_faq_vote. The extension does not store IP addresses or browser fingerprints. Claims are deleted with the FAQ and are not copied when an FAQ is duplicated.

Cookies must be enabled to vote. This is a practical deterrent, not proof of a person's identity: anonymous visitors can vote again after clearing/expiring their cookie or switching browsers. Different people sharing the same browser may be prevented from voting separately. Votes collected before this update cannot be associated with voters retrospectively. Rotating the application secret also invalidates existing cookie identities and signed voting links.

The cookie and stored identifiers should be described in the site's privacy information. The cookie is first issued when the visitor opens a voting link; ordinary FAQ page views do not set this cookie.

Templates and insert tags

The extension supplies mod_faqtoplist, mod_faqrecentlist, mod_faqrecommendedlist, mod_faqhelpfullist, mod_faqreader and mod_faqpage as .html.twig templates. Create overrides in Contao's template editor as needed. The four lists extend faqextensions_list.html.twig; the reader and FAQ page share faqextensions_answer.html.twig and faqextensions_vote.html.twig. The module template base names remain unchanged.

The templates reuse Contao's core module wrappers, images and comment form. No PHP templates are shipped by this extension.

Custom voting links can use {{faq_helpful_url::ID_OR_ALIAS}} and {{faq_nothelpful_url::ID_OR_ALIAS}} on a page containing the corresponding FAQ reader or FAQ page. Voting must be enabled and the answer must be published. These insert tags now generate signed links to the confirmation page. Old manually constructed ?vote=...&tl_faq=... links no longer submit votes; replace them with the insert tags.

The existing tl_faq fields viewcount, recommended, helpful, nothelpful and showhelpful retain their names and stored values.

Changelog

See CHANGELOG.md for changes grouped by release tag.

Updating existing installations

Run the database migration to create tl_faq_vote before accepting new votes, and clear the application/page caches to replace old voting links. FAQ content and existing vote totals are preserved.

Refresh the Contao cache and run database migrations through the Contao Manager or php vendor/bin/contao-console contao:migrate after updating. Convert custom .html5 overrides to .html.twig and review them against the supplied templates. Existing PHP overrides may still take precedence, so remove or rename them after converting. The extension does not convert custom templates automatically. Keep the existing template base names in module settings.

Development

Install the Composer development dependencies and run vendor/bin/phpunit. The tests cover service registration, list filtering, preview visibility and pagination counts, duplicate voting, rollback on errors and concurrent requests. The voting tests require PDO SQLite; the concurrency test additionally needs pcntl. Translation tests verify catalogue completeness, UTF-8 strings and numeric placeholders.

Run the rendering integration tests with an installed Contao 5.7 application (including the FAQ and comments bundles) and the PHP SQLite extension:

CONTAO_APP=/path/to/contao php tests/integration/render.php

The integration test boots a temporary application with its own SQLite database and removes it afterwards. It uses the application's installed dependencies but does not change that application's files or database. It checks all six templates, custom overrides, escaping, translations, real voting insert tags, images, downloads, comments, structured data and the full HTTP confirmation/POST flow. All 18 languages, regional fallbacks and Persian text direction are checked with the real Contao translation loader and HTTP routes.

License

This extension is licensed under the GNU Lesser General Public License, version 3 or (at your option) any later version (LGPL-3.0-or-later). See LICENSE.

Package icon

The scalable logo.svg uses a speech bubble, question mark and plus sign on an anthracite background with an orange corner, matching the extension family. For display in the Contao Manager, the logo is maintained separately in contao/package-metadata under meta/hschottm/faqextensions/logo.svg.