[TASK] Update tags for all rst files for 8.0
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / 8.0 / Feature-73429-WizardComponentHasBeenAdded.rst
1
2 .. include:: ../../Includes.txt
3
4 =================================================
5 Feature: #73429 - Wizard component has been added
6 =================================================
7
8 See :issue:`73429`
9
10 Description
11 ===========
12
13 A new wizard component has been added. This component may be used for user-guided interactions.
14 The RequireJS module can be used by including `TYPO3/CMS/Backend/Wizard`.
15
16 The wizard supports straight forward actions only, junctions are not possible yet.
17
18
19 Impact
20 ======
21
22 The wizard component has the following public methods:
23 #. :code:`addSlide(identifier, title, content, severity, callback)`
24 #. :code:`addFinalProcessingSlide(callback)`
25 #. :code:`set(key, value)`
26 #. :code:`show()`
27 #. :code:`dismiss()`
28 #. :code:`getComponent()`
29 #. :code:`lockNextStep()`
30 #. :code:`unlockNextStep()`
31
32 addSlide
33 ~~~~~~~~
34
35 Adds a slide to the wizard.
36
37 ========== =============== ============ ======================================================================================================
38 Name       DataType        Mandatory    Description
39 ========== =============== ============ ======================================================================================================
40 identifier string          Yes          The internal identifier of the slide
41 title      string          Yes          The title of the slide
42 content    string          Yes          The content of the slide
43 severity   int                          Represents the severity of a slide. Please see TYPO3.Severity. Default is :code:`TYPO3.Severity.info`.
44 callback   function                     Callback method run after the slide appeared. The callback receives two parameters:
45                                         :code:`$slide`: The current slide as a jQuery object
46                                         :code:`settings`: The settings defined via :js:`Wizard.set()`
47 ========== =============== ============ ======================================================================================================
48
49 addFinalProcessingSlide
50 ~~~~~~~~~~~~~~~~~~~~~~~
51
52 Adds a slide to the wizard containing a spinner. This should always be the latest slide. This method returns a Promise
53 object due to internal handling. This means you have to add a :js:`done()` callback containing :js:`Wizard.show()` and ,
54 :js:`Wizard.getComponent()` please see the example below.
55
56 ========== =============== ============ ======================================================================================================
57 Name       DataType        Mandatory    Description
58 ========== =============== ============ ======================================================================================================
59 callback   function                     Callback method run after the slide appeared. If no callback method is given, the wizard dismisses
60                                         without any further action.
61 ========== =============== ============ ======================================================================================================
62
63 Example code:
64
65 .. code-block:: js
66
67         Wizard.addFinalProcessingSlide().done(function() {
68             Wizard.show();
69
70             Wizard.getComponent().on('click', '.my-element', function(e) {
71                 e.preventDefault();
72                 $(this).doSomething();
73             });
74         });
75
76 set
77 ~~~
78
79 Adds values to the internal settings stack usable in other slides.
80
81 ========== =============== ============ ======================================================================================================
82 Name       DataType        Mandatory    Description
83 ========== =============== ============ ======================================================================================================
84 key        string          Yes          The key of the setting
85 value      string          Yes          The value of the setting
86 ========== =============== ============ ======================================================================================================
87
88 Events
89 ~~~~~~
90
91 The event `wizard-visible` is fired when the wizard rendering has finished.
92
93 Example code:
94
95 .. code-block:: js
96
97         Wizard.getComponent().on('wizard-visible', function() {
98             Wizard.unlockNextButton();
99         });
100
101
102 Wizards can be closed by firing the `wizard-dismiss` event.
103
104 Example code:
105
106 .. code-block:: js
107
108         Wizard.getComponent().trigger('wizard-dismiss');
109
110
111 Wizards fire the `wizard-dismissed` event if the wizard is closed. You can integrate your own listener by using :js:`Wizard.getComponent()`.
112
113 Example code:
114
115 .. code-block:: js
116
117         Wizard.getComponent().on('wizard-dismissed', function() {
118             // Calculate the answer of life the universe and everything
119         });
120
121 .. index:: Backend, JavaScript