class sap.ui.core.routing.Targets

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/core/routing/Targets
Application Component: CA-UI5-COR

Provides a convenient way for placing views into the correct containers of your application.

The main benefit of Targets is lazy loading: you do not have to create the views until you really need them. If you are using the mobile library, please use sap.m.routing.Targets instead of this class.


Constructor

Constructor for a new Targets class.

new sap.ui.core.routing.Targets(oOptions)
Param Type Default Value Description
oOptions object
views sap.ui.core.routing.Views

the views instance will create the views of all the targets defined, so if 2 targets have the same viewName, the same instance of the view will be displayed.

config? object

this config allows all the values oOptions.targets.anyName allows, these will be the default values for properties used in the target.
For example if you are only using xmlViews in your app you can specify viewType="XML" so you don't have to repeat this in every target.
If a target specifies viewType="JS", the JS will be stronger than the XML here is an example.


{
    config: {
        viewType : "XML"
    }
    targets : {
        xmlTarget : {
            ...
        },
        jsTarget : {
            viewType : "JS"
            ...
        }
    }
}

Then the effective config that will be used looks like this:

{
    xmlTarget : {
        // coming from the defaults
        viewType : "XML"
        ...
    },
    jsTarget : {
       // XML is overwritten by the "JS" of the targets property
       viewType : "JS"
      ...
    }
}

rootView? string

The id of the rootView - This should be the id of the view that contains the control with the controlId since the control will be retrieved by calling the sap.ui.core.mvc.View#byId function of the rootView. If you are using a component and add the routing.targets do not set this parameter, since the component will set the rootView to the view created by the sap.ui.core.UIComponent#createContent function. If you specify the "parent" property of a target, the control will not be searched in the root view but in the view Created by the parent (see parent documentation).

async? boolean false

@since 1.34 Whether the views which are created through this Targets are loaded asyncly. This option can be set only when the Targets is used standalone without the involvement of a Router. Otherwise the async option is inherited from the Router.

targets object

One or multiple targets in a map.

anyName object

a new target, the key severs as a name. An example:


{
    targets: {
        welcome: {
            type: "View",
            name: "Welcome",
            viewType: "XML",
            ....
            // Other target parameters
        },
        goodbye: {
            type: "Component",
            usage: "myreuse",
            containerSettings: {
                // settings for the component container
            }
            ....
            // Other target parameters
        }
    }
}

This will create two targets named 'welcome' and 'goodbye' you can display both of them or one of them using the #display function.

The 'welcome' target creates a View instance when it's displayed. The 'goodbye' target creates a Component instance.

The settings for the Component are defined in the manifest of the owner component of the router under path '/sap.ui5/componentUsages' and it can be used in the target by setting the 'usage' option with the name in the 'componentUsages'.
See the following manifest.json example of the owner component. There's a component settings object defined with name "myreuse" which can be used to set the "usage" option in a target's configuration.


{
    "sap.ui5": {
        "componentUsages": {
            "myreuse": {
                "name": "reuse.component",
                "settings": {},
                "componentData": {},
                "lazy": false,
            }
        }
    }
}

type string

Defines whether the target creates an instance of 'View' or 'Component'.

name? string

Defines the name of the View or Component that will be created. For type 'Component', use option 'usage' instead if an owner component exists. To place the view or component into a Control, use the options 'controlAggregation' and 'controlId'. Instance of View or Component will only be created once per 'name' or 'usage' combined with 'id'.


{
    targets: {
        // If display("masterWelcome") is called, the master view will be placed in the 'MasterPages' of a control with the id splitContainter
        masterWelcome: {
            type: "View",
            name: "Welcome",
            controlId: "splitContainer",
            controlAggregation: "masterPages"
        },
        // If display("detailWelcome") is called after the masterWelcome, the view will be removed from the master pages and added to the detail pages, since the same instance is used. Also the controls inside of the view will have the same state.
        detailWelcome: {
            // same view here, that's why the same instance is used
            type: "View",
            name: "Welcome",
            controlId: "splitContainer",
            controlAggregation: "detailPages"
        }
    }
}

If you want to have a second instance of the 'welcome' view you can set different 'id' to the targets:


{
    targets: {
        // If display("masterWelcome") is called, the master viewName will be placed in the 'MasterPages' of a control with the id splitContainter
        masterWelcome: {
            type: "View",
            name: "Welcome",
            controlId: "splitContainer",
            controlAggregation: "masterPages",
            id: "masterWelcome",
        },
        // If display("detailWelcome") is called after the masterWelcome, a second instance with an own controller instance will be added in the detail pages.
        detailWelcome: {
            type: "View",
            name: "WelcomeWithAlias",
            controlId: "splitContainer",
            controlAggregation: "detailPages",
            id: "detailWelcome"
        }
    }
}

usage? string

