stepper.wizard

StepperWizard : d2/sdk/controls/dialogs/stepper.wizard

Create a modal wizard that navigates through a configured set of steps to achieve some arbitrary functionality. Steps can be navigated in a simple-sequential manner or on-demand hopping manner.

Extends: Marionette.View
Emits: wizard:shown, wizard:minimized, wizard:restored, wizard:closed, wizard:forceclose, step:before:active, dom:refresh, step:active, step:before:inactive, step:inactive
Example (Minimal configuration for a two-step wizard)

define([
 'nuc/lib/backbone',
 'nuc/lib/marionette',
 'd2/sdk/controls/dialogs/stepper.wizard'
 ],function(Backbone, Marionette, StepperWizard){
   'use strict';

   new StepperWizard({
     steps: [
       {
         id: 'first',
         viewClass: Marionette.View.extend({
           template: '<div>First Step View</div>'
         }),
         title: 'First Step Title',
       },
       {
         id: 'last',
         viewClass: Marionette.View.extend({
           template: '<div>Last Step View</div>'
         }),
         title: 'Last Step Title'
       }
    ]
  }).show();
});

Example (Sample 3-step wizard)

define([
 'nuc/lib/backbone',
 'nuc/lib/marionette',
 'd2/sdk/controls/dialogs/stepper.wizard'
],function(Backbone, Marionette, StepperWizard){
 'use strict';

 new StepperWizard({
   steps: [
     {
       id: 'first',
       viewClass: Marionette.View.extend({
         template: '<div>First Step View</div>'
       }),
       nextStepId: 'second',
       title: 'First Step Title',
       subTitle: 'First Step Subtitle'
     },
     {
       id: 'second',
       viewClass: Marionette.View.extend({
         template: '<div>Second Step View</div>'
       }),
       buttons: [
         {
           id: 'additional', //An extra button for second step
           label: 'Additional',
           align: 'begin',
           clickHandler: function(){
             console.log('additional button clicked at step 2');
           }
         }
       ],
       nextStepId: 'third',
       previousStepId: 'first',
       title: 'Second Step Title'
     },
     {
       id: 'third',
       viewClass: Marionette.View.extend({
         template: '<div>Third Step View</div>',
         onStepActive: function(){
           //Refresh all footer buttons
           this.options.wizard.refreshFooter();
         },
         isValid: function() {
           //some custom logic to determine the return value here will control 'disabled' state of the 'next' button
           return true;
         }
       }),
       buttons: [
         {
           id: 'next',
           label: 'Done',
           disabled: function() {
             // Enable/Disable the 'Done' button based on validation state after the step has become active
             return !this.isValid(); //'this' refers to the view instance of this step
           }
         }
       ],
       previousStepId: 'second',
       title: 'Third step title',
       subTitle: 'This is the last step'
     }
   ],
   data: { //This data will be shared accross all step views.
     model: new Backbone.Model({})
   }
 }).show();
});

• StepperWizard : d2/sdk/controls/dialogs/stepper.wizard
  • instance
    • .show([stepId]) ⇒ void
    • .close([...arg]) ⇒ void
    • .cancel([...arg]) ⇒ void
    • .minimize([promise], [notificationTooltip]) ⇒ Boolean
    • .restore()
    • .prevStep()
    • .nextStep()
    • .gotoStep(stepId, [animateFromEnd])
    • .refreshHeader()
    • .refreshFooter([...buttonId])
    • .getData() ⇒ *
    • .getId() ⇒ string
    • .blockActions()
    • .unblockActions()
    • "wizard:shown"
    • "wizard:minimized"
    • "wizard:restored"
    • "wizard:closed" (isCancel, [...args])
    • "wizard:forceclose"
    • "step:before:active"
    • "dom:refresh"
    • "step:active"
    • "step:before:inactive"
    • "step:inactive"
  • inner
    • ~StepperWizard
      • new StepperWizard(options)
    • ~StepConfig : object
    • ~ButtonConfig : object
    • ~StepCancellationCallback ⇒ jQuery.Promise | void
    • ~ButtonClickHandler ⇒ void

stepperWizard.show([stepId]) ⇒ void

Show the wizard after construction. The wizard becomes visible on screen only after this method is called.

Kind: instance method of StepperWizard
Note: By default the wizard shows up on the first step as specified in constructor options.

Param	Type	Description
[stepId]	string	Instead of starting from the first step, start from this particular step. If a matching step is not found the wizard disregards this parameter and starts from the first step.

