Skip to content

Commit eda3c69

Browse files
froemkenlinawolf
froemken
and
linawolf
authored
Update documentation about JS multi-step wizard (#5488)
* Update documentation about JS multi-step wizard * Update Documentation/ApiOverview/Backend/JavaScript/Modules/MultiStepWizard.rst Co-authored-by: Lina Wolf <[email protected]> * Move JS part into its own file --------- Co-authored-by: Lina Wolf <[email protected]>
1 parent 3db29fb commit eda3c69

File tree

2 files changed

+175
-35
lines changed

2 files changed

+175
-35
lines changed

‎Documentation/ApiOverview/Backend/JavaScript/Modules/MultiStepWizard.rst‎

Lines changed: 137 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,142 @@
1-
.. include:: /Includes.rst.txt
2-
.. index:: JavaScript (Backend); Multi-step wizard
3-
.. _modules-multistepwizard:
1+
.. include:: /Includes.rst.txt
2+
.. index:: JavaScript (Backend); Multi-step wizard
3+
.. _modules-multistepwizard:
44

55
=================
66
Multi-step wizard
77
=================
88

9-
The JavaScript module :js:`MultiStepWizard` can be used to show a modal multi-step
10-
wizard with the following features:
11-
12-
* Navigation to previous / next steps
13-
* Steps may have descriptive labels like "Start" or "Finish!"
14-
* Steps may require actions before becoming available.
15-
16-
Code examples:
17-
18-
.. code-block:: js
19-
20-
// Show/ hide the wizard
21-
MultiStepWizard.show();
22-
MultiStepWizard.dismiss();
23-
24-
// Add a slide to the wizard
25-
MultiStepWizard.addSlide(
26-
identifier,
27-
stepTitle,
28-
content,
29-
severity,
30-
progressBarTitle,
31-
function() {
32-
...
33-
}
34-
);
35-
36-
// Lock/ unlock navigation buttons
37-
MultiStepWizard.lockNextStep();
38-
MultiStepWizard.unlockNextStep();
39-
MultiStepWizard.lockPrevStep();
40-
MultiStepWizard.unlockPrevStep();
9+
The JavaScript module :js:`MultiStepWizard` can be used to show a modal
10+
multi-step wizard with the following features:
11+
12+
* Navigation to previous / next steps
13+
* Steps may have descriptive labels like "Start" or "Finish!"
14+
* Steps may require actions before becoming available.
15+
16+
.. _modules-multistepwizard-addslide:
17+
18+
Add Slide
19+
=========
20+
21+
You have to define at least one slide :javascript:`MultiStepWizard.addSlide()`.
22+
23+
.. confval-menu::
24+
:name: multi-step-wizard-settings
25+
:display: table
26+
:type:
27+
28+
.. confval:: identifier
29+
:name: multi-step-wizard-settings-identifier
30+
:Required: true
31+
:type: string
32+
33+
A unique identifier for the slide
34+
35+
.. confval:: title
36+
:name: multi-step-wizard-settings-title
37+
:Required: true
38+
:type: string
39+
40+
The title of the slide. Will be shown as header of the slide.
41+
42+
.. confval:: content
43+
:name: multi-step-wizard-settings-content
44+
:Required: true
45+
:type: string|JQuery|Element|DocumentFragment
46+
47+
The content of the slide. If `string` any HTML will be escaped. To
48+
prevent that, chose one of the other allowed types:
49+
50+
**JQuery**:
51+
52+
.. code-block:: js
53+
54+
$(`<div>Your HTML content</div>`);
55+
56+
**Element**:
57+
58+
.. code-block:: js
59+
60+
Object.assign(document.createElement('div'), {
61+
innerHTML: 'Your HTML content'
62+
});
63+
64+
**DocumentFragment**:
65+
66+
.. code-block:: js
67+
68+
document.createRange().createContextualFragment("<div>Your HTML content</div>");
69+
70+
.. confval:: severity
71+
:name: multi-step-wizard-settings-severity
72+
:Required: true
73+
:type: SeverityEnum
74+
75+
Set severity color for sheet. Color will only affect title bar and
76+
prev- and next-buttons.
77+
78+
.. confval:: progressBarTitle
79+
:name: multi-step-wizard-settings-progressBarTitle
80+
:Required: true
81+
:type: string
82+
83+
Set a title for the progress bar. The progress bar will only be shown
84+
below the content section of the slide, if you have defined at least
85+
two or more slides.
86+
87+
.. confval:: callback
88+
:name: multi-step-wizard-settings-callback
89+
:Required: true
90+
:type: SlideCallback
91+
92+
A JavaScript callback function which will be called after the slide was
93+
rendered completely.
94+
95+
.. _modules-multistepwizard-show-hide-wizard:
96+
97+
Show / Hide Wizard
98+
==================
99+
100+
After defining some slides you can show
101+
:javascript:`MultiStepWizard.show()` and hide
102+
:javascript:`MultiStepWizard.dismiss()` the multi-step wizard.
103+
104+
.. _modules-multistepwizard-lock-unlock-wizard:
105+
106+
Lock/Unlock steps
107+
=================
108+
109+
Switching to the next or previous slides is called a `step`. The buttons
110+
to navigate to the slides are deactivated by default. Please use following
111+
methods to lock or unlock them:
112+
113+
.. code-block:: js
114+
115+
MultiStepWizard.lockNextStep();
116+
MultiStepWizard.unlockNextStep();
117+
MultiStepWizard.lockPrevStep();
118+
MultiStepWizard.unlockPrevStep();
119+
120+
.. _modules-multistepwizard-full-example:
121+
122+
"Hello world" Example
123+
=====================
124+
125+
This JavaScript snippet will create a new multi-step wizard with just one
126+
sheet. As it used :javascript:`SeverityEnum.warning` the title and buttons
127+
will be colored in yellow.
128+
129+
.. literalinclude:: _Modals/_multi-step-wizard.js
130+
:language: javascript
131+
:caption: EXT:my_extension/Resources/Public/JavaScript/HelloWorldModule.js
132+
133+
To call the JavaScript from above you have to use the
134+
:ref:`JavaScriptModuleInstruction<backend-javascript-es6-loading>`) technique.
135+
In following snippet you see how to add a JavaScript module to field within
136+
:ref:`Form Engine<FormEngine>`:
137+
138+
.. code-block:: js
139+
140+
$resultArray['javaScriptModules'][] = JavaScriptModuleInstruction::create(
141+
'@stefanfroemken/dropbox/AccessTokenModule.js'
142+
)->instance($fieldId);

