Class sap.m.WizardModule: sap/m/Wizard

extends Control

Enables users to accomplish a single goal which consists of multiple dependable sub-tasks.

Overview

The sap.m.Wizard helps users complete a complex and unfamiliar task by dividing it into sections and guiding the user through it. The wizard has two main areas - a navigation area at the top showing the step sequence and a content area below it.

Structure

Navigation Area

The top most area of the wizard is occupied by the navigation area. It shows the sequence of wizard steps.

  • The minimum number of steps is 3 and the maximum is 8 and are stored in the steps aggregation.
  • Steps can be branching depending on choices the user made in their input - this is set by the enableBranching property.
  • Steps can have different visual representations - numbers or icons. You can add labels for better readability

Content

The content occupies the main part of the page. It can hold any type of input controls. The content is kept in wizard steps.

Next Step Button

The next step button is displayed below the content. It can be hidden by setting showNextButton to false and displayed, for example, only after the user has filled all mandatory fields.

Usage

When to use:

When the user has to accomplish a long or unfamiliar task.

When not to use:

When the user has to accomplish a routine task that is clear and familiar. When the task has only two steps or less.

Responsive Behavior

On mobile devices the steps in the StepNavigator are grouped together and overlap. Tapping on them will show a popover to select the step to navigate to.


