class sap.m.Wizard

Control sample: sap.m.Wizard
Visiblity: public
UX Guidelines: Wizard
Implements: sap.f.IDynamicPageStickyContent
Available since: N/A
Module: sap/m/Wizard
Application Component: CA-UI5-CTR

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.

Note: Dynamic step insertion is not supported. Even if branching steps are used, the steps should be known in advance.

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.

When using the sap.m.Wizard in SAP Quartz theme, the breakpoints and layout paddings could be determined by the container's width. To enable this concept and add responsive paddings to the navigation area and to the content of the Wizard control, you may add the following classes depending on your use case: sapUiResponsivePadding--header, sapUiResponsivePadding--content.

As the sap.m.Wizard is a layout control, when used in the sap.f.DynamicPage, the sap.f.DynamicPage's fitContent property needs to be set to 'true' so that the scroll handling is left to the sap.m.Wizard control. Also, in order to achieve the target Fiori design, the sapUiNoContentPadding class needs to be added to the sap.f.DynamicPage as well as sapUiResponsivePadding--header, sapUiResponsivePadding--content to the sap.m.Wizard.

This control can be a drop target.

Constructor

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#constructor for a general description of the syntax of the settings object.

new sap.m.Wizard(sId?, mSettings?)
Param Type Default Value Description
sId? string

ID for the new control, generated automatically if no ID is given

mSettings? object

Initial settings for the new control


Properties

Name Type Default Value Description
backgroundDesign sap.m.PageBackgroundDesign Standard

This property is used to set the background color of a Wizard content. The Standard option with the default background color is used, if not specified.

Visibility: public
enableBranching boolean false

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 programmatically check for what is the input in the current step and set a concrete next step amongst the available subsequent steps. Note: If this property is set to false, next and subSequentSteps associations of the WizardStep control are ignored.

Since: 1.32.

Visibility: public
finishButtonText string Review

Changes the text of the finish button for the last step. This property can be used only if showNextButton is set to true. By default the text of the button is "Review".

Visibility: public
height sap.ui.core.CSSSize 100%

Determines the height of the Wizard.

Visibility: public
renderMode sap.m.WizardRenderMode Scroll

Defines how the steps of the Wizard would be visualized.

Visibility: public
showNextButton boolean true

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.

Visibility: public
width sap.ui.core.CSSSize auto

Determines the width of the Wizard.

Visibility: public

Aggregations

Default Aggregation: steps

Name Cardinality Type Description
_nextButton 0..1 sap.m.Button

The next button for the wizard.

_progressNavigator 0..1 sap.ui.core.Control

The progress navigator for the wizard.

Since: 1.32.

steps (default) 0..n sap.m.WizardStep

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


Associations

Name Cardinality Type Description
currentStep 0..1 sap.m.WizardStep

This association controls the current activated step of the wizard (meaning the last step) For example if we have A->B->C->D steps, we are on step A and we setCurrentStep(C) A,B and C are going to be activated. D will still remain unvisited. The parameter needs to be a Wizard step that is part of the current Wizard

Since: 1.50.


Events Overview

Event Description
complete

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.

stepActivate

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

complete

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.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

stepActivate

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

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
index int

The index of the activated step as a parameter. One-based.


Methods Overview

Method Description
addStep

Adds a new step to the Wizard.

attachComplete

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.

attachStepActivate

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.

destroySteps

Destroys all aggregated steps in the Wizard.

detachComplete

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.

detachStepActivate

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.

discardProgress

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.

sap.m.Wizard.extend

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.

fireComplete

Fires event complete to attached listeners.

fireStepActivate

Fires event stepActivate to attached listeners.

getBackgroundDesign

Gets current value of property backgroundDesign.

This property is used to set the background color of a Wizard content. The Standard option with the default background color is used, if not specified.

Default value is Standard.

getCurrentStep

ID of the element which is the current target of the association currentStep, or null.

getEnableBranching

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 programmatically check for what is the input in the current step and set a concrete next step amongst 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.

getFinishButtonText

Returns the finish button text which will be rendered.

getHeight

Gets current value of property height.

Determines the height of the Wizard.

Default value is "100%".

sap.m.Wizard.getMetadata

Returns a metadata object for class sap.m.Wizard.

getProgress

Returns the number of the last activated step in the Wizard.

getProgressStep

Returns the last activated step in the Wizard.

getRenderMode

Gets current value of property renderMode.

Defines how the steps of the Wizard would be visualized.

Default value is Scroll.

getShowNextButton

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.

getSteps