stepperWizard.close([...arg]) ⇒ void

Close and finally destroy the wizard.

Kind: instance method of StepperWizard

Param	Type	Description
[...arg]	any	This method could be invoked with any number of parameters. All those parameters will be passed as event parameters for "wizard:closed" event.

stepperWizard.cancel([...arg]) ⇒ void

Try closing the wizard with a CANCEL signal. If the signal is not interfered with, it eventually causes the wizard to close and destroy itself.

Kind: instance method of StepperWizard

Param	Type	Description
[...arg]	any	All arguments that this method is invoked with, will be passed as event parameters for "wizard:closed"

stepperWizard.minimize([promise], [notificationTooltip]) ⇒ Boolean

Hide the wizard from screen without destroying it.

Kind: instance method of StepperWizard
Returns: Boolean - Returns true to indicate that the wizard is actually minimized. otherwise returns false.
Note: Only one wizard can be minimized with a notification, every other instance that tries to do the same at the same time will fail to minimize itself

Param	Type	Description
[promise]	jQuery.Promise	Whether or not the wizard needs to be minimized with a notification on the toolbar. Usually used when wizard is performing long-running background task on some step and it doesn't want to keep the end user blocked on the modal wizard. Resolve or reject the promise to change status of the notification icon.
[notificationTooltip]	string	What should be the tooltip of the notification icon if wizard is minimized with a notification

stepperWizard.restore()

Restore a minimized hidden wizard and bring it back on screen.

Kind: instance method of StepperWizard

stepperWizard.prevStep()

Go to previous step as determined by 'steps' configuration of the wizard

Kind: instance method of StepperWizard

stepperWizard.nextStep()

Go to next step as determined by 'steps' configuration of the wizard.

Kind: instance method of StepperWizard

stepperWizard.gotoStep(stepId, [animateFromEnd])

Go to specific step with given animation direction. Allows random jump from one step to another.

Kind: instance method of StepperWizard

Param	Type	Default	Description
stepId	string		Id of the step to go to
[animateFromEnd]	Boolean	true	Whether or not the next step to be sweeped-in from end edge of the wizard. If false, the step is sweeped-in from beginning of the wizard.

stepperWizard.refreshHeader()

Refresh header to show updated data (title & subTitle) for the step if they were changed

Kind: instance method of StepperWizard

stepperWizard.refreshFooter([...buttonId])

Refresh footer to show updated button states

Kind: instance method of StepperWizard
Note: If the method is called without any parameter then all buttons of the active step are refreshed.

Param	Type	Description
[...buttonId]	string	Id of the button to refresh. Multiple id could be passed as parameters.

stepperWizard.getData() ⇒ *

Returns a reference to the data shared accross steps

Kind: instance method of StepperWizard
Returns: * - The data that was set as part of constructor options.

stepperWizard.getId() ⇒ string

Returns a specifier to uniquely identify a wizard instance. Can be used later for inbound radio channel events

Kind: instance method of StepperWizard
Returns: string - Unique identifier of this wizard instance

stepperWizard.blockActions()

Creates an indeterminate progress view over the wizard to block user interaction. The blocker remains active until unblockActions() is called.

Kind: instance method of StepperWizard

stepperWizard.unblockActions()

Withdraws an active user interaction blocker from over the wizard

Kind: instance method of StepperWizard

"wizard:shown"

Triggered on the wizard instance after it appears on screen

Kind: event emitted by StepperWizard

"wizard:minimized"

Triggered on the wizard instance after it is minimized

Kind: event emitted by StepperWizard

"wizard:restored"

Triggered on the wizard instance after it is restored from minimized state.

Kind: event emitted by StepperWizard

"wizard:closed" (isCancel, [...args])

Triggered on the wizard instance after it is closed.

Kind: event emitted by StepperWizard

Param	Type	Description
isCancel	Boolean	Whether the wizard was closed or cancelled.
[...args]	any	Any additional parameters paassed to cancel() or close()

"wizard:forceclose"

Triggered on the wizard instance just before it is about to be force closed due to unplanned page navigation e.g. reload

Kind: event emitted by StepperWizard

"step:before:active"

Triggered on StepView instance when the correspoding step is about to appear on screen.

Kind: event emitted by StepperWizard

"dom:refresh"

Triggered on the StepView when it appears on screen.

Kind: event emitted by StepperWizard

"step:active"

Triggered on the StepView after the step has become active and DOM is updated with corresponding view.

Kind: event emitted by StepperWizard

