1 2.. include:: ../../Includes.txt 3 4==================================================================================== 5Feature: #68741 - Introduce new IconFactory as base to replace the icon skinning API 6==================================================================================== 7 8See :issue:`68741` 9 10Description 11=========== 12 13The logic for working with icons, icon sizes and icon overlays is now bundled into the new `IconFactory` class. 14The new icon factory will replace the old icon skinning API step by step. 15 16All core icons will be registered directly in the `IconRegistry` class, third party extensions must use 17`IconRegistry::registerIcon()` to override existing icons or add additional icons to the icon factory. 18 19The `IconFactory` takes care of the correct icon and overlay size and the markup. 20 21 22IconProvider 23------------ 24 25The core implements three icon provider classes, which all implement the `IconProviderInterface`. 26 27* `BitmapIconProvider` for all kind of bitmap icons for gif, png and jpg files 28* `FontawesomeIconProvider` for font icons from fontawesome.io 29* `SvgIconProvider` for svg icons 30 31Third party extensions can provide own icon provider classes, each class must implement the `IconProviderInterface`. 32 33 34BitmapIconProvider 35------------------ 36 37The `BitmapIconProvider` has the following option 38 39* `source` The path to the bitmap file, this may also contain the EXT: prefix 40 41 42FontawesomeIconProvider 43----------------------- 44 45The `FontawesomeIconProvider` has the following option 46 47* `name` The name of the icon without the icon prefix e.g. `check` instead of `fa-check` 48 49 50SvgIconProvider 51--------------- 52 53The `SvgIconProvider` has the following option 54 55* `source` The path to the svg file, this may also contains the EXT: prefix 56 57 58Register an icon 59---------------- 60 61.. code-block:: php 62 63 /* 64 * Put the following code into your ext_localconf.php file of your extension. 65 * 66 * @param string $identifier the icon identifier 67 * @param string $iconProviderClassName the icon provider class name 68 * @param array $options provider specific options, please reference the icon provider class 69 */ 70 $iconRegistry = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Imaging\IconRegistry::class); 71 $iconRegistry->registerIcon($identifier, $iconProviderClassName, array $options = array()); 72 73 74Use an icon 75----------- 76 77To use an icon, you need at least the icon identifier. The default size is currently 32x32 px. 78The third parameter can be used to add an additional icon as overlay, which can be any registered icon. 79 80The `Icon` class provides only the following constants for Icon sizes: 81 82* `Icon::SIZE_SMALL` which currently means 16x16 px 83* `Icon::SIZE_DEFAULT` which currently means 32x32 px 84* `Icon::SIZE_LARGE` which currently means 48x48 px 85 86All the sizes can change in future, so please make use of the constants for an unified layout. 87 88.. code-block:: php 89 90 $iconFactory = GeneralUtility::makeInstance(IconFactory::class); 91 $iconFactory->getIcon($identifier, Icon::SIZE_SMALL, $overlay)->render(); 92 93 94ViewHelper 95---------- 96 97The core provides a fluid ViewHelper which makes it really easy to use icons within a fluid view. 98 99.. code-block:: html 100 101 {namespace core=TYPO3\CMS\Core\ViewHelpers} 102 <core:icon identifier="my-icon-identifier" /> 103 <!-- use the "small" size if none given -> 104 <core:icon identifier="my-icon-identifier" /> 105 <core:icon identifier="my-icon-identifier" size="large" /> 106 <core:icon identifier="my-icon-identifier" overlay="overlay-identifier" /> 107 <core:icon identifier="my-icon-identifier" size="default" overlay="overlay-identifier" /> 108 <core:icon identifier="my-icon-identifier" size="large" overlay="overlay-identifier" /> 109 110 111Impact 112====== 113 114No impact 115 116 117.. index:: PHP-API, Backend, Fluid 118