AppSuite:Wizard framework: Difference between revisions
From Open-Xchange
m (→Events) |
m (→API) |
||
| Line 23: | Line 23: | ||
! Function !! Description | ! Function !! Description | ||
|- | |- | ||
| | | step(options) | ||
| Add a new wizard/tour step. | | Add a new wizard/tour step. | ||
|- | |- | ||
| | | start() | ||
| Start the wizard/tour | | Start the wizard/tour | ||
|- | |- | ||
| | | title() | ||
| Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function. | | Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function. | ||
|- | |- | ||
| | | content() | ||
| Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function. | | Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function. | ||
|- | |- | ||
| | | footer() | ||
| Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function. | | Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function. | ||
|- | |- | ||
| | | mandatory() | ||
| Makes a step mandatory. The "close" icon gets removed; escape key no longer works. | | Makes a step mandatory. The "close" icon gets removed; escape key no longer works. | ||
|- | |- | ||
| | | toggleNext(state) | ||
| Enables (true) or disables (false) the "Next" button | | Enables (true) or disables (false) the "Next" button | ||
|- | |- | ||
| | | toggleBack(state) | ||
| Enables (true) or disables (false) the "Back" button | | Enables (true) or disables (false) the "Back" button | ||
|- | |- | ||
| | | isFirst() | ||
| Returns true if the current step is the first one | | Returns true if the current step is the first one | ||
|- | |- | ||
| | | isLast() | ||
| Returns true if the current step is the last one | | Returns true if the current step is the last one | ||
|- | |- | ||
| | | pointAt(selector) | ||
| Affects the dialogs location (alignment happens automatically). | | Affects the dialogs location (alignment happens automatically). | ||
|- | |- | ||
| | | spotlight(selector) | ||
| Sets a spotlight on a given element | | Sets a spotlight on a given element | ||
|- | |- | ||
| | | modal([state]) | ||
| Shows a darker backdrop. Default is true. | | Shows a darker backdrop. Default is true. | ||
|- | |- | ||
| | | waitFor(selector) | ||
| The step waits for a certain element to exist before showing the popup. | | The step waits for a certain element to exist before showing the popup. | ||
|- | |- | ||
| | | navigateTo(id, [options]) | ||
| The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch(). | | The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch(). | ||
|- | |- | ||
| | | scrollIntoView(selector) | ||
| This element will be scrolled into view before the popup is shown | | This element will be scrolled into view before the popup is shown | ||
|- | |- | ||
| | | beforeShow(callback) | ||
| Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view. | | Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view. | ||
|- | |- | ||
| | | end() | ||
| Go back to parent element, i.e. the Wizard or the Tour. | | Go back to parent element, i.e. the Wizard or the Tour. | ||
|} | |} | ||
Revision as of 13:20, 15 July 2015
Wizard/Tour framework
App Suite UI provides a simple but flexible framework to implement wizards and guided tours. The essence of both a wizard and a tour is a set of steps the end-user walks through. Usually a step is a smaller modal popup.
Simple example
The starting point is the "Wizard" (or "Tour") class defined in io.ox/core/tk/wizard.js. A simple example:
require(['io.ox/core/tk/wizard'], function (Tour) {
new Tour()
.step()
.title('Welcome')
.content('Lorem ipsum dolor sit amet, consetetur sadipscing elitr')
.end()
.start();
});
The function step() adds a new step. Each step is separate Backbone view instance (DisposableView to be more precise). The following function calls title() and content() both work on that view; end() just returns to the tour (same idea as in jQuery's end()). This allows long definition chains.
API
| Function | Description |
|---|---|
| step(options) | Add a new wizard/tour step. |
| start() | Start the wizard/tour |
| title() | Append content to the popup title. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function. |
| content() | Append content the popup body. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function. |
| footer() | Append content to the popup footer. Handed over to jQuery's append; can be String, DOM element, jQuery set, a function. |
| mandatory() | Makes a step mandatory. The "close" icon gets removed; escape key no longer works. |
| toggleNext(state) | Enables (true) or disables (false) the "Next" button |
| toggleBack(state) | Enables (true) or disables (false) the "Back" button |
| isFirst() | Returns true if the current step is the first one |
| isLast() | Returns true if the current step is the last one |
| pointAt(selector) | Affects the dialogs location (alignment happens automatically). |
| spotlight(selector) | Sets a spotlight on a given element |
| modal([state]) | Shows a darker backdrop. Default is true. |
| waitFor(selector) | The step waits for a certain element to exist before showing the popup. |
| navigateTo(id, [options]) | The step launches given app (id) before showing the popup. "options" are optional; handed over to ox.launch(). |
| scrollIntoView(selector) | This element will be scrolled into view before the popup is shown |
| beforeShow(callback) | Registers for the "before:show" event using once(). The callback's context is the step, i.e. "this" is a backbone view. |
| end() | Go back to parent element, i.e. the Wizard or the Tour. |
Events
| Event name | Description |
|---|---|
| Wizard/Tour | |
| step:next | Triggered when moving ahead. |
| step:back | Triggered when moving back. |
| step:close | Triggered when closing the wizard/tour. |
| step:done | Triggered when finishing the wizard/tour. |
| before:start | Triggered before starting the wizard or the tour. |
| start | Triggered when the wizard or the tour has been started |
| before:stop | Triggered before closing the wizard or the tour. |
| stop | Triggered when the wizard or the tour has been closed |
| Step | |
| next / back | Same as step:next or step:back (see above) |
| close / done | Same as step:close or step:done (see above) |
| before:show | Triggered before showing the step |
| show | Triggered when the step is visible |
| before:hide | Triggered before hiding the step |
| hide | Triggered when the step is hidden |
Using the registry
Bla bla.