8f725621adec7562b9ec7d61d7e5660840d2a614
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / master / Feature-70583-IntroducedIconAPIInJavaScript.rst
1 ===================================================
2 Feature: #70583 - Introduced Icon API in JavaScript
3 ===================================================
4
5 Description
6 ===========
7
8 A JavaScript-based icon API based on the PHP API has been introduced. The methods ``getIcon()``
9 and ``getIcons()`` can be called in an RequireJS module.
10
11 When imported in a RequireJS module, a developer can fetch icons via JavaScript with the same parameters as in PHP.
12 The methods ``getIcon()`` and ``getIcons()`` return ``Promise`` objects.
13
14 Importing
15 =========
16
17 .. code-block:: javascript
18
19         define(['jquery', 'TYPO3/CMS/Backend/Icons'], function($, Icons) {
20         });
21
22
23 Get icons
24 =========
25
26 A single icon can be fetched by ``getIcon()`` which takes four parameters:
27
28 .. container:: table-row
29
30    identifier
31          The icon identifier.
32
33    size
34          The size of the icon. Please use the properties of the ``Icons.sizes`` object.
35
36    overlayIdentifier
37          An overlay identifier rendered on the icon.
38
39    state
40          The state of the icon. Please use the properties of the ``Icons.states`` object.
41
42
43 Multiple icons can be fetched by ``getIcons()``. This function takes a multidimensional array as parameter,
44 holding the parameters used by ``getIcon()`` for each icon.
45
46 To use the fetched icons, chain the ``done()`` method to the promise.
47
48 Examples
49 --------
50
51 .. code-block:: javascript
52
53         // Get a single icon
54         Icons.getIcon('spinner-circle-light', Icons.sizes.small).done(function(icons) {
55                 $toolbarItemIcon.replaceWith(icons['spinner-circle-light']);
56         });
57
58         // Get multiple icons
59         Icons.getIcons([
60                 ['apps-filetree-folder-default', Icons.sizes.large],
61                 ['actions-edit-delete', Icons.sizes.small, null, Icons.states.disabled],
62                 ['actions-system-cache-clear-impact-medium']
63         ]).done(function(icons) {
64                 // icons['apps-filetree-folder-default']
65                 // icons['actions-edit-delete']
66                 // icons['actions-system-cache-clear-impact-medium']
67         });