class sap.m.Shell

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

The Shell control can be used as root element of applications. It can contain an App or a SplitApp control. The Shell provides some overarching functionality for the overall application and takes care of visual adaptation, such as a frame around the App, on desktop browser platforms.


Constructor

Constructor for a new Shell.

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.Shell(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
appWidthLimited boolean true

Determines whether the width of the content (the aggregated App) should be limited or extended to the full screen width.

Visibility: public
backgroundColor sap.ui.core.CSSColor

Defines the background color of the Shell. If set, this color will override the default background defined by the theme. This should only be set when really required. Any configured background image will be placed above this colored background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

Since: 1.11.2.

Visibility: public
backgroundImage sap.ui.core.URI

Defines the background image of the Shell. If set, this image will override the default background defined by the theme. This should only be set when really required. This background image will be placed above any color set for the background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

Since: 1.11.2.

Visibility: public
backgroundOpacity float 1

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

Since: 1.11.2.

Visibility: public
backgroundRepeat boolean false

Determines whether the background image (if configured) should be proportionally stretched to cover the whole Shell (false, default) or whether it should be tiled (true).

Since: 1.11.2.

Visibility: public
headerRightText string

Defines texts, such as the name of the logged-in user, which should be displayed on the right side of the header (if there is enough space to display the header at all - this only happens on very tall screens (1568px height), otherwise, it is always hidden).

Visibility: public
homeIcon object

Sets the icon used for the mobile device home screen and the icon to be used for bookmarks by desktop browsers.

This property should be only set once, and as early as possible. Subsequent calls replace the previous icon settings and may lead to different behavior depending on the browser.

Different image sizes for device home screen need to be given as PNG images, an ICO file needs to be given as desktop browser bookmark icon (other file formats may not work in all browsers). The precomposed flag defines whether there is already a glow effect contained in the home screen images (or whether iOS should add such an effect). The given structure could look like this: { 'phone':'phone-icon_57x57.png', 'phone@2':'phone-retina_114x114.png', 'tablet':'tablet-icon_72x72.png', 'tablet@2':'tablet-retina_144x144.png', 'precomposed':true, 'favicon':'favicon.ico' }

See jQuery.sap.setIcons() for full documentation.

Visibility: public
showLogout boolean true

Determines whether the Logout button should be displayed. Currently, this only happens on very tall screens (1568px height), otherwise, it is always hidden.

Visibility: public
title string

Defines the application title, which may or may not be displayed outside the actual application, depending on the available screen size.

Visibility: public
titleLevel sap.ui.core.TitleLevel H1

Defines the semantic level of the title.

This information is used by assistive technologies, such as screen readers to create a hierarchical site map for faster navigation. Depending on this setting an HTML h1-h6 element is used.

Visibility: public

Aggregations

Default Aggregation: app

Name Cardinality Type Description
app (default) 0..1 sap.ui.core.Control

A Shell contains an App or a SplitApp (they may be wrapped in a View). Other control types are not allowed.


Events Overview

Event Description
logout

Fires when the user presses the logout button/link.

logout

Fires when the user presses the logout button/link.

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

Methods Overview

Method Description
attachLogout

Attaches event handler fnFunction to the logout event of this sap.m.Shell.

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

Fires when the user presses the logout button/link.

destroyApp

Destroys the app in the aggregation app.

detachLogout

Detaches event handler fnFunction from the logout event of this sap.m.Shell.

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

sap.m.Shell.extend

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

fireLogout

Fires event logout to attached listeners.

getApp

Gets content of aggregation app.

A Shell contains an App or a SplitApp (they may be wrapped in a View). Other control types are not allowed.

getAppWidthLimited

Gets current value of property appWidthLimited.

Determines whether the width of the content (the aggregated App) should be limited or extended to the full screen width.

Default value is true.

getBackgroundColor

Gets current value of property backgroundColor.

Defines the background color of the Shell. If set, this color will override the default background defined by the theme. This should only be set when really required. Any configured background image will be placed above this colored background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

getBackgroundImage

Gets current value of property backgroundImage.

Defines the background image of the Shell. If set, this image will override the default background defined by the theme. This should only be set when really required. This background image will be placed above any color set for the background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

getBackgroundOpacity

Gets current value of property backgroundOpacity.

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

Default value is 1.

getBackgroundRepeat

Gets current value of property backgroundRepeat.

Determines whether the background image (if configured) should be proportionally stretched to cover the whole Shell (false, default) or whether it should be tiled (true).

Default value is false.

getHeaderRightText

Gets current value of property headerRightText.

Defines texts, such as the name of the logged-in user, which should be displayed on the right side of the header (if there is enough space to display the header at all - this only happens on very tall screens (1568px height), otherwise, it is always hidden).

getHomeIcon

Gets current value of property homeIcon.

Sets the icon used for the mobile device home screen and the icon to be used for bookmarks by desktop browsers.

This property should be only set once, and as early as possible. Subsequent calls replace the previous icon settings and may lead to different behavior depending on the browser.

Different image sizes for device home screen need to be given as PNG images, an ICO file needs to be given as desktop browser bookmark icon (other file formats may not work in all browsers). The precomposed flag defines whether there is already a glow effect contained in the home screen images (or whether iOS should add such an effect). The given structure could look like this: { 'phone':'phone-icon_57x57.png', 'phone@2':'phone-retina_114x114.png', 'tablet':'tablet-icon_72x72.png', 'tablet@2':'tablet-retina_144x144.png', 'precomposed':true, 'favicon':'favicon.ico' }

See jQuery.sap.setIcons() for full documentation.

getLogo

Gets current value of property logo.

Defines the logo to be displayed next to the App when the screen is sufficiently large.

Note: If property value isn't set, then the logo address is taken from the theme parameters. For reference please see: sap.ui.core.theming.Parameters

sap.m.Shell.getMetadata

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

getShowLogout

Gets current value of property showLogout.

Determines whether the Logout button should be displayed. Currently, this only happens on very tall screens (1568px height), otherwise, it is always hidden.

Default value is true.

getTitle

Gets current value of property title.

Defines the application title, which may or may not be displayed outside the actual application, depending on the available screen size.

getTitleLevel

Gets current value of property titleLevel.

Defines the semantic level of the title.

This information is used by assistive technologies, such as screen readers to create a hierarchical site map for faster navigation. Depending on this setting an HTML h1-h6 element is used.

Default value is H1.

setApp

Sets the aggregated app.

setAppWidthLimited

Sets a new value for property appWidthLimited.

Determines whether the width of the content (the aggregated App) should be limited or extended to the full screen width.

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

Default value is true.

setBackgroundColor

Sets a new value for property backgroundColor.

Defines the background color of the Shell. If set, this color will override the default background defined by the theme. This should only be set when really required. Any configured background image will be placed above this colored background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

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

setBackgroundImage

Sets a new value for property backgroundImage.

Defines the background image of the Shell. If set, this image will override the default background defined by the theme. This should only be set when really required. This background image will be placed above any color set for the background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

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

setBackgroundOpacity

Sets a new value for property backgroundOpacity.

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

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

Default value is 1.

setBackgroundRepeat

Sets a new value for property backgroundRepeat.

Determines whether the background image (if configured) should be proportionally stretched to cover the whole Shell (false, default) or whether it should be tiled (true).

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

Default value is false.

setHeaderRightText

Sets a new value for property headerRightText.

Defines texts, such as the name of the logged-in user, which should be displayed on the right side of the header (if there is enough space to display the header at all - this only happens on very tall screens (1568px height), otherwise, it is always hidden).

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

setHomeIcon

Sets a new value for property homeIcon.

Sets the icon used for the mobile device home screen and the icon to be used for bookmarks by desktop browsers.

This property should be only set once, and as early as possible. Subsequent calls replace the previous icon settings and may lead to different behavior depending on the browser.

Different image sizes for device home screen need to be given as PNG images, an ICO file needs to be given as desktop browser bookmark icon (other file formats may not work in all browsers). The precomposed flag defines whether there is already a glow effect contained in the home screen images (or whether iOS should add such an effect). The given structure could look like this: { 'phone':'phone-icon_57x57.png', 'phone@2':'phone-retina_114x114.png', 'tablet':'tablet-icon_72x72.png', 'tablet@2':'tablet-retina_144x144.png', 'precomposed':true, 'favicon':'favicon.ico' }

See jQuery.sap.setIcons() for full documentation.

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

setLogo

Sets a new value for property logo.

Defines the logo to be displayed next to the App when the screen is sufficiently large.

Note: If property value isn't set, then the logo address is taken from the theme parameters. For reference please see: sap.ui.core.theming.Parameters

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

setShowLogout

Sets a new value for property showLogout.

Determines whether the Logout button should be displayed. Currently, this only happens on very tall screens (1568px height), otherwise, it is always hidden.

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

Default value is true.

setTitle

Sets a new value for property title.

Defines the application title, which may or may not be displayed outside the actual application, depending on the available screen size.

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

setTitleLevel

Sets a new value for property titleLevel.

Defines the semantic level of the title.

This information is used by assistive technologies, such as screen readers to create a hierarchical site map for faster navigation. Depending on this setting an HTML h1-h6 element is used.

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

Default value is H1.

attachLogout

Attaches event handler fnFunction to the logout event of this sap.m.Shell.

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

Fires when the user presses the logout button/link.

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

destroyApp

Destroys the app in the aggregation app.

detachLogout

Detaches event handler fnFunction from the logout event of this sap.m.Shell.

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.Shell.extend

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

fireLogout

Fires event logout to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

getApp

Gets content of aggregation app.

A Shell contains an App or a SplitApp (they may be wrapped in a View). Other control types are not allowed.

getAppWidthLimited

Gets current value of property appWidthLimited.

Determines whether the width of the content (the aggregated App) should be limited or extended to the full screen width.

Default value is true.

getBackgroundColor

Gets current value of property backgroundColor.

Defines the background color of the Shell. If set, this color will override the default background defined by the theme. This should only be set when really required. Any configured background image will be placed above this colored background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

getBackgroundImage

Gets current value of property backgroundImage.

Defines the background image of the Shell. If set, this image will override the default background defined by the theme. This should only be set when really required. This background image will be placed above any color set for the background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

getBackgroundOpacity

Gets current value of property backgroundOpacity.

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

Default value is 1.

getBackgroundRepeat

Gets current value of property backgroundRepeat.

Determines whether the background image (if configured) should be proportionally stretched to cover the whole Shell (false, default) or whether it should be tiled (true).

Default value is false.

getHeaderRightText

Gets current value of property headerRightText.

Defines texts, such as the name of the logged-in user, which should be displayed on the right side of the header (if there is enough space to display the header at all - this only happens on very tall screens (1568px height), otherwise, it is always hidden).

getHomeIcon

Gets current value of property homeIcon.

Sets the icon used for the mobile device home screen and the icon to be used for bookmarks by desktop browsers.

This property should be only set once, and as early as possible. Subsequent calls replace the previous icon settings and may lead to different behavior depending on the browser.

Different image sizes for device home screen need to be given as PNG images, an ICO file needs to be given as desktop browser bookmark icon (other file formats may not work in all browsers). The precomposed flag defines whether there is already a glow effect contained in the home screen images (or whether iOS should add such an effect). The given structure could look like this: { 'phone':'phone-icon_57x57.png', 'phone@2':'phone-retina_114x114.png', 'tablet':'tablet-icon_72x72.png', 'tablet@2':'tablet-retina_144x144.png', 'precomposed':true, 'favicon':'favicon.ico' }

See jQuery.sap.setIcons() for full documentation.

sap.m.Shell.getMetadata

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

getShowLogout

Gets current value of property showLogout.

Determines whether the Logout button should be displayed. Currently, this only happens on very tall screens (1568px height), otherwise, it is always hidden.

Default value is true.

getTitle

Gets current value of property title.

Defines the application title, which may or may not be displayed outside the actual application, depending on the available screen size.

getTitleLevel

Gets current value of property titleLevel.

Defines the semantic level of the title.

This information is used by assistive technologies, such as screen readers to create a hierarchical site map for faster navigation. Depending on this setting an HTML h1-h6 element is used.

Default value is H1.

setApp

Sets the aggregated app.

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

The app to set

setAppWidthLimited

Sets a new value for property appWidthLimited.

Determines whether the width of the content (the aggregated App) should be limited or extended to the full screen width.

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
bAppWidthLimited boolean true

New value for property appWidthLimited

setBackgroundColor

Sets a new value for property backgroundColor.

Defines the background color of the Shell. If set, this color will override the default background defined by the theme. This should only be set when really required. Any configured background image will be placed above this colored background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

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

Param Type DefaultValue Description
sBackgroundColor sap.ui.core.CSSColor

New value for property backgroundColor

setBackgroundImage

Sets a new value for property backgroundImage.

Defines the background image of the Shell. If set, this image will override the default background defined by the theme. This should only be set when really required. This background image will be placed above any color set for the background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

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

Param Type DefaultValue Description
sBackgroundImage sap.ui.core.URI

New value for property backgroundImage

setBackgroundOpacity

Sets a new value for property backgroundOpacity.

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

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

Default value is 1.

Param Type DefaultValue Description
fBackgroundOpacity float 1

New value for property backgroundOpacity

setBackgroundRepeat

Sets a new value for property backgroundRepeat.

Determines whether the background image (if configured) should be proportionally stretched to cover the whole Shell (false, default) or whether it should be tiled (true).

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

Default value is false.

Param Type DefaultValue Description
bBackgroundRepeat boolean false

New value for property backgroundRepeat

setHeaderRightText

Sets a new value for property headerRightText.

Defines texts, such as the name of the logged-in user, which should be displayed on the right side of the header (if there is enough space to display the header at all - this only happens on very tall screens (1568px height), otherwise, it is always hidden).

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

Param Type DefaultValue Description
sHeaderRightText string

New value for property headerRightText

setHomeIcon

Sets a new value for property homeIcon.

Sets the icon used for the mobile device home screen and the icon to be used for bookmarks by desktop browsers.

This property should be only set once, and as early as possible. Subsequent calls replace the previous icon settings and may lead to different behavior depending on the browser.

Different image sizes for device home screen need to be given as PNG images, an ICO file needs to be given as desktop browser bookmark icon (other file formats may not work in all browsers). The precomposed flag defines whether there is already a glow effect contained in the home screen images (or whether iOS should add such an effect). The given structure could look like this: { 'phone':'phone-icon_57x57.png', 'phone@2':'phone-retina_114x114.png', 'tablet':'tablet-icon_72x72.png', 'tablet@2':'tablet-retina_144x144.png', 'precomposed':true, 'favicon':'favicon.ico' }

See jQuery.sap.setIcons() for full documentation.

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

Param Type DefaultValue Description
oHomeIcon object

New value for property homeIcon

setShowLogout

Sets a new value for property showLogout.

Determines whether the Logout button should be displayed. Currently, this only happens on very tall screens (1568px height), otherwise, it is always hidden.

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
bShowLogout boolean true

New value for property showLogout

setTitle

Sets a new value for property title.

Defines the application title, which may or may not be displayed outside the actual application, depending on the available screen size.

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

Param Type DefaultValue Description
sTitle string

New value for property title

setTitleLevel

Sets a new value for property titleLevel.

Defines the semantic level of the title.

This information is used by assistive technologies, such as screen readers to create a hierarchical site map for faster navigation. Depending on this setting an HTML h1-h6 element is used.

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

Default value is H1.

Param Type DefaultValue Description
sTitleLevel sap.ui.core.TitleLevel H1

New value for property titleLevel