"step:before:inactive"

Triggered on the StepView when it is about to disappear from screen.

Kind: event emitted by StepperWizard

"step:inactive"

Triggered on the StepView after the view has been removed from DOM.

Kind: event emitted by StepperWizard

StepperWizard~StepperWizard

Kind: inner class of StepperWizard

new StepperWizard(options)

Param	Type	Default	Description
options	object		Constructor options
options.steps	Array.<StepConfig>		Step configuration of the wizard. Each step is represented with a different screen and a transition animation is played when the wizard moves from one step to another due to user interaction.
[options.showPageLeavingWarning]	Boolean	true	Whether to show a page blocker when user tries to close the wizard.
[options.suppressHeader]	Boolean	false	Indicate whether to hide the header.
[options.suppressFooter]	Boolean	false	Indicate whether to hide the footer.
[options.usePreviousStepTitleAsBackButtonTooltip]	Boolean	true	Whether to show previous step's title as tooltip for Back button shown on current step.
[options.data]	object		Any arbitrary piece of data that is shared among all the steps i.e views representing the steps.
[options.className]	string		An additional CSS class name to be used along with its own styling classes. Useful, when specific styling classes are required to be written for step views or customize overall appearance of the wizard.

StepperWizard~StepConfig : object

Configuration for each step

Kind: inner typedef of StepperWizard
Properties

Name	Type	Default	Description
id	string		A unique identifier for the step
viewClass	Marionette.View		View definition(not an instance, the class itself) which will be used to create presentation for the corresponding step.
[nextStepId]	string | function		Id of the step, which the wizard should show next. Defaults to 'id' of the next step in config, if any.
[previousStepId]	string | function		Id of the step, which the wizard should go back to from present step. Defaults to 'id' of the previous step in config, if any.
[title]	string | function		Used to set title for the step
[subTitle]	string | function		Used to set sub-title for the step
[buttons]	Array.<ButtonConfig>		Configuration to control behavior of default and/or any additional button for this step. Three customizable buttons are automatically created by the wizard to facilitate back & forth navigation between steps and cancellation. Any other buttons configured here will be created upon activation of corresponding step
[onCancel]	StepCancellationCallback		Callback to decide whether or not to close a wizard upon receiving CANCEL signal from either close,cancel button press or cancel() API call.
[viewOptions]	object		An unmanaged JS Object that will be passed only onto the view's constructor for this step
[transient]	Boolean	false	Indicates whether or not this step is to be considered a transient one. A transient step is never kept in step navigation history. In effect, with default navigation setup, clicking back on the step next to a transient step always brings the user back to the step before the transient one

StepperWizard~ButtonConfig : object

Configuration for a button

Kind: inner typedef of StepperWizard
Note: Default clickHandler for button with id='previous', id='next' & id='cancel' are already defined by the wizard to control back & forth navigation and cancellation. Overriding those handlers may be desired for an alternative behavior for a step
Properties

Name	Type	Default	Description
id	string		Identifier for the button. Buttons with id='next' & id='previous' & id='cancel' are already added to the set by the wizard.
[className]	string		Name of CSS class to be applied to the button
[align]	string	"end"	Alignment of the button. 'previous', 'next', 'cancel' buttons come with pre-defined but customizable alignment. Buttons aligned on the same side will be placed according to their order of definition
[label]	string | function		Label for the button
[ariaLabel]	string | function		Accessible title for the button. Defaults to same as label, if omitted or kept blank
[toolTip]	string | function		Tooltip for the button
[hidden]	Boolean | function	false	Whether this button should be hidden upon step activation or not
[disabled]	Boolean | function	false	Whether this button should be disabled upon step activation or not. The 'hidden' attribute takes precedence over this 'disabled' attribute
[clickHandler]	ButtonClickHandler		Default click handler for this button. This handler gets executed in context of the step's view

StepperWizard~StepCancellationCallback ⇒ jQuery.Promise | void

Kind: inner typedef of StepperWizard
Returns: jQuery.Promise | void - Return a JQuery Promise object to control the decision. The wizard will close or discard the CANCEL signal depending on whether the Promise is resolved or rejected. If anything else is returned from the Function or the callback is not defined at all, the default 'CANCEL' signal handler will close the wizard.
Note: This callback is executed in the context of view instance associated with the current srep.

StepperWizard~ButtonClickHandler ⇒ void

Kind: inner typedef of StepperWizard
Note: This callback is executed in the context of view instance associated with the current srep.