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

Field Type items
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"
label : "{i18n>translatedStringKey}"
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
defaultValue : true //boolean type
defaultValue : "{i18n>translatedDefaultKey}" //trnaslatedDefaultValue for strings
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 Request Data List

There referred url will deliver the data asynchronous. Also an extension could be used as a data propvider.

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

Request Data List

There referred url will deliver the data asynchronous. Also an extension could be used as a data propvider.

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.

Validation Type
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