Since: 1.30.
Constructor Summary
new sap.m.Wizard(sId?, mSettings?)Constructor for a new Wizard.
Event Summary
complete(oControlEvent)The complete event is fired when the user clicks the finish button of the Wizard.
stepActivate(oControlEvent)The StepActivated event is fired every time a new step is activated.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.m.Wizard.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.Wizard with name sClassName and enriches it with the information contained in oClassInfo.
sap.m.Wizard.getMetadata()Returns a metadata object for class sap.m.Wizard.
addStep(wizardStep)Adds a new step to the Wizard.
attachComplete(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the complete event of this sap.m.Wizard.
attachStepActivate(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the stepActivate event of this sap.m.Wizard.
destroySteps()Destroys all aggregated steps in the Wizard.
detachComplete(fnFunction, oListener)Detaches event handler fnFunction from the complete event of this sap.m.Wizard.
detachStepActivate(fnFunction, oListener)Detaches event handler fnFunction from the stepActivate event of this sap.m.Wizard.
discardProgress(step)Discards all progress done from the given step(incl.
fireComplete(mParameters?)Fires event complete to attached listeners.
fireStepActivate(mParameters?)Fires event stepActivate to attached listeners.
getCurrentStep()ID of the element which is the current target of the association currentStep, or null.
getEnableBranching()Gets current value of property enableBranching.
getFinishButtonText()Returns the finish button text which will be rendered.
getHeight()Gets current value of property height.
getProgress()Returns the number of the last activated step in the Wizard.
getProgressStep()Returns the last activated step in the Wizard.
getShowNextButton()Gets current value of property showNextButton.
getSteps()Gets content of aggregation steps.
getWidth()Gets current value of property width.
goToStep(step, focusFirstStepElement)Goes to the given step.
indexOfStep(oStep)Checks for the provided sap.m.WizardStep in the aggregation steps.
insertStep()Dynamic step insertion is not yet supported.
invalidateStep(step)Invalidates the given step.
nextStep()Validates the current step, and moves one step further.
previousStep()Discards the current step and goes one step back.
removeAllSteps()Removes all steps from the Wizard.
removeStep()Dynamic step removal is not yet supported.
setCurrentStep(oCurrentStep)Sets the associated currentStep.
setEnableBranching(bEnableBranching)Sets a new value for property enableBranching.
setFinishButtonText(value)Sets the text for the finish button.
setHeight(sHeight)Sets a new value for property height.
setShowNextButton(value)Sets the visiblity of the next button.
setWidth(sWidth)Sets a new value for property width.
validateStep(step)Validates the given step.
Constructor Detail
new sap.m.Wizard(sId?, mSettings?)

Constructor for a new Wizard.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject for a general description of the syntax of the settings object.

The supported settings are:

  • Properties

  • Aggregations

    • steps : sap.m.WizardStep[] (default)

  • Associations

  • Events

    • stepActivate : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • complete : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]

In addition, all settings applicable to the base type sap.ui.core.Control can be used as well.

Parameters:
stringsId?ID for the new control, generated automatically if no ID is given
objectmSettings?Initial settings for the new control
Event Detail
complete(oControlEvent)
The complete event is fired when the user clicks the finish button of the Wizard. The finish button is only available on the last step of the Wizard.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
stepActivate(oControlEvent)
The StepActivated event is fired every time a new step is activated.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
intoControlEvent.getParameters.indexThe index of the activated step as a parameter. One-based.
Method Detail
sap.m.Wizard.extend(sClassName, oClassInfo?, FNMetaImpl?): function

Creates a new subclass of class sap.m.Wizard with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Parameters:
stringsClassNameName of the class being created
objectoClassInfo?Object literal with information about the class
functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
functionCreated class / constructor function
sap.m.Wizard.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.m.Wizard.
Returns:
sap.ui.base.MetadataMetadata object describing this class
addStep(wizardStep): sap.m.Wizard
Adds a new step to the Wizard.
Parameters:
sap.m.WizardStepwizardStepNew WizardStep to add to the Wizard
Returns:
sap.m.WizardPointer to the control instance for chaining
attachComplete(oData?, fnFunction, oListener?): sap.m.Wizard

Attaches event handler fnFunction to the complete event of this sap.m.Wizard.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Wizard itself.

The complete event is fired when the user clicks the finish button of the Wizard. The finish button is only available on the last step of the Wizard.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Wizard itself
Returns:
sap.m.WizardReference to this in order to allow method chaining
attachStepActivate(oData?, fnFunction, oListener?): sap.m.Wizard

Attaches event handler fnFunction to the stepActivate event of this sap.m.Wizard.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Wizard itself.

The StepActivated event is fired every time a new step is activated.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Wizard itself
Returns:
sap.m.WizardReference to this in order to allow method chaining
destroySteps(): sap.m.Wizard
Destroys all aggregated steps in the Wizard.
Returns:
sap.m.WizardPointer to the control instance for chaining.
detachComplete(fnFunction, oListener): sap.m.Wizard

Detaches event handler fnFunction from the complete event of this sap.m.Wizard.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.WizardReference to this in order to allow method chaining
detachStepActivate(fnFunction, oListener): sap.m.Wizard

Detaches event handler fnFunction from the stepActivate event of this sap.m.Wizard.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.WizardReference to this in order to allow method chaining
discardProgress(step): sap.m.Wizard
Discards all progress done from the given step(incl.) to the end of the wizard. The verified state of the steps is returned to the initial provided.
Parameters:
sap.m.WizardStepstepThe step after which the progress is discarded.
Returns:
sap.m.WizardPointer to the control instance for chaining.
fireComplete(mParameters?): sap.m.Wizard
Fires event complete to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.m.WizardReference to this in order to allow method chaining
fireStepActivate(mParameters?): sap.m.Wizard
Fires event stepActivate to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
intmParameters.index?The index of the activated step as a parameter. One-based.
Returns:
sap.m.WizardReference to this in order to allow method chaining
getCurrentStep(): sap.ui.core.ID
ID of the element which is the current target of the association currentStep, or null.
Returns:
sap.ui.core.ID
getEnableBranching(): boolean

Gets current value of property enableBranching.

Enables the branching functionality of the Wizard. Branching gives the developer the ability to define multiple routes a user is able to take based on the input in the current step. It is up to the developer to programatically check for what is the input in the current step and set a concrete next step amongs the available subsequent steps. Note: If this property is set to false, next and subSequentSteps associations of the WizardStep control are ignored.

Default value is false.

Returns:
booleanValue of property enableBranching
getFinishButtonText(): string
Returns the finish button text which will be rendered.
Returns:
stringThe text which will be rendered in the finish button.
getHeight(): sap.ui.core.CSSSize

Gets current value of property height.

Determines the height of the Wizard.

Default value is 100%.

Returns:
sap.ui.core.CSSSizeValue of property height
getProgress(): number
Returns the number of the last activated step in the Wizard.
Returns:
numberThe last activated step.
getProgressStep(): sap.m.WizardStep
Returns the last activated step in the Wizard.
Returns:
sap.m.WizardStepPointer to the control instance for chaining.
getShowNextButton(): boolean

Gets current value of property showNextButton.

Controls the visibility of the next button. The developers can choose to control the flow of the steps either through the API (with nextStep and previousStep methods) or let the user click the next button, and control it with validateStep or invalidateStep methods.

Default value is true.

Returns:
booleanValue of property showNextButton
getSteps(): sap.m.WizardStep[]

Gets content of aggregation steps.

The wizard steps to be included in the content of the control.

Returns:
sap.m.WizardStep[]
getWidth(): sap.ui.core.CSSSize

Gets current value of property width.

Determines the width of the Wizard.

Default value is auto.

Returns:
sap.ui.core.CSSSizeValue of property width
goToStep(step, focusFirstStepElement): sap.m.Wizard
Goes to the given step. The step must already be activated and visible. You can't use this method on steps that haven't been reached yet.
Parameters:
sap.m.WizardStepstepThe step to go to.
booleanfocusFirstStepElementDefines whether the focus should be changed to the first element.
Returns:
sap.m.WizardPointer to the control instance for chaining.
indexOfStep(oStep): int
Checks for the provided sap.m.WizardStep in the aggregation steps. and returns its index if found or -1 otherwise.
Parameters:
sap.m.WizardStepoStepThe step whose index is looked for
Returns:
intThe index of the provided control in the aggregation if found, or -1 otherwise
insertStep()
Dynamic step insertion is not yet supported.
Experimental API:
invalidateStep(step): sap.m.Wizard
Invalidates the given step.
Parameters:
sap.m.WizardStepstepThe step to be invalidated.
Returns:
sap.m.WizardPointer to the control instance for chaining.
nextStep(): sap.m.Wizard
Validates the current step, and moves one step further.
Returns:
sap.m.WizardPointer to the control instance for chaining.
previousStep(): sap.m.Wizard
Discards the current step and goes one step back.
Returns:
sap.m.WizardPointer to the control instance for chaining.
removeAllSteps(): sap.m.WizardStep[]
Removes all steps from the Wizard.
Returns:
sap.m.WizardStep[]Pointer to the Steps that were removed.
removeStep()
Dynamic step removal is not yet supported.
Experimental API:
setCurrentStep(oCurrentStep): sap.m.Wizard
Sets the associated currentStep.
Parameters:
sap.ui.core.ID|sap.m.WizardStepoCurrentStepID of an element which becomes the new target of this currentStep association; alternatively, an element instance may be given
Returns:
sap.m.WizardReference to this in order to allow method chaining
setEnableBranching(bEnableBranching): sap.m.Wizard

Sets a new value for property enableBranching.

Enables the branching functionality of the Wizard. Branching gives the developer the ability to define multiple routes a user is able to take based on the input in the current step. It is up to the developer to programatically check for what is the input in the current step and set a concrete next step amongs the available subsequent steps. Note: If this property is set to false, next and subSequentSteps associations of the WizardStep control are ignored.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Parameters:
booleanbEnableBranchingNew value for property enableBranching
Returns:
sap.m.WizardReference to this in order to allow method chaining
setFinishButtonText(value): sap.m.Wizard
Sets the text for the finish button. By default it is "Review".
Parameters:
stringvalueThe text of the finish button.
Returns:
sap.m.WizardReference to the control instance for chaining.
setHeight(sHeight): sap.m.Wizard

Sets a new value for property height.

Determines the height of the Wizard.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 100%.

Parameters:
sap.ui.core.CSSSizesHeightNew value for property height
Returns:
sap.m.WizardReference to this in order to allow method chaining
setShowNextButton(value): sap.m.Wizard
Sets the visiblity of the next button.
Parameters:
booleanvalueTrue to show the button or false to hide it.
Returns:
sap.m.WizardReference to the control instance for chaining.
setWidth(sWidth): sap.m.Wizard

Sets a new value for property width.

Determines the width of the Wizard.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is auto.

Parameters:
sap.ui.core.CSSSizesWidthNew value for property width
Returns:
sap.m.WizardReference to this in order to allow method chaining
validateStep(step): sap.m.Wizard
Validates the given step.
Parameters:
sap.m.WizardStepstepThe step to be validated.
Returns:
sap.m.WizardPointer to the control instance for chaining.