class sap.m.SplitApp

Control sample: sap.m.SplitApp
Visiblity: public
UX Guidelines: Split App
Implements:
Available since: N/A
Module: sap/m/SplitApp
Application Component: CA-UI5-CTR

A container control that is used to display a master-detail view, suitable for mobile applications.

Overview

The control extends the functionalities of the sap.m.SplitContainer. It adds certain header tags to the HTML page which are considered useful for mobile applications and allows the configuration of the application's home icon via the homeIcon property.

Usage

SplitApp should take the full width of the page and be used as the root of the application, not as child of another container.


Constructor

Constructor for a new SplitApp.

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.SplitApp(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
homeIcon any

Represents the icon to be displayed on the home screen of iOS devices after the user does "add to home screen". Note that only the first attempt to set the homeIcon is executed, subsequent settings are ignored. The icon must be in PNG format. The property can either store the URL of one single icon or an object holding icon URLs for the different required sizes. Note that if single icon is used for all devices, when scaled, its quality can regress. A desktop icon (used for bookmarks and overriding the favicon) can also be configured. This requires an object to be given and the "icon" property of this object then defines the desktop bookmark icon. The ICO format is supported by all browsers. ICO is also preferred for this desktop icon setting as the file can contain different images for different resolutions.

One example is:

app.setHomeIcon({ 'phone':'phone-icon.png', 'phone@2':'phone-retina.png', 'tablet':'tablet-icon.png', 'tablet@2':'tablet-retina.png', 'icon':'desktop.ico' });

The image size is 57/114 px for the phone and 72/144 px for the tablet. If an object is given but one of the sizes is not given, the largest given icon will be used for this size.

On Android, these icons may or may not be used by the device. Chances can be improved by adding glare effect, rounded corners, setting the file name to end with "-precomposed.png", and setting the homeIconPrecomposed property to true.

Visibility: public

Borrowed Properties

Name Type Default Value Description
backgroundColor string

Determines the background color of the SplitContainer. If set, this color overrides the default one, which is defined by the theme (should only be used when really required). Any configured background image will be placed above this colored background, but any theme adaptation in the Theme Designer will override this setting. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete SplitContainer or whether it should be tiled.

Since: 1.11.2.

Visibility: public
backgroundImage sap.ui.core.URI

Sets the background image of the SplitContainer. When set, this image overrides the default background defined by the theme (should only be used when really required). This background image will be placed above any color set for the background, but any theme adaptation in the Theme Designer will override this image setting. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete SplitContainer or whether it should be tiled.

Since: 1.11.2.

Visibility: public
backgroundOpacity float 1

Defines the opacity of the background image - between 0 (fully transparent) and 1 (fully opaque). This can be used to improve the content visibility by making the background image partly transparent.

Since: 1.11.2.

Visibility: public
backgroundRepeat boolean false

Defines whether the background image (if configured) is proportionally stretched to cover the whole SplitContainer (false) or whether it should be tiled (true).

Since: 1.11.2.

Visibility: public
defaultTransitionNameDetail string slide

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

Visibility: public
defaultTransitionNameMaster string slide

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

Visibility: public
masterButtonText string

Determines the text displayed in master button, which has a default value "Navigation". This text is only displayed in iOS platform and the icon from the current page in detail area is displayed in the master button for the other platforms. The master button is shown/hidden depending on the orientation of the device and whether the master area is opened or not. SplitContainer manages the show/hide of the master button by itself only when the pages added to the detail area are sap.m.Page with built-in header or sap.m.Page with built-in header, which is wrapped by one or several sap.ui.core.mvc.View. Otherwise, the show/hide of master button needs to be managed by the application.

Visibility: public
masterButtonTooltip string

Specifies the tooltip of the master button. If the tooltip is not specified, the title of the page, which is displayed is the master part, is set as tooltip to the master button.

Since: 1.48.

Visibility: public
mode sap.m.SplitAppMode ShowHideMode

Defines whether the master page will always be displayed (in portrait and landscape mode - StretchCompressMode), or if it should be hidden when in portrait mode (ShowHideMode). Default is ShowHideMode. Other possible values are Hide (Master is always hidden) and Popover (master is displayed in popover).

Visibility: public

Borrowed Aggregations

Name Cardinality Type Description
detailPages 0..n sap.ui.core.Control

Determines the content entities, between which the SplitContainer navigates in detail area. 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 receive navigation events like BeforeShow, they are documented in the pseudo interface sap.m.NavContainerChild.

masterPages 0..n sap.ui.core.Control

Determines the content entities, between which the SplitContainer navigates in master area. 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 receive navigation events like BeforeShow, they are documented in the pseudo interface sap.m.NavContainerChild.


Events Overview

Event Description
orientationChange

Fires when orientation (portrait/landscape) is changed.

orientationChange

Fires when orientation (portrait/landscape) is changed.

use {@link sap.ui.Device.orientation.attachHandler} instead.
Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
landscape boolean

Returns true if the device is in landscape mode.


Methods Overview

Method Description
attachOrientationChange

Attaches event handler fnFunction to the orientationChange event of this sap.m.SplitApp.

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

Fires when orientation (portrait/landscape) is changed.

Since 1.87 use {@link sap.ui.Device.orientation.attachHandler} instead.
detachOrientationChange

Detaches event handler fnFunction from the orientationChange event of this sap.m.SplitApp.

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

Since 1.87 use {@link sap.ui.Device.orientation.attachHandler} instead.
sap.m.SplitApp.extend

Creates a new subclass of class sap.m.SplitApp with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.m.SplitContainer.extend.

fireOrientationChange

Fires event orientationChange to attached listeners.

Since 1.87 use {@link sap.ui.Device.orientation.attachHandler} instead.
getHomeIcon

Gets current value of property homeIcon.

Represents the icon to be displayed on the home screen of iOS devices after the user does "add to home screen". Note that only the first attempt to set the homeIcon is executed, subsequent settings are ignored. The icon must be in PNG format. The property can either store the URL of one single icon or an object holding icon URLs for the different required sizes. Note that if single icon is used for all devices, when scaled, its quality can regress. A desktop icon (used for bookmarks and overriding the favicon) can also be configured. This requires an object to be given and the "icon" property of this object then defines the desktop bookmark icon. The ICO format is supported by all browsers. ICO is also preferred for this desktop icon setting as the file can contain different images for different resolutions.

One example is:

app.setHomeIcon({ 'phone':'phone-icon.png', 'phone@2':'phone-retina.png', 'tablet':'tablet-icon.png', 'tablet@2':'tablet-retina.png', 'icon':'desktop.ico' });

The image size is 57/114 px for the phone and 72/144 px for the tablet. If an object is given but one of the sizes is not given, the largest given icon will be used for this size.

On Android, these icons may or may not be used by the device. Chances can be improved by adding glare effect, rounded corners, setting the file name to end with "-precomposed.png", and setting the homeIconPrecomposed property to true.

sap.m.SplitApp.getMetadata

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

setHomeIcon

Sets a new value for property homeIcon.

Represents the icon to be displayed on the home screen of iOS devices after the user does "add to home screen". Note that only the first attempt to set the homeIcon is executed, subsequent settings are ignored. The icon must be in PNG format. The property can either store the URL of one single icon or an object holding icon URLs for the different required sizes. Note that if single icon is used for all devices, when scaled, its quality can regress. A desktop icon (used for bookmarks and overriding the favicon) can also be configured. This requires an object to be given and the "icon" property of this object then defines the desktop bookmark icon. The ICO format is supported by all browsers. ICO is also preferred for this desktop icon setting as the file can contain different images for different resolutions.

One example is:

app.setHomeIcon({ 'phone':'phone-icon.png', 'phone@2':'phone-retina.png', 'tablet':'tablet-icon.png', 'tablet@2':'tablet-retina.png', 'icon':'desktop.ico' });

The image size is 57/114 px for the phone and 72/144 px for the tablet. If an object is given but one of the sizes is not given, the largest given icon will be used for this size.

On Android, these icons may or may not be used by the device. Chances can be improved by adding glare effect, rounded corners, setting the file name to end with "-precomposed.png", and setting the homeIconPrecomposed property to true.

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

attachOrientationChange

Attaches event handler fnFunction to the orientationChange event of this sap.m.SplitApp.

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

Fires when orientation (portrait/landscape) is changed.

Since 1.87 use {@link sap.ui.Device.orientation.attachHandler} instead.
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.SplitApp itself

detachOrientationChange

Detaches event handler fnFunction from the orientationChange event of this sap.m.SplitApp.

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

Since 1.87 use {@link sap.ui.Device.orientation.attachHandler} instead.
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.SplitApp.extend

Creates a new subclass of class sap.m.SplitApp with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.m.SplitContainer.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

fireOrientationChange

Fires event orientationChange to attached listeners.

Since 1.87 use {@link sap.ui.Device.orientation.attachHandler} instead.
Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

landscape boolean

Returns true if the device is in landscape mode.

getHomeIcon

Gets current value of property homeIcon.

Represents the icon to be displayed on the home screen of iOS devices after the user does "add to home screen". Note that only the first attempt to set the homeIcon is executed, subsequent settings are ignored. The icon must be in PNG format. The property can either store the URL of one single icon or an object holding icon URLs for the different required sizes. Note that if single icon is used for all devices, when scaled, its quality can regress. A desktop icon (used for bookmarks and overriding the favicon) can also be configured. This requires an object to be given and the "icon" property of this object then defines the desktop bookmark icon. The ICO format is supported by all browsers. ICO is also preferred for this desktop icon setting as the file can contain different images for different resolutions.

One example is:

app.setHomeIcon({ 'phone':'phone-icon.png', 'phone@2':'phone-retina.png', 'tablet':'tablet-icon.png', 'tablet@2':'tablet-retina.png', 'icon':'desktop.ico' });

The image size is 57/114 px for the phone and 72/144 px for the tablet. If an object is given but one of the sizes is not given, the largest given icon will be used for this size.

On Android, these icons may or may not be used by the device. Chances can be improved by adding glare effect, rounded corners, setting the file name to end with "-precomposed.png", and setting the homeIconPrecomposed property to true.

sap.m.SplitApp.getMetadata

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

setHomeIcon

Sets a new value for property homeIcon.

Represents the icon to be displayed on the home screen of iOS devices after the user does "add to home screen". Note that only the first attempt to set the homeIcon is executed, subsequent settings are ignored. The icon must be in PNG format. The property can either store the URL of one single icon or an object holding icon URLs for the different required sizes. Note that if single icon is used for all devices, when scaled, its quality can regress. A desktop icon (used for bookmarks and overriding the favicon) can also be configured. This requires an object to be given and the "icon" property of this object then defines the desktop bookmark icon. The ICO format is supported by all browsers. ICO is also preferred for this desktop icon setting as the file can contain different images for different resolutions.

One example is:

app.setHomeIcon({ 'phone':'phone-icon.png', 'phone@2':'phone-retina.png', 'tablet':'tablet-icon.png', 'tablet@2':'tablet-retina.png', 'icon':'desktop.ico' });

The image size is 57/114 px for the phone and 72/144 px for the tablet. If an object is given but one of the sizes is not given, the largest given icon will be used for this size.

On Android, these icons may or may not be used by the device. Chances can be improved by adding glare effect, rounded corners, setting the file name to end with "-precomposed.png", and setting the homeIconPrecomposed property to true.

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

Param Type DefaultValue Description
oHomeIcon any

New value for property homeIcon