Defines the 'usage' name for 'Component' target which refers to the '/sap.ui5/componentUsages' entry in the owner component's manifest.

viewType? string oOptions.config.viewType

The type of the view that is going to be created. These are the supported types: sap.ui.core.mvc.ViewType. You always have to provide a viewType except if oOptions.config.viewType is set or when using sap.ui.core.routing.Views#setView.

path? string

A prefix that will be prepended in front of the name.
Example: name is set to "myView" and path is set to "myApp" - the created view name will be "myApp.myView".

id? string

The ID of the created instance. This is will be prefixed with the id of the component set to the views instance provided in oOptions.views. For details see sap.ui.core.routing.Views#getView.

targetParent? string

The id of the parent of the controlId - This should be the id of the view that contains your controlId, since the target control will be retrieved by calling the sap.ui.core.mvc.View#byId function of the targetParent. By default, this will be the view created by a component, so you do not have to provide this parameter. If you are using children, the view created by the parent of the child is taken. You only need to specify this, if you are not using a Targets instance created by a component and you should give the id of root view of your application to this property.

controlId? string

The ID of the control where you want to place the instance created by this target. You also need to set "controlAggregation" property to specify to which aggregation of the control should the created instance be added. An example for containers are sap.ui.ux3.Shell with the aggregation 'content' or a sap.m.NavContainer with the aggregation 'pages'.

controlAggregation? string

The name of an aggregation of the controlId, where the created instance from the target will be added. Eg: a sap.m.NavContainer has an aggregation 'pages', another Example is the sap.ui.ux3.Shell it has 'content'.

clearControlAggregation? boolean

Defines a boolean that can be passed to specify if the aggregation should be cleared - all items will be removed - before adding the View to it. When using a sap.ui.ux3.Shell this should be true. For a sap.m.NavContainer it should be false. When you use the sap.m.routing.Router the default will be false.

parent? string

A reference to another target, using the name of the target. If you display a target that has a parent, the parent will also be displayed. Also the control you specify with the controlId parameter, will be searched inside of the created instance of the parent not in the rootView, provided in the config. The control will be searched using the byId function of a view. When it is not found, the global id is checked.
The main usecase for the parent property is placing a view or component inside a smaller container of an instance, which is also created by targets. This is useful for lazy loading views or components, only if the user really navigates to this part of your application.
Example: Our aim is to lazy load a tab of an IconTabBar (a control that displays a view initially and when a user clicks on it the view changes). It's a perfect candidate to lazy load something inside of it.
Example app structure:
We have a rootView that is returned by the createContent function of our UIComponent. This view contains an sap.m.App control with the id 'myApp'


<View xmlns="sap.m">
    <App id="myApp"/>
</View>

an xml view called 'Detail'

<View xmlns="sap.m">
    <IconTabBar>
        <items>
            <IconTabFilter>
                <!-- content of our first tab -->
            <IconTabFilter>
            <IconTabFilter id="mySecondTab">
                <!-- nothing here, since we will lazy load this one with a target -->
            <IconTabFilter>
        </items>
    </IconTabBar>
</View>

and a view called 'SecondTabContent', this one contains our content we want to have lazy loaded. Now we need to create our Targets instance with a config matching our app:

    new Targets({
        //Creates our views except for root, we created this one before - when using a component you
        views: new Views(),
        config: {
            // all of our views have that type
            viewType: 'XML',
            // a reference to the app control in the rootView created by our UIComponent
            controlId: 'myApp',
            // An app has a pages aggregation where the views need to be put into
            controlAggregation: 'pages'
        },
        targets: {
            detail: {
                type: "View",
                name: 'Detail'
            },
            secondTabContent: {
                // A reference to the detail target defined above
                parent: 'detail',
                // A reference to the second Tab container in the Detail view. Here the target does not look in the rootView, it looks in the Parent view (Detail).
                controlId: 'mySecondTab',
                // An IconTabFilter has an aggregation called content so we need to overwrite the pages set in the config as default.
                controlAggregation: 'content',
                // A view containing the content
                type: "View",
                name: 'SecondTabContent'
            }
        }
    });

Now if we call oTargets.display("secondTabContent") , 2 views will be created: Detail and SecondTabContent. The 'Detail' view will be put into the pages aggregation of the App. And afterwards the 'SecondTabContent' view will be put into the content Aggregation of the second IconTabFilter. So a parent will always be created before the target referencing it.


Events Overview

Event Description
display

Will be fired when a target is displayed.

Could be triggered by calling the display function or by the sap.ui.core.routing.Router when a target is referenced in a matching route.

titleChanged

Will be fired when the title of the "TitleTarget" has been changed.

A "TitleTarget" is resolved as the following:

  1. When the display is called with only one target, the "TitleTarget" is resolved with this target when its title options is set.
  2. When the display is called with more than one target, the "TitleTarget" is resolved by default with the first target which has a title option.
  3. When the sTitleTarget parameter of display is given, this specific target is then used as the "TitleTarget".

