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.

Editing a category

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 new categories-relation field

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.