Attention
TYPO3 v10 has reached end-of-life as of April 30th 2023 and is no longer being maintained. Use the version switcher on the top left of this page to select documentation for a supported version of TYPO3.
Need more time before upgrading? You can purchase Extended Long Term Support (ELTS) for TYPO3 v10 here: TYPO3 ELTS.
System Categories¶
Since version 6.0, TYPO3 CMS provides a generic categorization system. Categories can be created in the backend like any other type of record. Any table can be made categorizable and thus be attached to system categories.
Since version 6.2, pages, content elements and files are categorizable by default.
Using Categories¶
Managing Categories¶
System categories are defined just like any other record. Each category can have a parent, making for a tree-like structure.

A category with a parent defined¶
The "items" tab shows all related records, i.e. all records that have been marked as belonging to this category.
Making a Table Categorizable¶
There are two ways to activate categories on a given table. The first one is to
use the global setting $GLOBALS['TYPO3_CONF_VARS']['SYS']['defaultCategorizedTables']
.
It is a comma-separated list of tables for which categories should be activated.
The default value is pages,tt_content,sys_file_metadata
.
Important
It is recommended to avoid changing this setting. You should rather use the API described just below so as to avoid overriding a default which may change in future versions of TYPO3 CMS. The API is also more powerful.
The second way is to call \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::makeCategorizable()
.
This method adds a new entry into the registry managed by \TYPO3\CMS\Core\\Category\CategoryRegistry
.
The registry will take care of adding the relevant $TCA definition to
create a field for making relations to the system categories.
The call to makeCategorizable()
must be located in an extension's
Configuration/TCA/Overrides
folder (or ext_tables.php
file before TYPO3 CMS 6.2.1).
The default $GLOBALS['TCA']
structure provided by the registry
can be overridden by an array options passed to makeCategorizable()
.
The example below illustrates how this is done:
// Add an extra categories selection field to the pages table
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::makeCategorizable(
'examples',
'pages',
// Do not use the default field name ("categories") for pages, tt_content, sys_file_metadata, which is already used
'tx_examples_cats',
array(
// Set a custom label
'label' => 'LLL:EXT:examples/Resources/Private/Language/locallang.xlf:additional_categories',
// This field should not be an exclude-field
'exclude' => FALSE,
// Override generic configuration, e.g. sort by title rather than by sorting
'fieldConfiguration' => array(
'foreign_table_where' => ' AND {#sys_category}.{#sys_language_uid} IN (-1, 0) ORDER BY sys_category.title ASC',
),
// string (keyword), see TCA reference for details
'l10n_mode' => 'exclude',
// list of keywords, see TCA reference for details
'l10n_display' => 'hideDiff',
)
);
The above code will add a categories field to the "pages" table,
which will be called tx_examples_cats
. The fieldConfiguration
part of the options array is the one which overrides the base
$TCA
structure. In this case we would like categories to be
listed alphabetically instead of using the "sorting" field.
If no label
part is set in the options array, the field will
be labeled "Categories".
By default, the field will be an exclude-field. The exclude
part
can be used to override this.
This is the result of the above code:

The newly added field to define relations to categories (on top of the default one)¶
Using Categories in FlexForms¶
It is possible to create relations to categories also in Flexforms, although this has to be done manually since no API exists for this.
The code will look something like:
<settings.categoriesList>
<TCEforms>
<exclude>1</exclude>
<label>Categories:</label>
<config>
<type>select</type>
<autoSizeMax>50</autoSizeMax>
<foreign_table>sys_category</foreign_table>
<foreign_table_where> AND {#sys_category}.{#sys_language_uid} IN (-1, 0) ORDER BY sys_category.sorting ASC</foreign_table_where>
<MM>sys_category_record_mm</MM>
<MM_opposite_field>items</MM_opposite_field>
<MM_match_fields>
<tablenames>tt_content</tablenames>
<fieldname>tx_myextension_categories</fieldname>
</MM_match_fields>
<maxitems>9999</maxitems>
<renderMode>tree</renderMode>
<size>10</size>
<treeConfig>
<appearance>
<expandAll>1</expandAll>
<showHeader>1</showHeader>
</appearance>
<parentField>parent</parentField>
</treeConfig>
</config>
</TCEforms>
</settings.categoriesList>
Properties tablenames
and fieldname
would need
to be adjusted.
System Categories API¶
Beyond makeCategorizable()
, class
\TYPO3\CMS\Core\Category\CategoryRegistry
has many other methods related to the management of
categorized table. The best way to discover is to follow
the link above and explore the methods provided by this class.
They are all quite specialized and should not be needed
most of the time.
Category Collections¶
The \TYPO3\CMS\Core\Category\Collection\CategoryCollection
class provides the API for retrieving records related
to a given category. Since TYPO3 CMS 6.2, it is extended by class
\TYPO3\CMS\Frontend\Category\Collection\CategoryCollection
which does the same job but in the frontend, i.e.
respecting all enable fields and performing version
and language overlays.
The main method is load()
which will return a
traversable list of items related to the given category.
Here is an example usage, taken from the RECORDS content object:
$collection = \TYPO3\CMS\Frontend\Category\Collection\CategoryCollection::load(
$aCategory,
TRUE,
$table,
$relationField
);
if ($collection->count() > 0) {
// Add items to the collection of records for the current table
foreach ($collection as $item) {
$tableRecords[$item['uid']] = $item;
// Keep track of all categories a given item belongs to
if (!isset($categoriesPerRecord[$item['uid']])) {
$categoriesPerRecord[$item['uid']] = array();
}
$categoriesPerRecord[$item['uid']][] = $aCategory;
}
}
As all collection classes in the TYPO3 CMS Core implement the
Iterator interface, it is also possible to use expected methods like
next()
, rewind()
, etc. Note that methods such as
add()
will only add items to the collection temporarily.
The relations are not persisted in the database.
Usage With TypoScript¶
(since TYPO3 CMS 6.2)
In the frontend, it is possible to get collections of categorized records loaded into a RECORDS content object for rendering. Check out the categories property.
The HMENU object also has a "categories" special type, to display a menu based on categorized pages.
User permissions for system categories¶
In most aspects system categories are treated like any other record. They can
be viewed or edited by editors if they are stored in a folder where the editor
has access to and if the table sys_category
is allowed in the field
Tables (listing) and Tables (modify) in the tab
Access Lists of the user group.
Additionally it is possible to set Mounts and Workspaces > Category Mounts in the user group. If at least one category is set in the category mounts only the chosen categories are allowed to be attached to records.