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 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.
Then the effective config that will be used looks like this:
|
|
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:
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'.
|
|
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'.
If you want to have a second instance of the 'welcome' view you can set different 'id' to the targets:
|
|
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 |
path? | string | A prefix that will be prepended in front of the name. |
|
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.
an xml view called 'Detail'
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:
Now if we call |
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:
|
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 |
Will be fired when the title of the "TitleTarget" has been changed.
A "TitleTarget" is resolved as the following:
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 |
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 When called, the context of the event handler (its |
attachTitleChanged |
Attaches event handler When called, the context of the event handler (its |
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 The passed function and listener object must match the ones used for event registration. |
detachTitleChanged |
Detaches event handler 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
|
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 |
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. |
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 |
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 |
Destroys the targets instance and all created targets. Does not destroy the views instance passed to the constructor. It has to be destroyed separately.
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 |
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 |
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 |
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 |
Fires event created to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
oParameters | object |
Parameters to pass along with the event |
Returns a metadata object for class sap.ui.core.routing.Targets.
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 |