You too can become a hero and support this Blog at GitHub Sponsors or Patreon.

More about support

Icons, Icons, Icons

As you may have noticed the general look of the TYPO3 backend got a big improvement with the 7 LTS release. Alongside the introduction of Bootstrap all icons had been reworked. Yes that's right: All icons had been reworked. By hand. In shiny SVG. They can be viewed, improved and starred on Github. There also is a nice overview where you can even filter through all existing icons: typo3.github.io/TYPO3.Icons.

So before we take a look at the icon API, we pause for a second and applaud all people that have been involved in that task!

A small portion of the TYPO3 icons.
A small portion of the TYPO3 icons.

Top

The Icon-API

To unify the handling and markup of icons throughout the backend a new API was introduced that handles the registering and rendering of all icons (Feature RST). The core uses the API for all its icons and extension developers are encouraged to adapt this practice for their backend modules. Using the API is not very complicated. First you register an icon in the IconRegistry, then you can use it with the IconFactory or a ViewHelper.

Top

Registering an Icon (since TYPO3 v11)

Since TYPO3 11

To use a custom icon in the TYPO3 backend it has to be registered in the class \TYPO3\CMS\Core\Imaging\IconRegistry.

We need to know at least two things about every icon. The identifier of the icon and the name of the IconProvider class we want to use.

  • The identifier is a unique string that identifies exactly one icon. Take whatever name you like. Prefix it with your extension name to be save and prevent naming conflicts.
  • The IconProvider is a class that generates the correct markup for a specific icon type. The core ships three providers: BitmapIconProvider, SvgIconProvider and the FontawesomeIconProvider.

If you want to register a simple image file (jpg, gif, png) as an icon you go with the BitmapIconProvider.

Since TYPO3 v11 icons are registered in the file Configuration/Icons.php. Let's look at an example:

<?php
return [
    'proof-of-concept' => [
        'provider' => \TYPO3\CMS\Core\Imaging\IconProvider\FontawesomeIconProvider::class,
        'name' => 'spinner',
        'spinning' => true
    ],
    'tx-fs-code-snippet' => [
        'provider' => \TYPO3\CMS\Core\Imaging\IconProvider\BitmapIconProvider::class,
        'source' => 'EXT:my_extension/Resources/Public/Icons/code-snippet-icon.png'
    ],
];

Before the introduction of the ServiceProvider that collects the Configuration/Icon.php files from all extensions (Patch, Feature RST) in TYPO3 v11 LTS, the registration had to be done differently:

Top

Registering an Icon (up to TYPO3 v10)

The following information is only valid up to TYPO3 v10. For TYPO3 v11 and upward, please refer to the section above.

Since there is no ServiceProvider before TYPO3 v11, we need to register the icons ourselves by calling registerIcon() on an instance of the IconRegistry.

$iconRegistry = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Imaging\IconRegistry::class);
$iconRegistry->registerIcon(
  'tx-fs-code-snippet',
  \TYPO3\CMS\Core\Imaging\IconProvider\BitmapIconProvider::class,
  ['source' => 'EXT:' . $extKey . '/Resources/Public/Images/code-snippet-icon.png']
);

This code is best put into the ext_localconf.php. It registers an image (code-snippet-icon.png) with the identifier tx-fs-code-snippet. This identifier can now be used troughout the backend. But before we take a look at the usage let's see how we use the FontawesomeIconProvider:

$iconRegistry = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Imaging\IconRegistry::class);
$iconRegistry->registerIcon(
    'proof-of-concept',
    \TYPO3\CMS\Core\Imaging\IconProvider\FontawesomeIconProvider::class,
    [
        'name'     => 'spinner',
        'spinning' => true
    ]
);

If we use the BitmapIconProvider or the SvgIconProvider we have to specify the source of the icon while the FontawesomeIconProvider expects the name of the Font Awesome CSS class we want to use (but without the fa- prefix). All IconProviders however can take the additional option spinning to ... you guessed it ... make the icon spin.

So much for registering an icon. But how do we use it?

Top

Using an Icon

There are many places in the core where we just need the identifier to render an icon. in the TCA for example you specify a new typeicon like this:

$GLOBALS['TCA']['tt_content']['ctrl']['typeicon_classes']['fs_code_snippet'] = 'tx-fs-code-snippet';

But if we need our icon markup in our PHP code, we can always use an instance of  the \TYPO3\CMS\Core\Imaging\IconFactory. By passing our identifer to the method getIcon(), we get an instance of Icon. To modify the markup of the method Icon->render(), we can optionally determine

  • size (2nd argument) with the constants Icon::SIZE_SMALL (16px), Icon::SIZE_DEFAULT (32px) and Icon::SIZE_LARGE (48px),
  • an overlay icon (3rd argument) by its identifier and
  • the state of  the icon (4th argument) with the Enumeration constants IconState::STATE_DEFAULT and IconState::STATE_DISABLED. Note that the method expects an instance of the IconState class. So you have to cast the constant to such an instance: IconState::cast(IconState::STATE_DISABLED).
$iconFactory = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Imaging\IconFactory::class);
$icon = $iconFactory->getIcon(
  'tx-fs-code-snippet',
  \TYPO3\CMS\Core\Imaging\Icon::SIZE_SMALL,
  'overlay-identifier',
  \TYPO3\CMS\Core\Type\Icon\IconState::cast(\TYPO3\CMS\Core\Type\Icon\IconState::STATE_DISABLED)
);
$iconMarkup = $icon->render();

There also is a Fluid ViewHelper (\TYPO3\CMS\Core\ViewHelpers\IconViewHelper) that takes all these arguments as well and renders our icon within our Fluid template: 

<html xmlns:core="http://typo3.org/ns/TYPO3/CMS/Core/ViewHelpers" data-namespace-typo3-fluid="true">
  <core:icon identifier="tx-fs-code-snippet" size="small" overlay="overlay-identifier" state="disabled" />
</html>

And that is everything you need to know about the Icon-API of TYPO3.

Top

Further Information