display

Will be fired when a target is displayed.

Could be triggered by calling the display function or by the sap.ui.core.routing.Router when a target is referenced in a matching route.

Param Type Description
oEvent object
getSource sap.ui.base.EventProvider
getParameters object
view object

The view that got displayed.

control object

The control that now contains the view in the controlAggregation

config object

The options object passed to the constructor sap.ui.core.routing.Targets#constructor

name object

The name of the target firing the event

data object

The data passed into the sap.ui.core.routing.Targets#display function

routeRelevant object

Whether the target is relevant to the matched route or not

titleChanged

Will be fired when the title of the "TitleTarget" has been changed.

A "TitleTarget" is resolved as the following:

  1. When the display is called with only one target, the "TitleTarget" is resolved with this target when its title options is set.
  2. When the display is called with more than one target, the "TitleTarget" is resolved by default with the first target which has a title option.
  3. When the sTitleTarget parameter of display is given, this specific target is then used as the "TitleTarget".

Param Type Description
oEvent object
getSource sap.ui.base.EventProvider
getParameters object
title string

The current displayed title

name string

The name of the displayed target


Methods Overview

Method Description
addTarget

Creates a target by using the given name and options.

If there's already a target with the same name, the existing target is not overwritten and an error log will be written to the console.

attachDisplay

Attaches event handler fnFunction to the display event of this sap.ui.core.routing.Targets.

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.ui.core.routing.Targets itself.

attachTitleChanged

Attaches event handler fnFunction to the titleChanged event of this sap.ui.core.routing.Targets.

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.ui.core.routing.Targets itself.

destroy

Destroys the targets instance and all created targets. Does not destroy the views instance passed to the constructor. It has to be destroyed separately.

detachDisplay

Detaches event handler fnFunction from the display event of this sap.ui.core.routing.Targets.

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

detachTitleChanged

Detaches event handler fnFunction from the titleChanged event of this sap.ui.core.routing.Targets.

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

display

Creates a view and puts it in an aggregation of the specified control.

sap.ui.core.routing.Targets.extend

Creates a new subclass of class sap.ui.core.routing.Targets 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.base.EventProvider.extend.

fireDisplay

Fires event created to attached listeners.

sap.ui.core.routing.Targets.getMetadata

Returns a metadata object for class sap.ui.core.routing.Targets.

getTarget

Returns a target by its name (if you pass myTarget: { view: "myView" }) in the config myTarget is the name.

getViews

Returns the views instance passed to the constructor

addTarget

Creates a target by using the given name and options.

If there's already a target with the same name, the existing target is not overwritten and an error log will be written to the console.

Param Type DefaultValue Description
sName string

Name of a target

oTargetOptions object

Options of a target. The option names are the same as the ones in "oOptions.targets.anyName" of #constructor.

attachDisplay

Attaches event handler fnFunction to the display event of this sap.ui.core.routing.Targets.

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.ui.core.routing.Targets itself.

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

The function to be called, when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.core.routing.Targets itself

attachTitleChanged

Attaches event handler fnFunction to the titleChanged event of this sap.ui.core.routing.Targets.

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.ui.core.routing.Targets itself.

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

The function to be called, when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.core.routing.Targets itself

destroy

Destroys the targets instance and all created targets. Does not destroy the views instance passed to the constructor. It has to be destroyed separately.

detachDisplay

Detaches event handler fnFunction from the display event of this sap.ui.core.routing.Targets.

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

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachTitleChanged

Detaches event handler fnFunction from the titleChanged event of this sap.ui.core.routing.Targets.

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

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

display

Creates a view and puts it in an aggregation of the specified control.

Param Type DefaultValue Description
vTargets string string[] sap.ui.core.routing.TargetInfo sap.ui.core.routing.TargetInfo[]

Either the target name or a target info object. To display multiple targets you may also pass an array of target names or target info objects.

oData object

an object that will be passed to the display event in the data property. If the target has parents, the data will also be passed to them.

sTitleTarget string

the name of the target from which the title option is taken for firing the titleChanged event

sap.ui.core.routing.Targets.extend

Creates a new subclass of class sap.ui.core.routing.Targets 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.base.EventProvider.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

fireDisplay

Fires event created to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

sap.ui.core.routing.Targets.getMetadata

Returns a metadata object for class sap.ui.core.routing.Targets.

getTarget

Returns a target by its name (if you pass myTarget: { view: "myView" }) in the config myTarget is the name.

Param Type DefaultValue Description
vName string string[]

the name of a single target or the name of multiple targets

bSuppressNotFoundError boolean false

In case no target is found for the given name, the not found error is supressed when this is set with true

getViews

Returns the views instance passed to the constructor