class sap.m.NavContainer

Control sample: sap.m.NavContainer
Visiblity: public
UX Guidelines:
Implements: sap.ui.core.IPlaceholderSupport
Available since: N/A
Module: sap/m/NavContainer
Application Component: CA-UI5-CTR

Handles hierarchical navigation between Pages or other fullscreen controls.

All children of this control receive navigation events, such as BeforeShow, they are documented in the pseudo interface sap.m.NavContainerChild.


Constructor

Constructor for a new NavContainer.

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.NavContainer(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
autoFocus boolean true

Determines whether the initial focus is set automatically on first rendering and after navigating to a new page. This is useful when on touch devices the keyboard pops out due to the focus being automatically set on an input field. If necessary, the AfterShow event can be used to focus another element, only if autoFocus is set to false.

Note: The following scenarios are possible, depending on where the focus was before navigation to a new page:

  • If autoFocus is set to true and the focus was inside the current page, the focus will be moved automatically on the new page.
  • If autoFocus is set to false and the focus was inside the current page, the focus will disappear.
  • If the focus was outside the current page, after the navigation it will remain unchanged regardless of what is set to the autoFocus property.
  • If the autoFocus is set to false and at the same time another wrapping control has its own logic for focus restoring upon rerendering, the focus will still appear.


Since: 1.30.

Visibility: public
defaultTransitionName string slide

The type of the transition/animation to apply when "to()" is called without defining a transition type to use. The default is "slide". Other options are: "baseSlide", "fade", "flip" and "show" - and the names of any registered custom transitions.

Since: 1.7.1.

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

The height of the NavContainer. Can be changed when the NavContainer should not cover the whole available area.

Visibility: public
visible boolean true

Whether the NavContainer is visible.

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

The width of the NavContainer. Can be changed when the NavContainer should not cover the whole available area.

Visibility: public

Aggregations

Default Aggregation: pages

Name Cardinality Type Description
pages (default) 0..n sap.ui.core.Control

The content entities between which this NavContainer navigates. These can be of type sap.m.Page, sap.ui.core.mvc.View, sap.m.Carousel or any other control with fullscreen/page semantics.

These aggregated controls will receive navigation events like BeforeShow, they are documented in the pseudo interface sap.m.NavContainerChild


Associations

Name Cardinality Type Description
initialPage 0..1 sap.ui.core.Control

This association can be used to define which page is displayed initially. If the given page does not exist or no page is given, the first page which has been added is considered as initial page. This value should be set initially and not set/modified while the application is running.

This could be used not only for the initial display, but also if the user wants to navigate "up to top", so this page serves as a sort of "home/root page".


Events Overview

Event Description
afterNavigate

The event is fired when navigation between two pages has completed (once all events to the child controls have been fired). In case of animated transitions this event is fired with some delay after the "navigate" event.

Since: 1.7.1.

navigate

The event is fired when navigation between two pages has been triggered (before any events to the child controls are fired). The transition (if any) to the new page has not started yet. This event can be aborted by the application with preventDefault(), which means that there will be no navigation.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object.

Since: 1.7.1.

afterNavigate

The event is fired when navigation between two pages has completed (once all events to the child controls have been fired). In case of animated transitions this event is fired with some delay after the "navigate" event.

Since: 1.7.1.

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

The page which had been shown before navigation.

fromId string

The ID of the page which had been shown before navigation.

to sap.ui.core.Control

The page which is now shown after navigation.

toId string

The ID of the page which is now shown after navigation.

firstTime boolean

Whether the "to" page (more precisely: a control with the ID of the page which has been navigated to) had not been shown/navigated to before.

isTo boolean

Whether was a forward navigation, triggered by "to()".

isBack boolean

Whether this was a back navigation, triggered by "back()".

isBackToTop boolean

Whether this was a navigation to the root page, triggered by "backToTop()".

isBackToPage boolean

Whether this was a navigation to a specific page, triggered by "backToPage()".

Since: 1.7.2.

direction string

How the navigation was triggered, possible values are "to", "back", "backToPage", and "backToTop".

navigate

The event is fired when navigation between two pages has been triggered (before any events to the child controls are fired). The transition (if any) to the new page has not started yet. This event can be aborted by the application with preventDefault(), which means that there will be no navigation.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object.

Since: 1.7.1.

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

The page which was shown before the current navigation.

fromId string

The ID of the page which was shown before the current navigation.

to sap.ui.core.Control

The page which will be shown after the current navigation.

toId string

The ID of the page which will be shown after the current navigation.

firstTime boolean

Whether the "to" page (more precisely: a control with the ID of the page which is currently navigated to) has not been shown/navigated to before.

isTo boolean

Whether this is a forward navigation, triggered by "to()".

isBack boolean

Whether this is a back navigation, triggered by "back()".

isBackToTop boolean

Whether this is a navigation to the root page, triggered by "backToTop()".

isBackToPage boolean

Whether this was a navigation to a specific page, triggered by "backToPage()".

Since: 1.7.2.

direction string

How the navigation was triggered, possible values are "to", "back", "backToPage", and "backToTop".


Methods Overview

Method Description
addCustomTransition

Adds a custom transition to the NavContainer type (not to a particular instance!). The transition is identified by a "name". Make sure to only use names that will not collide with transitions which may be added to the NavContainer later. A suggestion is to use the prefix "c_" or "_" for your custom transitions to ensure this.

"to" and "back" are the transition functions for the forward and backward navigation. Both will be called with the following parameters: - oFromPage: the Control which is currently being displayed by the NavContainer - oToPage: the Control which should be displayed by the NavContainer after the transition - fCallback: a function which MUST be called when the transition has completed - oTransitionParameters: a data object that can be given by application code when triggering the transition by calling to() or back(); this object could give additional information to the transition function, like the DOM element which triggered the transition or the desired transition duration

The contract for "to" and "back" is that they may do an animation of their choice, but it should not take "too long". At the beginning of the transition the target page "oToPage" does have the CSS class "sapMNavItemHidden" which initially hides the target page (visibility:hidden). The transition can do any preparation (e.g. move that page out of the screen or make it transparent) and then should remove this CSS class. After the animation the target page "oToPage" should cover the entire screen and the source page "oFromPage" should not be visible anymore. This page should then have the CSS class "sapMNavItemHidden". For adding/removing this or other CSS classes, the transition can use the addStyleClass/removeStyleClass method: oFromPage.addStyleClass("sapMNavItemHidden"); When the transition is complete, it MUST call the given fCallback method to inform the NavContainer that navigation has finished!

Hint: if the target page of your transition stays black on iPhone, try wrapping the animation start into a setTimeout(..., 0) block (delayed, but without waiting).

This method can be called on any NavContainer instance or statically on the sap.m.NavContainer type. However, the transition will always be registered for the type (and ALL instances), not for the single instance on which this method was invoked.

Returns the sap.m.NavContainer type if called statically, or "this" (to allow method chaining) if called on a particular NavContainer instance.

addPage

Adds some page to the aggregation pages.

attachAfterNavigate

Attaches event handler fnFunction to the afterNavigate event of this sap.m.NavContainer.

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.NavContainer itself.

The event is fired when navigation between two pages has completed (once all events to the child controls have been fired). In case of animated transitions this event is fired with some delay after the "navigate" event.

attachNavigate

Attaches event handler fnFunction to the navigate event of this sap.m.NavContainer.

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.NavContainer itself.

The event is fired when navigation between two pages has been triggered (before any events to the child controls are fired). The transition (if any) to the new page has not started yet. This event can be aborted by the application with preventDefault(), which means that there will be no navigation.

back

Navigates back one level. If already on the initial page and there is no place to go back, nothing happens.

Calling this navigation method triggers first the (cancelable) "navigate" event on the NavContainer, then the "BeforeHide" pseudo event on the source page and "BeforeFirstShow" (if applicable) and"BeforeShow" on the target page. Later - after the transition has completed - the "AfterShow" pseudo event is triggered on the target page and "AfterHide" on the page which has been left. The given backData object is available in the "BeforeFirstShow", "BeforeShow" and "AfterShow" event object as "data" property. The original "data" object from the "to" navigation is also available in these event objects.

backToPage

Navigates back to the nearest previous page in the NavContainer history with the given ID. If there is no such page among the previous pages, nothing happens. The transition effect which had been used to get to the current page is inverted and used for this navigation.

Calling this navigation method triggers first the (cancelable) "navigate" event on the NavContainer, then the "BeforeHide" pseudo event on the source page and "BeforeFirstShow" (if applicable) and"BeforeShow" on the target page. Later - after the transition has completed - the "AfterShow" pseudo event is triggered on the target page and "AfterHide" on the page which has been left. The given backData object is available in the "BeforeFirstShow", "BeforeShow" and "AfterShow" event object as "data" property. The original "data" object from the "to" navigation is also available in these event objects.

backToTop

Navigates back to the initial/top level (this is the element aggregated as "initialPage", or the first added element). If already on the initial page, nothing happens. The transition effect which had been used to get to the current page is inverted and used for this navigation.

Calling this navigation method triggers first the (cancelable) "navigate" event on the NavContainer, then the "BeforeHide" pseudo event on the source page and "BeforeFirstShow" (if applicable) and "BeforeShow" on the target page. Later - after the transition has completed - the "AfterShow" pseudo event is triggered on the target page and "AfterHide" on the page which has been left. The given backData object is available in the "BeforeFirstShow", "BeforeShow" and "AfterShow" event object as "data" property.

currentPageIsTopPage

Returns whether the current page is the top/initial page.

Note: going to the initial page again with a row of "to" navigations causes the initial page to be displayed again, but logically one is not at the top level, so this method returns "false" in this case.

destroyPages

Destroys all the pages in the aggregation pages.

detachAfterNavigate

Detaches event handler fnFunction from the afterNavigate event of this sap.m.NavContainer.

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

detachNavigate

Detaches event handler fnFunction from the navigate event of this sap.m.NavContainer.

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

sap.m.NavContainer.extend

Creates a new subclass of class sap.m.NavContainer 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.

fireAfterNavigate

Fires event afterNavigate to attached listeners.

fireNavigate

Fires event navigate to attached listeners.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object. The return value of this method indicates whether the default action should be executed.

getAutoFocus

Gets current value of property autoFocus.

Determines whether the initial focus is set automatically on first rendering and after navigating to a new page. This is useful when on touch devices the keyboard pops out due to the focus being automatically set on an input field. If necessary, the AfterShow event can be used to focus another element, only if autoFocus is set to false.

Note: The following scenarios are possible, depending on where the focus was before navigation to a new page:

  • If autoFocus is set to true and the focus was inside the current page, the focus will be moved automatically on the new page.
  • If autoFocus is set to false and the focus was inside the current page, the focus will disappear.
  • If the focus was outside the current page, after the navigation it will remain unchanged regardless of what is set to the autoFocus property.
  • If the autoFocus is set to false and at the same time another wrapping control has its own logic for focus restoring upon rerendering, the focus will still appear.

Default value is true.

getCurrentPage

Returns the currently displayed page-level control.

Note: Returns undefined if no page has been added yet, otherwise returns an instance of sap.m.Page, sap.ui.core.mvc.View, sap.m.Carousel or whatever is aggregated.

getDefaultTransitionName

Gets current value of property defaultTransitionName.

The type of the transition/animation to apply when "to()" is called without defining a transition type to use. The default is "slide". Other options are: "baseSlide", "fade", "flip" and "show" - and the names of any registered custom transitions.

Default value is "slide".

getHeight

Gets current value of property height.

The height of the NavContainer. Can be changed when the NavContainer should not cover the whole available area.

Default value is '100%'.

getInitialPage

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

sap.m.NavContainer.getMetadata

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

getPage

Returns the control with the given ID from the "pages" aggregation (if available).

getPages

Gets content of aggregation pages.

The content entities between which this NavContainer navigates. These can be of type sap.m.Page, sap.ui.core.mvc.View, sap.m.Carousel or any other control with fullscreen/page semantics.

These aggregated controls will receive navigation events like BeforeShow, they are documented in the pseudo interface sap.m.NavContainerChild

getPreviousPage

Returns the previous page (the page from which the user drilled down to the current page with "to()").

Note: this is not the page which the user has seen before, but the page which is the target of the next "back()" navigation. If there is no previous page, undefined is returned.

getVisible

Gets current value of property visible.

Whether the NavContainer is visible.

Default value is true.

getWidth

Gets current value of property width.

The width of the NavContainer. Can be changed when the NavContainer should not cover the whole available area.

Default value is '100%'.

hidePlaceholder

Hides the placeholder and removes the 'onAfterRendering' placeholder delegate.

indexOfPage

Checks for the provided sap.ui.core.Control in the aggregation pages. and returns its index if found or -1 otherwise.

insertPage

Inserts a page into the aggregation pages.

insertPreviousPage

Inserts the page/control with the specified ID into the navigation history stack of the NavContainer.

This can be used for deep-linking when the user directly reached a drilldown detail page using a bookmark and then wants to navigate up in the drilldown hierarchy. Normally such a back navigation would not be possible because there is no previous page in the NavContainer's history stack.

needPlaceholder

Checks whether a placeholder is needed by comparing the currently displayed page with the page object that is going to be displayed. If they are the same, no placeholder needs to be shown.

removeAllPages

Removes all the controls from the aggregation pages.

Additionally, it unregisters them from the hosting UIArea.

removePage

Removes a page.

setAutoFocus

Sets a new value for property autoFocus.

Determines whether the initial focus is set automatically on first rendering and after navigating to a new page. This is useful when on touch devices the keyboard pops out due to the focus being automatically set on an input field. If necessary, the AfterShow event can be used to focus another element, only if autoFocus is set to false.

Note: The following scenarios are possible, depending on where the focus was before navigation to a new page:

  • If autoFocus is set to true and the focus was inside the current page, the focus will be moved automatically on the new page.
  • If autoFocus is set to false and the focus was inside the current page, the focus will disappear.
  • If the focus was outside the current page, after the navigation it will remain unchanged regardless of what is set to the autoFocus property.
  • If the autoFocus is set to false and at the same time another wrapping control has its own logic for focus restoring upon rerendering, the focus will still appear.

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

Default value is true.

setDefaultTransitionName

Sets a new value for property defaultTransitionName.

The type of the transition/animation to apply when "to()" is called without defining a transition type to use. The default is "slide". Other options are: "baseSlide", "fade", "flip" and "show" - and the names of any registered custom transitions.

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

Default value is "slide".

setHeight

Sets a new value for property height.

The height of the NavContainer. Can be changed when the NavContainer should not cover the whole available area.

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

Default value is '100%'.

setInitialPage

Sets the associated initialPage.

setVisible

Sets a new value for property visible.

Whether the NavContainer is visible.

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

Default value is true.

setWidth

Sets a new value for property width.

The width of the NavContainer. Can be changed when the NavContainer should not cover the whole available area.

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

Default value is '100%'.

showPlaceholder

Shows the placeholder if NavContainer is rendered. Otherwise, registers the 'onAfterRendering' delegate which shows the placeholder.

to

Navigates to the next page (with drill-down semantic) with the given (or default) animation. This creates a new history item inside the NavContainer and allows going back.

Note that any modifications to the target page (like setting its title, or anything else that could cause a re-rendering) should be done BEFORE calling to(), in order to avoid unwanted side effects, e.g. related to the page animation.

Available transitions currently include "slide" (default), "baseSlide", "fade", "flip", and "show". None of these is currently making use of any given transitionParameters.

Calling this navigation method triggers first the (cancelable) "navigate" event on the NavContainer, then the "BeforeHide" pseudo event on the source page and "BeforeFirstShow" (if applicable) and"BeforeShow" on the target page. Later - after the transition has completed - the "AfterShow" pseudo event is triggered on the target page and "AfterHide" on the page which has been left. The given data object is available in the "BeforeFirstShow", "BeforeShow" and "AfterShow" event object as "data" property.

addCustomTransition

Adds a custom transition to the NavContainer type (not to a particular instance!). The transition is identified by a "name". Make sure to only use names that will not collide with transitions which may be added to the NavContainer later. A suggestion is to use the prefix "c_" or "_" for your custom transitions to ensure this.

"to" and "back" are the transition functions for the forward and backward navigation. Both will be called with the following parameters: - oFromPage: the Control which is currently being displayed by the NavContainer - oToPage: the Control which should be displayed by the NavContainer after the transition - fCallback: a function which MUST be called when the transition has completed - oTransitionParameters: a data object that can be given by application code when triggering the transition by calling to() or back(); this object could give additional information to the transition function, like the DOM element which triggered the transition or the desired transition duration

The contract for "to" and "back" is that they may do an animation of their choice, but it should not take "too long". At the beginning of the transition the target page "oToPage" does have the CSS class "sapMNavItemHidden" which initially hides the target page (visibility:hidden). The transition can do any preparation (e.g. move that page out of the screen or make it transparent) and then should remove this CSS class. After the animation the target page "oToPage" should cover the entire screen and the source page "oFromPage" should not be visible anymore. This page should then have the CSS class "sapMNavItemHidden". For adding/removing this or other CSS classes, the transition can use the addStyleClass/removeStyleClass method: oFromPage.addStyleClass("sapMNavItemHidden"); When the transition is complete, it MUST call the given fCallback method to inform the NavContainer that navigation has finished!

Hint: if the target page of your transition stays black on iPhone, try wrapping the animation start into a setTimeout(..., 0) block (delayed, but without waiting).

This method can be called on any NavContainer instance or statically on the sap.m.NavContainer type. However, the transition will always be registered for the type (and ALL instances), not for the single instance on which this method was invoked.

Returns the sap.m.NavContainer type if called statically, or "this" (to allow method chaining) if called on a particular NavContainer instance.

Param Type DefaultValue Description
sName string

The name of the transition. This name can be used by the application to choose this transition when navigating "to()" or "back()": the "transitionName" parameter of "NavContainer.to()" corresponds to this name, the back() navigation will automatically use the same transition.

Make sure to only use names that will not collide with transitions which may be added to the NavContainer later. A suggestion is to use the prefix "c_" or "_" for your custom transitions to ensure this.

fTo object

The function which will be called by the NavContainer when the application navigates "to()", using this animation's name. The NavContainer instance is the "this" context within the animation function.

See the documentation of NavContainer.addCustomTransitions for more details about this function.

fBack object

The function which will be called by the NavContainer when the application navigates "back()" from a page where it had navigated to using this animation's name. The NavContainer instance is the "this" context within the animation function.

See the documentation of NavContainer.addCustomTransitions for more details about this function.

addPage

Adds some page to the aggregation pages.

Param Type DefaultValue Description
oPage sap.ui.core.Control

The page to add; if empty, nothing is inserted

attachAfterNavigate

Attaches event handler fnFunction to the afterNavigate event of this sap.m.NavContainer.

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.NavContainer itself.

The event is fired when navigation between two pages has completed (once all events to the child controls have been fired). In case of animated transitions this event is fired with some delay after the "navigate" event.

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.NavContainer itself

attachNavigate

Attaches event handler fnFunction to the navigate event of this sap.m.NavContainer.

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.NavContainer itself.

The event is fired when navigation between two pages has been triggered (before any events to the child controls are fired). The transition (if any) to the new page has not started yet. This event can be aborted by the application with preventDefault(), which means that there will be no navigation.

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.NavContainer itself

back

Navigates back one level. If already on the initial page and there is no place to go back, nothing happens.

Calling this navigation method triggers first the (cancelable) "navigate" event on the NavContainer, then the "BeforeHide" pseudo event on the source page and "BeforeFirstShow" (if applicable) and"BeforeShow" on the target page. Later - after the transition has completed - the "AfterShow" pseudo event is triggered on the target page and "AfterHide" on the page which has been left. The given backData object is available in the "BeforeFirstShow", "BeforeShow" and "AfterShow" event object as "data" property. The original "data" object from the "to" navigation is also available in these event objects.

Param Type DefaultValue Description
backData object

Since version 1.7.1. This optional object can carry any payload data which should be made available to the target page of the back navigation. The event on the target page will contain this data object as "backData" property. (The original data from the "to()" navigation will still be available as "data" property.)

In scenarios where the entity triggering the navigation can or should not directly initialize the target page, it can fill this object and the target page itself (or a listener on it) can take over the initialization, using the given data. For back navigation this can be used e.g. when returning from a detail page to transfer any settings done there.

When the "transitionParameters" object is used, this "data" object must also be given (either as object or as null) in order to have a proper parameter order.

oTransitionParameters object

Since version 1.7.1. This optional object can give additional information to the transition function, like the DOM element which triggered the transition or the desired transition duration. The animation type can NOT be selected here - it is always the inverse of the "to" navigation.

In order to use the "transitionParameters" property, the "data" property must be used (at least "null" must be given) for a proper parameter order.

NOTE: it depends on the transition function how the object should be structured and which parameters are actually used to influence the transition.

backToPage

Navigates back to the nearest previous page in the NavContainer history with the given ID. If there is no such page among the previous pages, nothing happens. The transition effect which had been used to get to the current page is inverted and used for this navigation.

Calling this navigation method triggers first the (cancelable) "navigate" event on the NavContainer, then the "BeforeHide" pseudo event on the source page and "BeforeFirstShow" (if applicable) and"BeforeShow" on the target page. Later - after the transition has completed - the "AfterShow" pseudo event is triggered on the target page and "AfterHide" on the page which has been left. The given backData object is available in the "BeforeFirstShow", "BeforeShow" and "AfterShow" event object as "data" property. The original "data" object from the "to" navigation is also available in these event objects.

Param Type DefaultValue Description
pageId string

The ID of the screen to which back navigation should happen. The ID or the control itself can be given. The nearest such page among the previous pages in the history stack will be used.

backData object

This optional object can carry any payload data which should be made available to the target page of the "backToPage" navigation. The event on the target page will contain this data object as "backData" property.

When the "transitionParameters" object is used, this "data" object must also be given (either as object or as null) in order to have a proper parameter order.

oTransitionParameters object

This optional object can give additional information to the transition function, like the DOM element which triggered the transition or the desired transition duration. The animation type can NOT be selected here - it is always the inverse of the "to" navigation.

In order to use the "transitionParameters" property, the "data" property must be used (at least "null" must be given) for a proper parameter order.

NOTE: it depends on the transition function how the object should be structured and which parameters are actually used to influence the transition.

backToTop

Navigates back to the initial/top level (this is the element aggregated as "initialPage", or the first added element). If already on the initial page, nothing happens. The transition effect which had been used to get to the current page is inverted and used for this navigation.

Calling this navigation method triggers first the (cancelable) "navigate" event on the NavContainer, then the "BeforeHide" pseudo event on the source page and "BeforeFirstShow" (if applicable) and "BeforeShow" on the target page. Later - after the transition has completed - the "AfterShow" pseudo event is triggered on the target page and "AfterHide" on the page which has been left. The given backData object is available in the "BeforeFirstShow", "BeforeShow" and "AfterShow" event object as "data" property.

Param Type DefaultValue Description
backData object

This optional object can carry any payload data which should be made available to the target page of the "backToTop" navigation. The event on the target page will contain this data object as "backData" property.

When the "transitionParameters" object is used, this "data" object must also be given (either as object or as null) in order to have a proper parameter order.

oTransitionParameters object

This optional object can give additional information to the transition function, like the DOM element which triggered the transition or the desired transition duration. The animation type can NOT be selected here - it is always the inverse of the "to" navigation.

In order to use the "transitionParameters" property, the "data" property must be used (at least "null" must be given) for a proper parameter order.

NOTE: it depends on the transition function how the object should be structured and which parameters are actually used to influence the transition.

currentPageIsTopPage

Returns whether the current page is the top/initial page.

Note: going to the initial page again with a row of "to" navigations causes the initial page to be displayed again, but logically one is not at the top level, so this method returns "false" in this case.

destroyPages

Destroys all the pages in the aggregation pages.

detachAfterNavigate

Detaches event handler fnFunction from the afterNavigate event of this sap.m.NavContainer.

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

detachNavigate

Detaches event handler fnFunction from the navigate event of this sap.m.NavContainer.

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

sap.m.NavContainer.extend

Creates a new subclass of class sap.m.NavContainer 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

fireAfterNavigate

Fires event afterNavigate to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

from sap.ui.core.Control

The page which had been shown before navigation.

fromId string

The ID of the page which had been shown before navigation.

to sap.ui.core.Control

The page which is now shown after navigation.

toId string

The ID of the page which is now shown after navigation.

firstTime boolean

Whether the "to" page (more precisely: a control with the ID of the page which has been navigated to) had not been shown/navigated to before.

isTo boolean

Whether was a forward navigation, triggered by "to()".

isBack boolean

Whether this was a back navigation, triggered by "back()".

isBackToTop boolean

Whether this was a navigation to the root page, triggered by "backToTop()".

isBackToPage boolean

Whether this was a navigation to a specific page, triggered by "backToPage()".

direction string

How the navigation was triggered, possible values are "to", "back", "backToPage", and "backToTop".

fireNavigate

Fires event navigate to attached listeners.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object. The return value of this method indicates whether the default action should be executed.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

from sap.ui.core.Control

The page which was shown before the current navigation.

fromId string

The ID of the page which was shown before the current navigation.

to sap.ui.core.Control

The page which will be shown after the current navigation.

toId string

The ID of the page which will be shown after the current navigation.

firstTime boolean

Whether the "to" page (more precisely: a control with the ID of the page which is currently navigated to) has not been shown/navigated to before.

isTo boolean

Whether this is a forward navigation, triggered by "to()".

isBack boolean

Whether this is a back navigation, triggered by "back()".

isBackToTop boolean

Whether this is a navigation to the root page, triggered by "backToTop()".

isBackToPage boolean

Whether this was a navigation to a specific page, triggered by "backToPage()".

direction string

How the navigation was triggered, possible values are "to", "back", "backToPage", and "backToTop".

getAutoFocus

Gets current value of property autoFocus.

Determines whether the initial focus is set automatically on first rendering and after navigating to a new page. This is useful when on touch devices the keyboard pops out due to the focus being automatically set on an input field. If necessary, the AfterShow event can be used to focus another element, only if autoFocus is set to false.

Note: The following scenarios are possible, depending on where the focus was before navigation to a new page:

Default value is true.

getCurrentPage

Returns the currently displayed page-level control.

Note: Returns undefined if no page has been added yet, otherwise returns an instance of sap.m.Page, sap.ui.core.mvc.View, sap.m.Carousel or whatever is aggregated.

getDefaultTransitionName

Gets current value of property defaultTransitionName.

The type of the transition/animation to apply when "to()" is called without defining a transition type to use. The default is "slide". Other options are: "baseSlide", "fade", "flip" and "show" - and the names of any registered custom transitions.

Default value is "slide".

getHeight

Gets current value of property height.

The height of the NavContainer. Can be changed when the NavContainer should not cover the whole available area.

Default value is '100%'.

getInitialPage

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

sap.m.NavContainer.getMetadata

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

getPage

Returns the control with the given ID from the "pages" aggregation (if available).

Param Type DefaultValue Description
pageId string

The ID of the aggregated control to find

getPages

Gets content of aggregation pages.

The content entities between which this NavContainer navigates. These can be of type sap.m.Page, sap.ui.core.mvc.View, sap.m.Carousel or any other control with fullscreen/page semantics.

These aggregated controls will receive navigation events like BeforeShow, they are documented in the pseudo interface sap.m.NavContainerChild

getPreviousPage

Returns the previous page (the page from which the user drilled down to the current page with "to()").

Note: this is not the page which the user has seen before, but the page which is the target of the next "back()" navigation. If there is no previous page, undefined is returned.

getVisible

Gets current value of property visible.

Whether the NavContainer is visible.

Default value is true.

getWidth

Gets current value of property width.

The width of the NavContainer. Can be changed when the NavContainer should not cover the whole available area.

Default value is '100%'.

hidePlaceholder

Hides the placeholder and removes the 'onAfterRendering' placeholder delegate.

indexOfPage

Checks for the provided sap.ui.core.Control in the aggregation pages. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oPage sap.ui.core.Control

The page whose index is looked for

insertPage

Inserts a page into the aggregation pages.

Param Type DefaultValue Description
oPage sap.ui.core.Control

The page to insert; if empty, nothing is inserted

iIndex int

The 0-based index the page should be inserted at; for a negative value of iIndex, the page is inserted at position 0; for a value greater than the current size of the aggregation, the page is inserted at the last position

insertPreviousPage

Inserts the page/control with the specified ID into the navigation history stack of the NavContainer.

This can be used for deep-linking when the user directly reached a drilldown detail page using a bookmark and then wants to navigate up in the drilldown hierarchy. Normally such a back navigation would not be possible because there is no previous page in the NavContainer's history stack.

Param Type DefaultValue Description
pageId string

The ID of the control/page/screen which is inserted into the history stack. The respective control must be aggregated by the NavContainer, otherwise this will cause an error.

transitionName string slide

The type of the transition/animation which would have been used to navigate from the (inserted) previous page to the current page. When navigating back, the inverse animation will be applied. Options are "slide" (horizontal movement from the right), "baseSlide", "fade", "flip", and "show" and the names of any registered custom transitions.

data object

This optional object can carry any payload data which would have been given to the inserted previous page if the user would have done a normal forward navigation to it.

needPlaceholder

Checks whether a placeholder is needed by comparing the currently displayed page with the page object that is going to be displayed. If they are the same, no placeholder needs to be shown.

Param Type DefaultValue Description
sAggregationName string

The aggregation name

oObject object

The page object to be displayed

removeAllPages

Removes all the controls from the aggregation pages.

Additionally, it unregisters them from the hosting UIArea.

removePage

Removes a page.

Param Type DefaultValue Description
vPage int string sap.ui.core.Control

the position or ID of the Control that should be removed or that Control itself; if vPage is invalid, a negative value or a value greater or equal than the current size of the aggregation, nothing is removed.

setAutoFocus

Sets a new value for property autoFocus.

Determines whether the initial focus is set automatically on first rendering and after navigating to a new page. This is useful when on touch devices the keyboard pops out due to the focus being automatically set on an input field. If necessary, the AfterShow event can be used to focus another element, only if autoFocus is set to false.

Note: The following scenarios are possible, depending on where the focus was before navigation to a new page:

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

Default value is true.

Param Type DefaultValue Description
bAutoFocus boolean true

New value for property autoFocus

setDefaultTransitionName

Sets a new value for property defaultTransitionName.

The type of the transition/animation to apply when "to()" is called without defining a transition type to use. The default is "slide". Other options are: "baseSlide", "fade", "flip" and "show" - and the names of any registered custom transitions.

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

Default value is "slide".

Param Type DefaultValue Description
sDefaultTransitionName string "slide"

New value for property defaultTransitionName

setHeight

Sets a new value for property height.

The height of the NavContainer. Can be changed when the NavContainer should not cover the whole available area.

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

setInitialPage

Sets the associated initialPage.

Param Type DefaultValue Description
oInitialPage sap.ui.core.ID sap.ui.core.Control

ID of an element which becomes the new target of this initialPage association; alternatively, an element instance may be given

setVisible

Sets a new value for property visible.

Whether the NavContainer is visible.

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

Default value is true.

Param Type DefaultValue Description
bVisible boolean true

New value for property visible

setWidth

Sets a new value for property width.

The width of the NavContainer. Can be changed when the NavContainer should not cover the whole available area.

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
sWidth sap.ui.core.CSSSize '100%'

New value for property width

showPlaceholder

Shows the placeholder if NavContainer is rendered. Otherwise, registers the 'onAfterRendering' delegate which shows the placeholder.

Param Type DefaultValue Description
mSettings object

Object containing the placeholder instance. Can be omitted if a placeholder instance is already created by sap.ui.core.routing.async.Target.

placeholder sap.ui.core.Placeholder

The placeholder instance

to

Navigates to the next page (with drill-down semantic) with the given (or default) animation. This creates a new history item inside the NavContainer and allows going back.

Note that any modifications to the target page (like setting its title, or anything else that could cause a re-rendering) should be done BEFORE calling to(), in order to avoid unwanted side effects, e.g. related to the page animation.

Available transitions currently include "slide" (default), "baseSlide", "fade", "flip", and "show". None of these is currently making use of any given transitionParameters.

Calling this navigation method triggers first the (cancelable) "navigate" event on the NavContainer, then the "BeforeHide" pseudo event on the source page and "BeforeFirstShow" (if applicable) and"BeforeShow" on the target page. Later - after the transition has completed - the "AfterShow" pseudo event is triggered on the target page and "AfterHide" on the page which has been left. The given data object is available in the "BeforeFirstShow", "BeforeShow" and "AfterShow" event object as "data" property.

Param Type DefaultValue Description
pageId string

The screen to which drilldown should happen. The ID or the control itself can be given.

transitionName string slide

The type of the transition/animation to apply. Options are "slide" (horizontal movement from the right), "baseSlide", "fade", "flip", and "show" and the names of any registered custom transitions.

None of the standard transitions is currently making use of any given transition parameters.

data object

Since version 1.7.1. This optional object can carry any payload data which should be made available to the target page. The "BeforeShow" event on the target page will contain this data object as "data" property. Use case: in scenarios where the entity triggering the navigation can or should not directly initialize the target page, it can fill this object and the target page itself (or a listener on it) can take over the initialization, using the given data.

When the "transitionParameters" object is used, this "data" object must also be given (either as object or as null) in order to have a proper parameter order.

oTransitionParameters object

Since version 1.7.1. This optional object can contain additional information for the transition function, like the DOM element which triggered the transition or the desired transition duration.

For a proper parameter order, the "data" parameter must be given when the "transitionParameters" parameter is used. (it can be given as "null")

NOTE: it depends on the transition function how the object should be structured and which parameters are actually used to influence the transition. The "show", "slide", "baseSlide" and "fade" transitions do not use any parameter.