A control that represents a container with a header and content.
Cards are small user interface elements which provide the most important information from an app, related to a specific role or task. The information is represented in a compact manner, allowing for actions to be executed. Cards can be described as small representations of an app which can be integrated in different systems.
The integration card is defined in a declarative way, using a manifest.json to be:
The role of the card developer is to describe the card in a manifest.json file and define:
The role of the app developer is to integrate the card into the app and define:
width
and height
propertiesYou can learn more about integration cards in the Card Explorer
When to use
When not to use
Constructor for a new Card
.
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.ui.integration.widgets.Card(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 |
Name | Type | Default Value | Description |
---|---|---|---|
baseUrl | sap.ui.core.URI | Defines the base URL of the Card Manifest. It should be used when manifest property is an object instead of a URL. |
|
dataMode | sap.ui.integration.CardDataMode | Active | Defines the state of the |
manifest | any | empty string | The URL of the manifest or an object. Visibility: public |
manifestChanges | object[] | Defines a list of configuration settings, which will be merged into the original manifest. This can be a list of flexibility changes generated during designtime. Each level of changes is an item in the list. The change has property "content" which contains the configuration, which will be merged on top of the original Example: [ {"content": {"header": {"title": "My title"}}}, {"content": {"header": {"title": "My new title"}}} ] Since: 1.76.Visibility: public |
|
parameters | object | Overrides the default values of the parameters, which are defined in the manifest. The value is an object containing parameters in format |
Default Aggregation:
Name | Cardinality | Type | Description |
---|---|---|---|
_content | 0..1 | sap.ui.core.Control |
Defines the content of the card. |
_extension | 0..1 | sap.ui.integration.Extension |
Defines the Extension of the card. |
_filterBar | 0..1 | sap.ui.core.Control |
Defines the filters section of the card. |
_footer | 0..1 | sap.ui.core.Control |
Defines the footer of the card. |
_header | 0..1 | sap.f.cards.IHeader |
Defines the header of the card. |
_loadingProvider | 0..1 | sap.ui.core.Element |
Defines the internally used LoadingProvider. |
actionDefinitions | 0..n | sap.ui.integration.ActionDefinition |
Actions definitions from which actions in the header menu of the card are created. Note: This aggregation is destroyed when the property |
Event | Description |
---|---|
action |
Fired when an action is triggered on the card. Listeners may prevent the default action of this event by calling the |
configurationChange |
Fired when some configuration settings are changed as a result of user interaction. For example - filter value is changed. |
manifestApplied |
Fired when card utilities (like Note: The card's content may not be available yet because it may depend on other resources to load. |
manifestReady |
Fired when the manifest is loaded. |
Fired when an action is triggered on the card.
Listeners may prevent the default action of this event by calling the preventDefault
method on the event object.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
actionSource | sap.ui.core.Control |
The action source. |
manifestParameters | object |
The manifest parameters related to the triggered action. |
parameters | object |
The parameters related to the triggered action. |
type | sap.ui.integration.CardActionType |
The type of the action. |
Fired when some configuration settings are changed as a result of user interaction. For example - filter value is changed.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
changes | object |
Changed configuration settings. Example: { "/sap.card/configuration/filters/shipper/value": "key3", "/sap.card/configuration/filters/item/value": "key2", } |
Fired when card utilities (like DataProviderFactory
) and the card elements (like header) are created and initialized.
Note: The card's content may not be available yet because it may depend on other resources to load.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object |
Method | Description |
---|---|
addActionDefinition |
Adds some actionDefinition to the aggregation actionDefinitions. |
attachAction |
Attaches event handler When called, the context of the event handler (its Fired when an action is triggered on the card. |
attachConfigurationChange |
Attaches event handler When called, the context of the event handler (its Fired when some configuration settings are changed as a result of user interaction. For example - filter value is changed. |
attachManifestApplied |
Attaches event handler When called, the context of the event handler (its Fired when card utilities (like Note: The card's content may not be available yet because it may depend on other resources to load. |
attachManifestReady |
Attaches event handler When called, the context of the event handler (its Fired when the manifest is loaded. |
destroyActionDefinitions |
Destroys all the actionDefinitions in the aggregation actionDefinitions. |
detachAction |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachConfigurationChange |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachManifestApplied |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachManifestReady |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.ui.integration.widgets.Card.extend |
Creates a new subclass of class sap.ui.integration.widgets.Card with name
|
fireAction |
Fires event action to attached listeners. Listeners may prevent the default action of this event by calling the |
fireConfigurationChange |
Fires event configurationChange to attached listeners. |
fireManifestApplied |
Fires event manifestApplied to attached listeners. |
fireManifestReady |
Fires event manifestReady to attached listeners. |
getActionDefinitions |
Gets content of aggregation actionDefinitions. Actions definitions from which actions in the header menu of the card are created. Note: This aggregation is destroyed when the property |
getBaseUrl |
Gets current value of property baseUrl. Defines the base URL of the Card Manifest. It should be used when manifest property is an object instead of a URL. |
getBindingNamespaces | |
getCardContent |
Implements sap.f.ICard interface. |
getCardHeader |
Implements sap.f.ICard interface. |
getCardHeaderPosition |
Implements sap.f.ICard interface. |
getCombinedParameters |
Gets values of manifest parameters combined with the parameters from Notes - Use this method when the manifest is ready. Check - Use when developing a Component card. |
getDataMode |
Gets current value of property dataMode. Defines the state of the Default value is |
getDataProviderFactory |
Returns the |
getFocusDomRef |
Returns the DOM Element that should get the focus. |
getHost |
ID of the element which is the current target of the association host, or |
getHostInstance |
Gets the instance of the |
getManifest |
Overwrites getter for card manifest. |
getManifestChanges |
Gets current value of property manifestChanges. Defines a list of configuration settings, which will be merged into the original manifest. This can be a list of flexibility changes generated during designtime. Each level of changes is an item in the list. The change has property "content" which contains the configuration, which will be merged on top of the original Example: [ {"content": {"header": {"title": "My title"}}}, {"content": {"header": {"title": "My new title"}}} ] |
getManifestEntry |
Returns a value from the Manifest based on the specified path. Note Use this method when the manifest is ready. Check |
getManifestRawJson |
Returns a clone of the initial manifest without any processing and without any changes applied to it. |
getManifestWithMergedChanges |
Returns a clone of the original manifest with all changes from the manifestChanges property applied on top. Use during designtime. |
sap.ui.integration.widgets.Card.getMetadata |
Returns a metadata object for class sap.ui.integration.widgets.Card. |
getRuntimeUrl |
Resolves the given URL relatively to the manifest base path. Absolute paths are not changed. |
getTranslatedText |
Gets translated text from the i18n properties files configured for this card. For more details see module:sap/base/i18n/ResourceBundle#getText. |
hideLoadingPlaceholders |
Hides the loading placeholders on the whole card, or a particular section of the card. |
indexOfActionDefinition |
Checks for the provided |
insertActionDefinition |
Inserts a actionDefinition into the aggregation actionDefinitions. |
isReady | |
loadDesigntime |
Loads the module designtime/Card.designtime or the module given in "sap.card": { "designtime": "designtime/Own.designtime" } This file should contain the designtime configuration for the card. Returns a promise that resolves with an object { designtime: the designtime modules response manifest: the complete manifest json } The promise is rejected if the module cannot be loaded with an object: { error: "Card.designtime not found" } |
refresh |
Refreshes the card by re-applying the manifest settings and triggering all data requests. |
refreshData |
Refreshes the card data by triggering all data requests. |
removeActionDefinition |
Removes a actionDefinition from the aggregation actionDefinitions. |
removeAllActionDefinitions |
Removes all the controls from the aggregation actionDefinitions. Additionally, it unregisters them from the hosting UIArea. |
request |
Performs an HTTP request using the given configuration. |
resolveDestination |
Resolves the destination and returns its URL. |
setBaseUrl |
Sets a new value for property baseUrl. Defines the base URL of the Card Manifest. It should be used when manifest property is an object instead of a URL. When called with a value of |
setDataMode |
Sets a new value for the |
setHost |
Sets the associated host. |
setManifest |
Sets a new value for property manifest. The URL of the manifest or an object. When called with a value of Default value is |
setManifestChanges |
Sets a new value for property manifestChanges. Defines a list of configuration settings, which will be merged into the original manifest. This can be a list of flexibility changes generated during designtime. Each level of changes is an item in the list. The change has property "content" which contains the configuration, which will be merged on top of the original Example: [ {"content": {"header": {"title": "My title"}}}, {"content": {"header": {"title": "My new title"}}} ] When called with a value of |
showLoadingPlaceholders |
Displays the loading placeholders on the whole card, or a particular area of the card. Note: Only areas that contain binding will receive a loading placeholder. |
showMessage |
Displays a message strip on top of the content with the given text. Note Currently only available for an Adaptive Card. |
startManifestProcessing |
Starts the card's manifest processing. It will load the manifest and apply the settings written in it. This method can be called if the card needs to be used without rendering. When card is rendered it starts automatically. |
triggerAction |
Triggers an action inside the card. Use this method if you need to trigger an action programmatically from inside an For other use cases use the manifest to define the actions. See https://ui5.sap.com/test-resources/sap/ui/integration/demokit/cardExplorer/webapp/index.html#/learn/features/cardActions
Example
oCard.triggerAction({ type: "Navigation", parameters: { url: "...", target: "_blank" } }); |
Adds some actionDefinition to the aggregation actionDefinitions.
Param | Type | DefaultValue | Description |
---|---|---|---|
oActionDefinition | sap.ui.integration.ActionDefinition |
The actionDefinition to add; if empty, nothing is inserted |
Attaches event handler fnFunction
to the action event of this sap.ui.integration.widgets.Card
.
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.integration.widgets.Card
itself.
Fired when an action is triggered on the card.
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 |
Attaches event handler fnFunction
to the configurationChange event of this sap.ui.integration.widgets.Card
.
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.integration.widgets.Card
itself.
Fired when some configuration settings are changed as a result of user interaction. For example - filter value is changed.
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 |
Attaches event handler fnFunction
to the manifestApplied event of this sap.ui.integration.widgets.Card
.
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.integration.widgets.Card
itself.
Fired when card utilities (like DataProviderFactory
) and the card elements (like header) are created and initialized.
Note: The card's content may not be available yet because it may depend on other resources to load.
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 |
Attaches event handler fnFunction
to the manifestReady event of this sap.ui.integration.widgets.Card
.
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.integration.widgets.Card
itself.
Fired when the manifest is loaded.
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 |
Detaches event handler fnFunction
from the action event of this sap.ui.integration.widgets.Card
.
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 |
Detaches event handler fnFunction
from the configurationChange event of this sap.ui.integration.widgets.Card
.
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 |
Detaches event handler fnFunction
from the manifestApplied event of this sap.ui.integration.widgets.Card
.
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 |
Detaches event handler fnFunction
from the manifestReady event of this sap.ui.integration.widgets.Card
.
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 |
Creates a new subclass of class sap.ui.integration.widgets.Card with name sClassName
and enriches it with the information contained in oClassInfo
.
oClassInfo
might contain the same kind of information as described in sap.f.CardBase.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 action to attached listeners.
Listeners may prevent the default action of this event by calling the preventDefault
method on the event object. The return value of this method indicates whether the default action should be executed.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
actionSource | sap.ui.core.Control |
The action source. |
|
manifestParameters | object |
The manifest parameters related to the triggered action. |
|
parameters | object |
The parameters related to the triggered action. |
|
type | sap.ui.integration.CardActionType |
The type of the action. |
Fires event configurationChange to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
changes | object |
Changed configuration settings. Example: { "/sap.card/configuration/filters/shipper/value": "key3", "/sap.card/configuration/filters/item/value": "key2", } |
Fires event manifestApplied to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
Fires event manifestReady to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
Gets content of aggregation actionDefinitions.
Actions definitions from which actions in the header menu of the card are created. Note: This aggregation is destroyed when the property manifest
changes.
Gets current value of property baseUrl.
Defines the base URL of the Card Manifest. It should be used when manifest property is an object instead of a URL.
Gets values of manifest parameters combined with the parameters from parameters
property.
Notes
- Use this method when the manifest is ready. Check manifestReady
event.
- Use when developing a Component card.
Gets current value of property dataMode.
Defines the state of the Card
. When set to Inactive
, the Card
doesn't make requests.
Default value is Active
.
Gets current value of property manifestChanges.
Defines a list of configuration settings, which will be merged into the original manifest.
This can be a list of flexibility changes generated during designtime.
Each level of changes is an item in the list. The change has property "content" which contains the configuration, which will be merged on top of the original sap.card
section.
Example:
[ {"content": {"header": {"title": "My title"}}}, {"content": {"header": {"title": "My new title"}}} ]
Returns a value from the Manifest based on the specified path.
Note Use this method when the manifest is ready. Check manifestReady
event.
Param | Type | DefaultValue | Description |
---|---|---|---|
sPath | string |
The path to return a value for. |
Returns a clone of the initial manifest without any processing and without any changes applied to it.
Returns a clone of the original manifest with all changes from the manifestChanges property applied on top.
Use during designtime.
Returns a metadata object for class sap.ui.integration.widgets.Card.
Resolves the given URL relatively to the manifest base path. Absolute paths are not changed.
Param | Type | DefaultValue | Description |
---|---|---|---|
sUrl | string |
The URL to resolve. |
Gets translated text from the i18n properties files configured for this card.
For more details see module:sap/base/i18n/ResourceBundle#getText.
Param | Type | DefaultValue | Description |
---|---|---|---|
sKey | string |
Key to retrieve the text for |
|
aArgs | string[] |
List of parameter values which should replace the placeholders "{n}" (n is the index) in the found locale-specific string value. Note that the replacement is done whenever |
|
bIgnoreKeyFallback | boolean | false |
If set, |
Hides the loading placeholders on the whole card, or a particular section of the card.
Param | Type | DefaultValue | Description |
---|---|---|---|
eCardArea | sap.ui.integration.CardArea |
Area of the card to show the loading placeholders on. Possible options are 'Header', 'Content', 'Filters'. Leave empty to hide loading placeholders on all areas of the card. |
Checks for the provided sap.ui.integration.ActionDefinition
in the aggregation actionDefinitions. and returns its index if found or -1 otherwise.
Param | Type | DefaultValue | Description |
---|---|---|---|
oActionDefinition | sap.ui.integration.ActionDefinition |
The actionDefinition whose index is looked for |
Inserts a actionDefinition into the aggregation actionDefinitions.
Param | Type | DefaultValue | Description |
---|---|---|---|
oActionDefinition | sap.ui.integration.ActionDefinition |
The actionDefinition to insert; if empty, nothing is inserted |
|
iIndex | int |
The |
Loads the module designtime/Card.designtime or the module given in "sap.card": { "designtime": "designtime/Own.designtime" } This file should contain the designtime configuration for the card.
Returns a promise that resolves with an object { designtime: the designtime modules response manifest: the complete manifest json } The promise is rejected if the module cannot be loaded with an object: { error: "Card.designtime not found" }
Removes a actionDefinition from the aggregation actionDefinitions.
Param | Type | DefaultValue | Description |
---|---|---|---|
vActionDefinition | int string sap.ui.integration.ActionDefinition |
The actionDefinition to remove or its index or id |
Removes all the controls from the aggregation actionDefinitions.
Additionally, it unregisters them from the hosting UIArea.
Performs an HTTP request using the given configuration.
Param | Type | DefaultValue | Description |
---|---|---|---|
oConfiguration | object |
The configuration of the request. |
|
URL | string |
The URL of the resource. |
|
mode | string | "cors" |
The mode of the request. Possible values are "cors", "no-cors", "same-origin". |
method | string | "GET" |
The HTTP method. Possible values are "GET", "POST". |
parameters | Object |
The request parameters. If the method is "POST" the parameters will be put as key/value pairs into the body of the request. |
|
dataType | Object | "json" |
The expected Content-Type of the response. Possible values are "xml", "json", "text", "script", "html", "jsonp". Note: Complex Binding is not supported when a dataType is provided. Serialization of the response to an object is up to the developer. |
headers | Object |
The HTTP headers of the request. |
|
withCredentials | boolean | false |
Indicates whether cross-site requests should be made using credentials. |
Resolves the destination and returns its URL.
Param | Type | DefaultValue | Description |
---|---|---|---|
sKey | string |
The destination's key used in the configuration. |
Sets a new value for property baseUrl.
Defines the base URL of the Card Manifest. It should be used when manifest property is an object instead of a URL.
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sBaseUrl | sap.ui.core.URI |
New value for property |
Sets a new value for the dataMode
property.
Param | Type | DefaultValue | Description |
---|---|---|---|
sMode | sap.ui.integration.CardDataMode |
The mode to set to the Card. |
Sets the associated host.
Param | Type | DefaultValue | Description |
---|---|---|---|
oHost | sap.ui.core.ID sap.ui.core.Control |
ID of an element which becomes the new target of this host association; alternatively, an element instance may be given |
Sets a new value for property manifest.
The URL of the manifest or an object.
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 |
---|---|---|---|
oManifest | any | "" |
New value for property |
Sets a new value for property manifestChanges.
Defines a list of configuration settings, which will be merged into the original manifest.
This can be a list of flexibility changes generated during designtime.
Each level of changes is an item in the list. The change has property "content" which contains the configuration, which will be merged on top of the original sap.card
section.
Example:
[ {"content": {"header": {"title": "My title"}}}, {"content": {"header": {"title": "My new title"}}} ]
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sManifestChanges | object[] |
New value for property |
Displays the loading placeholders on the whole card, or a particular area of the card. Note: Only areas that contain binding will receive a loading placeholder.
Param | Type | DefaultValue | Description |
---|---|---|---|
eCardArea | sap.ui.integration.CardArea |
Area of the card to show the loading placeholders on. Possible options are 'Header', 'Content', 'Filters'. Leave empty to show loading placeholders on all areas of the card. |
Displays a message strip on top of the content with the given text.
Note Currently only available for an Adaptive Card.
Param | Type | DefaultValue | Description |
---|---|---|---|
sMessage | string |
The message. |
|
sType | sap.ui.core.MessageType |
Type of the message. |
Starts the card's manifest processing. It will load the manifest and apply the settings written in it. This method can be called if the card needs to be used without rendering. When card is rendered it starts automatically.
Triggers an action inside the card.
Use this method if you need to trigger an action programmatically from inside an Extension
or from a Component card.
For other use cases use the manifest to define the actions. See https://ui5.sap.com/test-resources/sap/ui/integration/demokit/cardExplorer/webapp/index.html#/learn/features/cardActions
oCard.triggerAction({ type: "Navigation", parameters: { url: "...", target: "_blank" } });
Param | Type | DefaultValue | Description |
---|---|---|---|
oAction | object |
The settings of the action. |
|
type | sap.ui.integration.CardActionType |
The type of the action. |
|
parameters | object |
Additional parameters which will be used by the action handler to perform the action. |