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