System categories

TYPO3 CMS provides a generic categorization system. Categories can be created in the backend like any other type of record.

A TCA field of the column type category

Pages, content elements and files contain category fields by default.

Changed in version 11.4: Starting with v11.4 the formerly used php function ExtensionManagementUtility::makeCategorizable() is deprecated. Use a TCA field of the type category instead.

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.

../../_images/Editing.png

A category with a parent defined

The “items” tab shows all related records, for example all records that have been marked as belonging to this category.

Adding categories to a table

Deprecated since version 11.4: Starting with v11.4 Defining category fields for tables with $GLOBALS['TYPO3_CONF_VARS']['SYS']['defaultCategorizedTables'] or by calling ExtensionManagementUtility::makeCategorizable() is deprecated.

Categories can be added to a table by defining a TCA field of the TCA column type category. While using this type, TYPO3 takes care of generating the necessary TCA configuration and also adds the database column automatically. Developers only have to configure the TCA column and add it to the desired record types:

$GLOBALS['TCA'][$myTable]['columns']['categories'] = [
   'config' => [
      'type' => 'category'
   ]
];

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addToAllTCAtypes(
   $myTable,
   'categories'
);

This is the result of the above code:

../../_images/AddingWithApi.png

The newly added field to define relations to categories

Using categories in FlexForms

It is possible to create relations to categories also in Flexforms.

Due to some limitations in FlexForm, the property relationship manyToMany is not supported. Therefore, the default value for this property is oneToMany.

<T3DataStructure>
    <ROOT>
        <TCEforms>
            <sheetTitle>aTitle</sheetTitle>
        </TCEforms>
        <type>array</type>
        <el>
            <categories>
                <TCEforms>
                    <config>
                        <type>category</type>
                    </config>
                </TCEforms>
            </categories>
        </el>
    </ROOT>
</T3DataStructure>

System categories API

Deprecated since version 11.4: Starting with v 11.4 the API function ExtensionManagementUtility::makeCategorizable() and the class CategoryRegistry have been deprecated. Use a TCA field of the type category instead.

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

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.