PHPackages                             avh/contao-faq-structured-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. avh/contao-faq-structured-bundle

ActiveContao-bundle

avh/contao-faq-structured-bundle
================================

SEO/AEO-optimized FAQ content element with Schema.org FAQPage JSON-LD and three template variants (Handorgel, Bootstrap 5, Tailwind CSS)

1.0.0(2w ago)123↓100%MITPHPPHP ^8.3

Since Mar 8Pushed 2w agoCompare

[ Source](https://github.com/avhulst/AvhContaoFaqStructuredBundle)[ Packagist](https://packagist.org/packages/avh/contao-faq-structured-bundle)[ RSS](/packages/avh-contao-faq-structured-bundle/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (2)Versions (2)Used By (0)

ContaoFaqStructuredBundle
-------------------------

[](#contaofaqstructuredbundle)

**Package name:** `avh/contao-faq-structured-bundle`

**Short description:** Custom Contao content element for SEO/AEO-optimized FAQ sections with automatic Schema.org FAQPage JSON-LD output and three template variants (Handorgel, Bootstrap 5, Tailwind CSS).

---

### Target Audiences

[](#target-audiences)

- **Developers:** Technical integration of the bundle into Contao 5.7, template customization, extending FAQ logic.
- **Project Managers:** Understanding SEO benefits (Rich Results in Google), feature overview for client consulting and project planning.

---

### Core Features

[](#core-features)

1. **FAQ Content Element** — New content type `faq_structured` in the *Texts* category. Unlimited question-answer pairs per element.
2. **Schema.org FAQPage JSON-LD** — Automatic generation of structured data in FAQPage format. Output in the `` of the page.
3. **Three Template Variants** — Handorgel (default), Bootstrap 5 Accordion, Tailwind CSS with `` element.
4. **Rich-Text Answers** — Answers are edited via TinyMCE and support HTML formatting (links, lists, bold text, etc.).

---

### Technical Architecture

[](#technical-architecture)

#### Directory Structure

[](#directory-structure)

```
custom/bundles/ContaoFaqStructuredBundle/
├── .editorconfig                                  # Code style configuration
├── .gitignore                                     # Git ignore rules
├── .gitlab-ci.yml                                 # CI/CD pipeline
├── CHANGELOG.md                                   # Changelog
├── LICENSE                                        # MIT license
├── README.md                                      # Documentation (English)
├── README_DE.md                                   # Documentation (German)
├── cliff.toml                                     # git-cliff changelog configuration
├── composer.json                                  # Package definition, dependencies
├── config/
│   └── services.php                               # Service autowiring
├── contao/
│   ├── dca/
│   │   └── tl_content.php                         # Backend field definitions (palette, fields)
│   ├── languages/
│   │   ├── de/default.php                         # German labels
│   │   └── en/default.php                         # English labels
│   └── templates/twig/
│       ├── .twig-root                             # Namespace root marker
│       └── content_element/
│           ├── faq_structured.html.twig           # Default template (Handorgel)
│           └── faq_structured/
│               ├── bootstrap.html.twig            # Bootstrap 5 Accordion
│               └── tailwind.html.twig             # Tailwind CSS Details
└── src/
    ├── ContaoFaqStructuredBundle.php               # AbstractBundle (loads services.php)
    ├── ContaoManager/
    │   └── Plugin.php                              # Bundle registration via BundlePluginInterface
    └── Controller/
        └── ContentElement/
            └── FaqStructuredController.php         # Content element logic

```

#### Request Flow

[](#request-flow)

1. Contao renders the content element `faq_structured`
2. `FaqStructuredController::getResponse()` is called
3. FAQ entries are deserialized from the serialized `faqItems` field and filtered
4. Schema.org FAQPage JSON-LD is built as an array
5. Template receives: `faq_items`, `schema_org_data`, `accordion_id`
6. JSON-LD is injected into the `` via `{% do add_schema_org(schema_org_data) %}`

#### Dependencies

[](#dependencies)

PackageVersionPurpose`php`^8.3Minimum PHP version`contao/core-bundle`^5.7Contao framework`mvo/contao-group-widget`^1.6Repeatable field groups in the backend (inputType `group`)---

### Setup / Installation

[](#setup--installation)

**Requirements:**

- Contao Managed Edition 5.7
- PHP 8.3+
- `mvo/contao-group-widget` ^1.6 (automatically installed as a dependency)

**Installation:**

The bundle is located as a local package under `custom/bundles/ContaoFaqStructuredBundle/`. It is included via the `repositories` configuration in the project's `composer.json`.

```
ddev composer install
```

*After changes to `Plugin.php`, `ddev composer install` must be run again — a `cache:clear` is not sufficient.*

---

### Configuration &amp; Usage

[](#configuration--usage)

#### Backend Operation

[](#backend-operation)

1. **Create content element:** In the article section, create a new content element of type **FAQ (Structured Data)** (category: *Texts*).
2. **Manage questions and answers:** In the *FAQ Entries* section, add any number of question-answer pairs. Answers support rich text (TinyMCE).
3. **Select template:** Use the *Custom Template* field (`customTpl`) to choose one of the three variants. Without selection, the Handorgel template is used.

#### Available Backend Fields

[](#available-backend-fields)

FieldTypeDescription`faqItems`Group widgetRepeatable question-answer pairs`faqQuestion`TextQuestion text (max. 512 characters, required)`faqAnswer`Textarea (RTE)Answer text with TinyMCE editor (required)---

### Template Variants

[](#template-variants)

VariantFileCSS/JS DependencyBehavior**Handorgel** (default)`faq_structured.html.twig``contao-components/handorgel` (CSS + JS, automatically included)First item open, only one item at a time (`multiSelectable: false`)**Bootstrap 5**`faq_structured/bootstrap.html.twig`Bootstrap 5 must be available in the projectAccordion with `data-bs-toggle="collapse"`, first item open**Tailwind CSS**`faq_structured/tailwind.html.twig`Tailwind CSS must be available in the projectNative ``/`` element, no JavaScript, first item open#### Template Selection Guide

[](#template-selection-guide)

- **Handorgel:** Standalone solution without framework dependency. Suitable for projects without a CSS framework.
- **Bootstrap 5:** When the project already uses Bootstrap 5. Seamless integration with existing accordion styling.
- **Tailwind CSS:** Minimal footprint, no JavaScript. Uses native browser behavior (``). Ideal for Tailwind projects.

---

### Schema.org / SEO

[](#schemaorg--seo)

The bundle automatically generates **FAQPage JSON-LD** for each FAQ element. The structure is inserted into the `` via Contao's `add_schema_org()` function in the template's `metadata` block.

#### Example Output

[](#example-output)

```
{
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
        {
            "@type": "Question",
            "name": "What is Contao?",
            "acceptedAnswer": {
                "@type": "Answer",
                "text": "Contao is an open-source content management system."
            }
        }
    ]
}
```

#### Allowed HTML Tags in Answers (JSON-LD)

[](#allowed-html-tags-in-answers-json-ld)

In the JSON-LD output, answers are sanitized with `strip_tags()`. The following tags are preserved:

``, ``, ``, ``, ``, ``, ``, ``, ``, ``

#### Google Rich Results

[](#google-rich-results)

- FAQPage markup enables **FAQ Rich Results** in Google Search (expandable questions directly in the search result).
- Validation via the [Google Rich Results Test Tool](https://search.google.com/test/rich-results).

---

### Important Notes

[](#important-notes)

- **Dependency `mvo/contao-group-widget`:** The bundle uses the `inputType` `group` for repeatable field groups. Without this package, the backend form will not work.
- **Cache:** After changes to FAQ content, the page cache must be refreshed for the updated JSON-LD data to be served.
- **Empty entries:** Question-answer pairs without a question or answer are automatically filtered out and appear neither in the frontend nor in the JSON-LD.
- **`.twig-root` file:** The file `contao/templates/twig/.twig-root` is mandatory for Contao to correctly recognize the template variants.
- **Extensibility:** Custom template variants can be added as subfolder templates under `contao/templates/twig/content_element/faq_structured/`. Alternatively, templates can be overridden in the project under `templates/`.

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance97

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

16d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c9898678b6cfea03538cf5c2d1cdb150535d82dd5727dc4052abcc56ff3861a4?d=identicon)[avh](/maintainers/avh)

### Embed Badge

![Health badge](/badges/avh-contao-faq-structured-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/avh-contao-faq-structured-bundle/health.svg)](https://phpackages.com/packages/avh-contao-faq-structured-bundle)
```

###  Alternatives

[plenta/contao-jobs-basic-bundle

Basic Job Manager for Contao (including Google Jobs).

314.8k](/packages/plenta-contao-jobs-basic-bundle)[inspiredminds/contao-fieldset-duplication

Contao extension to allow the duplication of form fieldsets in the front end by the user for additional input fields.

138.0k1](/packages/inspiredminds-contao-fieldset-duplication)[tastaturberuf/anystores

Location management and geographic search

121.7k](/packages/tastaturberuf-anystores)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
