Download the PHP package maikschneider/category-tree without Composer

Category Tree

A reusable category tree navigation component for TYPO3 backend modules — plus an optional backend module for managing categories.

Any backend module can declare the tree as its navigation component. Selecting a node reloads the module with a category=<uid> query parameter; what the module does with that is entirely up to the module. The tree itself handles creating, renaming, moving, copying, deleting and searching sys_category records.

Installation

That is all that is needed for the navigation component. The Web > Categories module is registered automatically and can be switched off in the extension configuration.

Using the tree in your own module

Declare it as the navigationComponent of your module in Configuration/Backend/Modules.php:

Then read the selected category in your controller:

That is the entire contract. The tree keeps the rest of your module's query parameters intact when the selection changes, so paging, filters and sorting survive a click in the tree.

Extbase modules

Extbase modules work the same way; read the parameter from the request:

Filtering a record list by the selected category

Categories are attached to records through the sys_category_record_mm table. A minimal constraint for a list query looks like this:

The optional category management module

Enabled by default. It appears as Web > Categories and exists purely to manage the tree: create, rename, move and delete categories via the tree, and edit the selected category in the regular TYPO3 record form (record_edit). Closing the form returns to the module.

Switch it off in the extension configuration (enableCategoryModule = 0) if you only want the navigation component.

Configuration

All settings live in the extension configuration (Admin Tools > Settings > Extension Configuration > category_tree):

Entry points that do not exist are silently skipped, so a stale UID cannot empty the tree.

Settings are resolved per module, so two modules can render the tree with different entry points, depth or root node — see Documentation/ModuleSettings.md.

See Documentation/EntryPoints.md for resolving entry points dynamically, and Documentation/Events.md for decorating tree nodes with badges and labels.

Permissions

Reading the tree is not permission filtered — like TYPO3's own category selector, every backend user sees the category hierarchy. Writing is gated twice: the toolbar's create/edit/delete affordances only appear when the user has tables_modify access to sys_category, and every write goes through DataHandler, which enforces record level access regardless of what the frontend allows.

Development

The repository ships a DDEV setup with a complete TYPO3 installation, so a working backend is three commands away:

ddev init-typo3 drops the database, installs TYPO3, creates a site and an admin user, and imports the functional test fixtures as demo content — a small category tree with nested, hidden and translated records. It prints the backend URL when it finishes. Override the admin credentials with TYPO3_SETUP_ADMIN_USERNAME / TYPO3_SETUP_ADMIN_PASSWORD if the defaults do not suit you. Re-run it any time you want a clean slate.

Frontend build

The compiled JavaScript in Resources/Public/JavaScript/ is committed, because TYPO3 serves it directly. CI fails if it is out of sync with the TypeScript source, so run npm run build whenever you touch Resources/Private/TypeScript.

After rebuilding, run ddev exec vendor/bin/typo3 cache:flush and hard-reload the backend (Cmd/Ctrl + Shift + R) — the browser caches the module under an unchanged URL and will otherwise keep running the previous bundle.

Quality gate

PHPStan runs at level 7 with an empty baseline. Functional tests use typo3/testing-framework and need database credentials that may create and drop databases; .ddev/config.yaml provides them. The acceptance tests drive the real backend and need ddev init-typo3 to have run — see Tests/Playwright/README.md.

Documentation

• Per-module settings — giving a module its own entry points, exclusions, root node, depth or hidden-category handling
• Entry points — where the tree starts, and how to resolve it dynamically
• Events — decorating tree nodes

Credits

Modelled on TYPO3's own page tree.