Gets content of aggregation steps.

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

getWidth

Gets current value of property width.

Determines the width of the Wizard.

Default value is "auto".

goToStep

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.

indexOfStep

Checks for the provided sap.m.WizardStep in the aggregation steps. and returns its index if found or -1 otherwise.

invalidateStep

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.

setCurrentStep

Sets association currentStep to the given step.

setEnableBranching

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 programmatically check for what is the input in the current step and set a concrete next step amongst 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.

setFinishButtonText

Sets a new value for property finishButtonText.

Changes the text of the finish button for the last step. This property can be used only if showNextButton is set to true. By default the text of the button is "Review".

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

Default value is "Review".

setHeight

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%".

setRenderMode

Sets a new value for property renderMode.

Defines how the steps of the Wizard would be visualized.

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

Default value is Scroll.

setShowNextButton

Sets the visibility of the next button.

setWidth

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".

validateStep

Validates the given step.

addStep

Adds a new step to the Wizard.

Param Type DefaultValue Description
oWizardStep sap.m.WizardStep

New WizardStep to add to the Wizard.

attachComplete

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.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.Wizard itself

attachStepActivate

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.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.Wizard itself

destroySteps

Destroys all aggregated steps in the Wizard.

detachComplete

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.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachStepActivate

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.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

discardProgress

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.

Param Type DefaultValue Description
oStep sap.m.WizardStep

The step after which the progress is discarded.

bPreserveNextStep boolean

Indicating whether we should preserve next step

sap.m.Wizard.extend

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.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireComplete

Fires event complete to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireStepActivate

Fires event stepActivate to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

index int

The index of the activated step as a parameter. One-based.

getBackgroundDesign

Gets current value of property backgroundDesign.

This property is used to set the background color of a Wizard content. The Standard option with the default background color is used, if not specified.

Default value is Standard.

getCurrentStep

ID of the element which is the current target of the association currentStep, or null.

getEnableBranching

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 programmatically check for what is the input in the current step and set a concrete next step amongst 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.

getFinishButtonText

Returns the finish button text which will be rendered.

getHeight

Gets current value of property height.

Determines the height of the Wizard.

Default value is "100%".

sap.m.Wizard.getMetadata

Returns a metadata object for class sap.m.Wizard.

getProgress

Returns the number of the last activated step in the Wizard.

getProgressStep

Returns the last activated step in the Wizard.

getRenderMode

Gets current value of property renderMode.

Defines how the steps of the Wizard would be visualized.

Default value is Scroll.

getShowNextButton

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.

getSteps

Gets content of aggregation steps.

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

getWidth

Gets current value of property width.

Determines the width of the Wizard.

Default value is "auto".

goToStep

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.

Param Type DefaultValue Description
oStep sap.m.WizardStep

The step to go to.

bFocusFirstStepElement boolean

Defines whether the focus should be changed to the first element.

indexOfStep

Checks for the provided sap.m.WizardStep in the aggregation steps. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oStep sap.m.WizardStep

The step whose index is looked for

invalidateStep

Invalidates the given step.

Param Type DefaultValue Description
oStep sap.m.WizardStep

The step to be invalidated.

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.

setCurrentStep

Sets association currentStep to the given step.

Param Type DefaultValue Description
vStepId sap.m.WizardStep sap.ui.core.ID

The step of the wizard that will be currently activated (meaning the last step).

setEnableBranching

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 programmatically check for what is the input in the current step and set a concrete next step amongst 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.

Param Type DefaultValue Description
bEnableBranching boolean false

New value for property enableBranching

setFinishButtonText

Sets a new value for property finishButtonText.

Changes the text of the finish button for the last step. This property can be used only if showNextButton is set to true. By default the text of the button is "Review".

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

Default value is "Review".

Param Type DefaultValue Description
sFinishButtonText string "Review"

New value for property finishButtonText

setHeight

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%".

Param Type DefaultValue Description
sHeight sap.ui.core.CSSSize "100%"

New value for property height

setRenderMode

Sets a new value for property renderMode.

Defines how the steps of the Wizard would be visualized.

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

Default value is Scroll.

Param Type DefaultValue Description
sRenderMode sap.m.WizardRenderMode Scroll

New value for property renderMode

setShowNextButton

Sets the visibility of the next button.

Param Type DefaultValue Description
bValue boolean

True to show the button or false to hide it.

setWidth

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".

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize "auto"

New value for property width

validateStep

Validates the given step.

Param Type DefaultValue Description
oStep sap.m.WizardStep

The step to be validated.