Design-time Configurations and APIs
The Card Editor will use the design-time module to create the user interface for administrator, page/content administrator and translator. Build in configuration settings allow to easily create an appealing UI for the user.

Create a Design-time module and register it in the Cards manifest
Advanced design-time configuration and implementation should happen outside the manifest of the Card.
With that design-time code will not harm or influence the runtime or the Card instance for the end-user.
Create a folder "dt" besides the manifest.json to store all designt-time related artifacts.
Create a designtime.js file in this new folder.
Add the following inital module setup into the js file.
sap.ui.define(["sap/ui/integration/Designtime"], function ( Designtime ) { "use strict"; return function () { return new Designtime({ "form": { "items": { //here goes the configuration } }, "preview": { "modes": "Abstract" } }); }; });
Similar to a Card Extension, the design-time module is registered in the manifest. As soon as the Card Editor is launched.
"sap.card": { "designtime": "dt/designtime" }
Configure the editor's form
Within the configuration the form section will contain the items that are shown in the Editor
sap.ui.define(["sap/ui/integration/Designtime"], function ( Designtime ) { "use strict"; return function () { return new Designtime({ "form": { "items": { } }, "preview": { "modes": "Abstract" } }); }; }); |
![]() |
Form Items
The items section is a map of item configuration.
Try it Out
Property | Type | Required | Default | Description | Since |
---|---|---|---|---|---|
manifestpath | string | Yes | Path to the manifest value that should be edited.
In case a the type of the item is "group" the path can be omited.
manifestpath : "sap.card/configuration/parameters/title/value" |
1.83 | |
type | string | Yes | "string" | Type of the value in the manifest that is edited. Currently "string", "integer", "number",
"date", "datetime", "boolean", "string[]" are supported. type="group" in an item will allow to set an expandable panel within the form. It will contains all the parameters behind it and before the next item which type is "group" too. For a group typed item the manifestpath setting can be omitted. A label should be provided. type : "string" |
1.83 |
label | string | No | Name of the item in the form/items collection | Defines the label string. This value can be bound to values in the i18n file used in the
connected Card.
label : "fixedString" |
1.83 |
defaultValue | any | No | Depending on type property | Defines the default value that is used if the current value in the manifest for this
property is empty.
defaultValue : "stringValue" //string type |
1.83 |
required | boolean | No | false | Defines whether the value is required or not. The editors label for the field will get a "*"
to indicate this state.
required : true |
1.83 |
visible | boolean | No | true | Defines whether the value is visible in the editor or not. For technical parameters it might
be needed to hide them from the user.
In future version an administrator is able to change the visible property for the
page/content administrator. This will only apply for
parameters that are visible to the administrator.
visible : true |
1.83 |
editable | boolean | No | true | Defines whether the value is editable in the editor or not. For technical parameters it might
be needed to make them consistent from the user.
In future version an administrator is able to change the editable property for the
page/content administrator. This will only apply for
parameters that are editable to the administrator.
editable : true |
1.83 |
translatable | boolean | No | false | Defines whether the value is potentially translatable and should be shown in the Card Editor
in translation mode.
This setting should be used for fields of type string only.
to indicate this state.
translatable : true |
1.83 |
description | string | No | Defines the description of current field.
description : "Description of current field" |
1.83 | |
cols | 1 or 2 | No | 2 | By default, the form in the editor spans field to its two columns. Setting cols=1 in two
sibling items,
will allow to align two fields next to each other
cols : 1 |
1.83 |
Visualization | object of type Visualization | No | none | Defines a visualization for the field. It will render the field using the new control defined in visualization.
visualization : { //visualization settings } |
1.83 |
allowDynamicValues | boolean | No | false | Defines whether the value can be bound to a context value of the host environment.
The default value for an administrator and content admin is false. In translation mode this
property is ignored.
To activate the feature additionally the allowDynamicValues property
of the Card Editor control needs to be enabled.
allowDynamicValues : true |
1.84 |
allowSettings | boolean | No | true | Defines whether the administrator is allowed to change the settings of the field.
For example the administrator can hide or disable fields for the content mode.
To activate the feature additionally the allowSettings property
of the Card Editor control needs to be enabled.
allowSettings : true |
1.84 |
placeholder | string | No | none | Define a placeholder string that appears within a default input for string parameters.
placeholder : "My Placeholder" |
1.84 |
expanded | boolean | No | true | Defines whether the Group panel is expanded in the editor or not.
Only for Group type parameter.
expanded : true |
1.86 |
hint | string | No | none | Define a hint string that appears below a group or an item with the formatted text.
hint : "Hint Message" |
1.86 |
validation | object of type Validation | No | none | Defines a validation rule for the value of the field.
validation : { //validation settings } |
1.86 |
validations | object[] of type Validation | No | none | Defines a validation rules for the value of the field.
validations : { //validations settings } |
1.86 |
formatter | object of type formatter | No | none | Defines a formater options for the value of the field.
formatter : { //formatter options } |
1.88 |
Providing Lists for string
To allow a selection of values for fields of type "string", you can add a values section. Similar to the Card data section, the list can be filled with a static json or a request. The item section in the values definition links the data. The "key" property of the item is used as the value for the setting referred by the "manifestPath".
Static Data List"stringWithStaticList": { "manifestpath": "/sap.card/configuration/parameters/stringWithStaticList/value", "type": "string", "values": { "data": { "json": { "values": [ { "text": "From JSON 1", "key": "key1" }, { "text": "From JSON 2", "key": "key2" }, { "text": "From JSON 3", "key": "key3" } ] }, "path": "/values" }, "item": { "text": "{text}", "key": "{key}" } } }Request Data List
There referred url will deliver the data asynchronous. Also an extension could be used as a data propvider.
"stringWithStaticList": { "manifestpath": "/sap.card/configuration/parameters/stringWithRequestList/value", "type": "string", "values": { "data": { "request": { "url": "./dt/listdata.json" }, "path": "/values" }, "item": { "text": "{text}", "key": "{key}" } } }
"values": [ { "text": "From JSON 1", "key": "key1" }, { "text": "From JSON 2", "key": "key2" }, { "text": "From JSON 3", "key": "key3" } ]
Providing Lists for string arrays
To allow a selection of values for fields of type "string[]", you can add the same values sections as above. Similar to the Card data section, the list can be filled with a static json or a request. The item section in the values definition links the data. The "key" property of the item is used as the value for the setting referred by the "manifestPath". Static Data List
"stringArrayWithStaticList": { "manifestpath": "/sap.card/configuration/parameters/stringArrayWithStaticList/value", "type": "string[]", "values": { "data": { "json": { "values": [ { "text": "From JSON 1", "key": "key1" }, { "text": "From JSON 2", "key": "key2" }, { "text": "From JSON 3", "key": "key3" } ] }, "path": "/values" }, "item": { "text": "{text}", "key": "{key}" } } }Request Data List
There referred url will deliver the data asynchronous. Also an extension could be used as a data propvider.
"stringWithStaticList": { "manifestpath": "/sap.card/configuration/parameters/stringArrayWithRequestList/value", "type": "string[]", "values": { "data": { "request": { "url": "./dt/listdata.json" }, "path": "/values" }, "item": { "text": "{text}", "key": "{key}" } } }
"values": [ { "text": "From JSON 1", "key": "key1" }, { "text": "From JSON 2", "key": "key2" }, { "text": "From JSON 3", "key": "key3" } ]
Validation of field input
Validation of input of the users can be added to the validation(s) settings in the configuration of each field. Please ensure that users are not overwhelmed with error and warning messages. Use validation wisely.
"string1": { "type": "string", "required": true, //this is a validation rule, it will automaticall check for empty value, no need to define a validation for it. "validation": { "type": "error", "maxLength": 20 } }, "int1": { "type": "integer", "required": true, //this is a validation rule, it will automaticall check for empty value, no need to define a validation for it. "validation": { "type": "error", "maximum": 20, "minimum": 10, "exclusiveMinimum": true, "message": "Your message" //optional } }, "string2": { "type": "string", "validations": [ { "type": "error", "maxLength": 20, "message": "Your message"//optional }, { "type": "error", "minLength": 1, "message": "Your message" //optional }, { "type": "warning", "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$", //american phone number "message": "Your message" //optional }, { "type": "warning", "validate": function (value) { //do your own checks here }, "message": "Your message" //optional } ] }
Property | Type | Required | Default | For Type | Description | Since |
---|---|---|---|---|---|---|
type | ["error","warning"] | No | error | all | Defines the type of the message (error or warning) that should appear on the field.
type: "error" |
1.86 |
message | string | No | none | all | Defines the error message that should apprear. If not given a default message will appear.
message: "{i18n>TRANSLATABLE_ERROR_MESSAGE}" |
1.86 |
minLength | integer | No | 0 | string | Minimal length of a string value
minLength : 10 |
1.86 |
maxLength | integer | No | unlimited | string | Maximal length of a string value
maxLength : 10 |
1.86 |
pattern | Reg Exp string | No | none | string | String values are only valid if thex match the given Regular Expression.
pattern : "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$" |
1.86 |
validate | function | No | none | all | Own implementation function to check values
validate : function(value) { return true if value is valid } |
1.86 |
minimum | integer | No | none | integer/number | Minimum value for the number
minimum : 10 |
1.86 |
maximum | integer | No | none | integer/number | Maximum value for the number
maximum : 20 |
1.86 |
exclusiveMinimum | boolean | No | false | integer/number | Whether the given minimum should be excluded.
minimum: 10, exclusiveMinimum : true //10 is not allowed, but 10.00001 |
1.86 |
exclusiveMaximum | boolean | No | false | integer/number | Whether the given maximum should be excluded.
maximum: 20, exclusiveMaximum : true //20 is not allowed, but 19.9999 |
1.86 |