class sap.f.IllustratedMessage

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

A combination of message and illustration to represent an empty or a success state.

Overview

An IllustratedMessage is a recommended combination of a solution-oriented message, an engaging illustration, and conversational tone to better communicate an empty or a success state than just show a message alone. Empty states are moments in the user experience where there’s no data to display. Success states are occasions to celebrate and reward a user’s special accomplishment or the completion of an important task.

The IllustratedMessage control is meant to be used inside container controls, for example a Card, a Dialog, or a Page.

Structure

The IllustratedMessage consists of the following elements, which are displayed below each other in the following order:

Responsive Behavior

The IllustratedMessage control can adapt depending on the API settings provided by the app developer and the available space of its parent container. Some of the structural elements are displayed differently or are omitted in the different breakpoint sizes (XS, S, M, L).

This control can be a drop target.

Constructor

Constructor for a new IllustratedMessage.

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.f.IllustratedMessage(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
description string empty string

Defines the description displayed below the title.

If there is no initial input from the app developer and the default illustration set is being used, a default description for the current illustration type is going to be displayed. The default description is stored in the sap.f resource bundle.

Since: 1.88.

Visibility: public
enableFormattedText boolean false

Defines whether the value set in the description property is displayed as formatted text in HTML format.

For details regarding supported HTML tags, see sap.m.FormattedText.

Since: 1.88.

Visibility: public
illustrationSize sap.f.IllustratedMessageSize Auto

Determines which illustration breakpoint variant is used.

As IllustratedMessage adapts itself around the Illustration, the other elements of the control are displayed differently on the different breakpoints/illustration sizes.

Since: 1.88.

Visibility: public
illustrationType string sap.f.IllustratedMessageType.NoSearchResults

Determines which illustration type is displayed.

Note: The sap.f.IllustratedMessageType enumeration contains a default illustration set. If you want to use another illustration set, you have to register it in the sap.f.IllustrationPool.

Example input for the illustrationType property is sapIllus-UnableToLoad. The logic behind this format is as follows:

  • First is the the illustration set - sapIllus
  • Second is the illustration type - UnableToLoad


Since: 1.88.

Visibility: public
title string empty string

Defines the title that is displayed below the illustration.

If there is no initial input from the app developer and the default illustration set is being used, a default title is displayed corresponding to the current illustrationType.

Since: 1.88.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
_formattedText 0..1 sap.m.FormattedText

The description displayed under the title when enableFormattedText is true.

Since: 1.88.

_illustration 0..1 sap.f.Illustration

Defines the illustration used, according to the illustrationType property and the current state of IllustratedMessage.

It is placed above all other aggregations. Not displayed illustrationSize is set to Base.

Since: 1.88.

_text 0..1 sap.m.Text

The description displayed under the title when enableFormattedText is false.

Since: 1.88.

_title 0..1 sap.m.Title

The text displayed under the illustration.

Since: 1.88.

additionalContent 0..n sap.m.Button

Defines the controls placed below the description as additional content.

Note: Not displayed when illustrationSize is set to Base.

Since: 1.88.


Methods Overview

Method Description
addAdditionalContent

Adds some additionalContent to the aggregation additionalContent.

destroyAdditionalContent

Destroys all the additionalContent in the aggregation additionalContent.

sap.f.IllustratedMessage.extend

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

getAdditionalContent

Gets content of aggregation additionalContent.

Defines the controls placed below the description as additional content.

Note: Not displayed when illustrationSize is set to Base.

getDescription

Gets current value of property description.

Defines the description displayed below the title.

If there is no initial input from the app developer and the default illustration set is being used, a default description for the current illustration type is going to be displayed. The default description is stored in the sap.f resource bundle.

Default value is empty string.

getEnableFormattedText

Gets current value of property enableFormattedText.

Defines whether the value set in the description property is displayed as formatted text in HTML format.

For details regarding supported HTML tags, see sap.m.FormattedText.

Default value is false.

getIllustrationSize

Gets current value of property illustrationSize.

Determines which illustration breakpoint variant is used.

As IllustratedMessage adapts itself around the Illustration, the other elements of the control are displayed differently on the different breakpoints/illustration sizes.

Default value is Auto.

getIllustrationType

Gets current value of property illustrationType.

Determines which illustration type is displayed.

Note: The sap.f.IllustratedMessageType enumeration contains a default illustration set. If you want to use another illustration set, you have to register it in the sap.f.IllustrationPool.

Example input for the illustrationType property is sapIllus-UnableToLoad. The logic behind this format is as follows:

  • First is the the illustration set - sapIllus
  • Second is the illustration type - UnableToLoad

Default value is IllustratedMessageType.NoSearchResults.

sap.f.IllustratedMessage.getMetadata

Returns a metadata object for class sap.f.IllustratedMessage.

getTitle

Gets current value of property title.

Defines the title that is displayed below the illustration.

If there is no initial input from the app developer and the default illustration set is being used, a default title is displayed corresponding to the current illustrationType.

Default value is empty string.

indexOfAdditionalContent

Checks for the provided sap.m.Button in the aggregation additionalContent. and returns its index if found or -1 otherwise.

insertAdditionalContent

Inserts a additionalContent into the aggregation additionalContent.

removeAdditionalContent

Removes a additionalContent from the aggregation additionalContent.

removeAllAdditionalContent

Removes all the controls from the aggregation additionalContent.

Additionally, it unregisters them from the hosting UIArea.

setDescription

Sets a new value for property description.

Defines the description displayed below the title.

If there is no initial input from the app developer and the default illustration set is being used, a default description for the current illustration type is going to be displayed. The default description is stored in the sap.f resource bundle.

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

Default value is empty string.

setEnableFormattedText

Sets a new value for property enableFormattedText.

Defines whether the value set in the description property is displayed as formatted text in HTML format.

For details regarding supported HTML tags, see sap.m.FormattedText.

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

Default value is false.

setIllustrationSize

Sets a new value for property illustrationSize.

Determines which illustration breakpoint variant is used.

As IllustratedMessage adapts itself around the Illustration, the other elements of the control are displayed differently on the different breakpoints/illustration sizes.

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

Default value is Auto.

setTitle

Sets a new value for property title.

Defines the title that is displayed below the illustration.

If there is no initial input from the app developer and the default illustration set is being used, a default title is displayed corresponding to the current illustrationType.

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

Default value is empty string.

addAdditionalContent

Adds some additionalContent to the aggregation additionalContent.

Param Type DefaultValue Description
oAdditionalContent sap.m.Button

The additionalContent to add; if empty, nothing is inserted

destroyAdditionalContent

Destroys all the additionalContent in the aggregation additionalContent.

sap.f.IllustratedMessage.extend

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

getAdditionalContent

Gets content of aggregation additionalContent.

Defines the controls placed below the description as additional content.

Note: Not displayed when illustrationSize is set to Base.

getDescription

Gets current value of property description.

Defines the description displayed below the title.

If there is no initial input from the app developer and the default illustration set is being used, a default description for the current illustration type is going to be displayed. The default description is stored in the sap.f resource bundle.

Default value is empty string.

getEnableFormattedText

Gets current value of property enableFormattedText.

Defines whether the value set in the description property is displayed as formatted text in HTML format.

For details regarding supported HTML tags, see sap.m.FormattedText.

Default value is false.

getIllustrationSize

Gets current value of property illustrationSize.

Determines which illustration breakpoint variant is used.

As IllustratedMessage adapts itself around the Illustration, the other elements of the control are displayed differently on the different breakpoints/illustration sizes.

Default value is Auto.

getIllustrationType

Gets current value of property illustrationType.

Determines which illustration type is displayed.

Note: The sap.f.IllustratedMessageType enumeration contains a default illustration set. If you want to use another illustration set, you have to register it in the sap.f.IllustrationPool.

Example input for the illustrationType property is sapIllus-UnableToLoad. The logic behind this format is as follows:

Default value is IllustratedMessageType.NoSearchResults.

sap.f.IllustratedMessage.getMetadata

Returns a metadata object for class sap.f.IllustratedMessage.

getTitle

Gets current value of property title.

Defines the title that is displayed below the illustration.

If there is no initial input from the app developer and the default illustration set is being used, a default title is displayed corresponding to the current illustrationType.

Default value is empty string.

indexOfAdditionalContent

Checks for the provided sap.m.Button in the aggregation additionalContent. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oAdditionalContent sap.m.Button

The additionalContent whose index is looked for

insertAdditionalContent

Inserts a additionalContent into the aggregation additionalContent.

Param Type DefaultValue Description
oAdditionalContent sap.m.Button

The additionalContent to insert; if empty, nothing is inserted

iIndex int

The 0-based index the additionalContent should be inserted at; for a negative value of iIndex, the additionalContent is inserted at position 0; for a value greater than the current size of the aggregation, the additionalContent is inserted at the last position

removeAdditionalContent

Removes a additionalContent from the aggregation additionalContent.

Param Type DefaultValue Description
vAdditionalContent int string sap.m.Button

The additionalContent to remove or its index or id

removeAllAdditionalContent

Removes all the controls from the aggregation additionalContent.

Additionally, it unregisters them from the hosting UIArea.

setDescription

Sets a new value for property description.

Defines the description displayed below the title.

If there is no initial input from the app developer and the default illustration set is being used, a default description for the current illustration type is going to be displayed. The default description is stored in the sap.f resource bundle.

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

Default value is empty string.

Param Type DefaultValue Description
sDescription string ""

New value for property description

setEnableFormattedText

Sets a new value for property enableFormattedText.

Defines whether the value set in the description property is displayed as formatted text in HTML format.

For details regarding supported HTML tags, see sap.m.FormattedText.

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
bEnableFormattedText boolean false

New value for property enableFormattedText

setIllustrationSize

Sets a new value for property illustrationSize.

Determines which illustration breakpoint variant is used.

As IllustratedMessage adapts itself around the Illustration, the other elements of the control are displayed differently on the different breakpoints/illustration sizes.

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

Default value is Auto.

Param Type DefaultValue Description
sIllustrationSize sap.f.IllustratedMessageSize Auto

New value for property illustrationSize

setTitle

Sets a new value for property title.

Defines the title that is displayed below the illustration.

If there is no initial input from the app developer and the default illustration set is being used, a default title is displayed corresponding to the current illustrationType.

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

Default value is empty string.

Param Type DefaultValue Description
sTitle string ""

New value for property title