NavContainer SAP SE Handles hierarchical navigation between Pages or other fullscreen controls. All children of this control receive navigation events, such as {@link sap.m.NavContainerChild#event:beforeShow beforeShow}, they are documented in the pseudo interface {@link sap.m.NavContainerChild sap.m.NavContainerChild}. sap.ui.core/Control 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 <code>afterShow</code> event can be used to focus another element, only if <code>autoFocus</code> is set to <code>false</code>. <b>Note:</b> The following scenarios are possible, depending on where the focus was before navigation to a new page: <ul><li>If <code>autoFocus</code> is set to <code>true</code> and the focus was inside the current page, the focus will be moved automatically on the new page.</li> <li>If <code>autoFocus</code> is set to <code>false</code> and the focus was inside the current page, the focus will disappear. <li>If the focus was outside the current page, after the navigation it will remain unchanged regardless of what is set to the <code>autoFocus</code> property.</li> <li>If the <code>autoFocus</code> is set to <code>false</code> and at the same time another wrapping control has its own logic for focus restoring upon rerendering, the focus will still appear.</li></ul> The height of the NavContainer. Can be changed when the NavContainer should not cover the whole available area. The width of the NavContainer. Can be changed when the NavContainer should not cover the whole available area. Whether the NavContainer is visible. 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: "fade", "flip" and "show" - and the names of any registered custom transitions. 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. The page which was shown before the current navigation. The ID of the page which was shown before the current navigation. The page which will be shown after the current navigation. The ID of the page which will be shown after the current navigation. 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. Whether this is a forward navigation, triggered by "to()". Whether this is a back navigation, triggered by "back()". Whether this is a navigation to the root page, triggered by "backToTop()". Whether this was a navigation to a specific page, triggered by "backToPage()". How the navigation was triggered, possible values are "to", "back", "backToPage", and "backToTop". 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. The page which had been shown before navigation. The ID of the page which had been shown before navigation. The page which is now shown after navigation. The ID of the page which is now shown after navigation. 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. Whether was a forward navigation, triggered by "to()". Whether this was a back navigation, triggered by "back()". Whether this was a navigation to the root page, triggered by "backToTop()". Whether this was a navigation to a specific page, triggered by "backToPage()". How the navigation was triggered, possible values are "to", "back", "backToPage", and "backToTop". The content entities between which this NavContainer navigates. These can be of type sap.m.Page, sap.ui.core.View, sap.m.Carousel or any other control with fullscreen/page semantics. These aggregated controls will receive navigation events like {@link sap.m.NavContainerChild#event:beforeShow beforeShow}, they are documented in the pseudo interface {@link sap.m.NavContainerChild sap.m.NavContainerChild} 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". Returns the control with the given ID from the "pages" aggregation (if available). The ID of the aggregated control to find Returns the currently displayed page-level control. <b>Note:</b> Returns <code>undefined</code> if no page has been added yet, otherwise returns an instance of <code>sap.m.Page</code>, <code>sap.ui.core.View</code>, <code>sap.m.Carousel</code> or whatever is aggregated. Returns the previous page (the page from which the user drilled down to the current page with "to()"). <b>Note:</b> 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, <code>undefined</code> is returned. Returns whether the current page is the top/initial page. <b>Note:</b> 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. 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. 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. 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. 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. 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), "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. The screen to which drilldown should happen. The ID or the control itself can be given. The type of the transition/animation to apply. This parameter can be omitted; then the default is "slide" (horizontal movement from the right). Since version 1.7.1. This optional object can carry any payload data which should be made available to the target page. 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. 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. 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.) 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. 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. 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. 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. This optional object can give additional information to the transition function, like the DOM element which triggered the transition or the desired transition duration. 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. 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. This optional object can give additional information to the transition function, like the DOM element which triggered the transition or the desired transition duration. 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. 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. 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. 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.