Enables users to accomplish a single goal which consists of multiple dependable sub-tasks.
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.
The top most area of the wizard is occupied by the navigation area. It shows the sequence of wizard steps.
steps
aggregation.enableBranching
property. The content occupies the main part of the page. It can hold any type of input controls. The content is kept in wizard steps.
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.
When the user has to accomplish a long or unfamiliar task.
When the user has to accomplish a routine task that is clear and familiar. When the task has only two steps or less.
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
.
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 |
Name | Type | Default Value | Description |
---|---|---|---|
backgroundDesign | sap.m.PageBackgroundDesign | Standard | This property is used to set the background color of a Wizard content. The |
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, |
finishButtonText | string | Review | Changes the text of the finish button for the last step. This property can be used only if |
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 |
width | sap.ui.core.CSSSize | auto | Determines the width of the Wizard. Visibility: public |
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. |
steps (default) | 0..n | sap.m.WizardStep |
The wizard steps to be included in the content of the control. |
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 |
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. |
Method | Description |
---|---|
addStep |
Adds a new step to the Wizard. |
attachComplete |
Attaches event handler When called, the context of the event handler (its 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 When called, the context of the event handler (its The StepActivated event is fired every time a new step is activated. |
destroySteps |
Destroys all aggregated steps in the Wizard. |
detachComplete |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachStepActivate |
Detaches event handler 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
|
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 Default value is |
getCurrentStep |
ID of the element which is the current target of the association currentStep, or |
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, Default value is |
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 |
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 |
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 Default value is |
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 |
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 |
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, When called with a value of Default value is |
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 When called with a value of Default value is |
setHeight |
Sets a new value for property height. Determines the height of the Wizard. When called with a value of Default value is |
setRenderMode |
Sets a new value for property renderMode. Defines how the steps of the Wizard would be visualized. When called with a value of Default value is |
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 Default value is |
validateStep |
Validates the given step. |
Adds a new step to the Wizard.
Param | Type | DefaultValue | Description |
---|---|---|---|
oWizardStep | sap.m.WizardStep |
New WizardStep to add to the 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.
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 |
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 |
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 |
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 |
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 |
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 |
Fires event complete to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
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. |
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
.
ID of the element which is the current target of the association currentStep, or null
.
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
.
Gets current value of property height.
Determines the height of the Wizard.
Default value is "100%"
.
Gets current value of property renderMode.
Defines how the steps of the Wizard would be visualized.
Default value is Scroll
.
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
.
Gets content of aggregation steps.
The wizard steps to be included in the content of the control.
Gets current value of property width.
Determines the width of the Wizard.
Default value is "auto"
.
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. |
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 |
Invalidates the given step.
Param | Type | DefaultValue | Description |
---|---|---|---|
oStep | sap.m.WizardStep |
The step to be invalidated. |
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). |
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 |
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 |
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 |
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 |
Sets the visibility of the next button.
Param | Type | DefaultValue | Description |
---|---|---|---|
bValue | boolean |
True to show the button or false to hide it. |
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 |
Validates the given step.
Param | Type | DefaultValue | Description |
---|---|---|---|
oStep | sap.m.WizardStep |
The step to be validated. |