‎Documentation/ApiOverview/Backend/JavaScript/Modules/_MultiStepWizard/_multi-step-wizard.js‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
import {SeverityEnum} from "@typo3/backend/enum/severity.js"
2+
import MultiStepWizard from "@typo3/backend/multi-step-wizard.js"
3+
import $ from "jquery";
4+
5+
export default class HelloWorldModule {
6+
constructor(triggerHelloWorldWizardButtonClass) {
7+
const buttons = document.querySelectorAll("." + triggerHelloWorldWizardButtonClass);
8+
9+
buttons.forEach((button) => {
10+
button.addEventListener("click", () => {
11+
MultiStepWizard.addSlide(
12+
"UniqueHelloWorldIdentifier",
13+
"Title of the Hello World example slide",
14+
document.createRange().createContextualFragment("<div>Hello world</div>"),
15+
SeverityEnum.warning,
16+
"Step Hello World",
17+
function ($slide) {
18+
let $modal = $slide.closest(".modal");
19+
let $nextButton = $modal.find(".modal-footer").find("button[name='next']");
20+
MultiStepWizard.unlockNextStep();
21+
22+
$nextButton.off().on("click", function () {
23+
// Process whatever you want from current slide, just before wizard will be closed or next slide
24+
25+
// Close wizard
26+
MultiStepWizard.dismiss();
27+
28+
// Go to next slide, if any
29+
// MultiStepWizard.setup.$carousel.carousel("next");
30+
});
31+
}
32+
);
33+
34+
MultiStepWizard.show();
35+
});
36+
});
37+
}
38+
}

0 commit comments

Comments
 (0)