Design Studio SDK: Specification Driven Development (or create a full component in 20 minutes)
This is a document for all who do not want to make repeatable work again and again… Addressing the developers of SDK extensions.
What is the Goal?
If you have read the documentation, you know the basic content which is required for a single component:
- contribution.xml – a file describing the component properties
- contribution.ztl – a file for the component scripting
- component.js – content for the visualization
- additional_property_sheet – work with complex properties which cannot be visualized via standard property grid in Design Studio
Actually, only one part has value – the visualization.
The others can be easily “automated”. And this is what we currently have, started by me in the ZTL area and by Michael in the APS (advanced property sheet) area. After some work, today we have a combined contribution. We can generate everything…
When I create a property, I want to have script access to it, w/o any special coding – as this is something quite basic. I want also to have APS UI to change the property (especially for complex types as arrays). And, finally I want to be able to add new properties with small effort, also I want to improve the scripts and all components should get them immediatelly.
This leads to only one case: we need a specification, which is binding all the contexts and can generate all the parts in reproducible way.
The Story.
The work starts with specification. I make it here on the example of “CheckBoxGroup” component in the SCN repository. (here the content folder).
I start with creation of the component folder as in the blog SDK Development Community Git Repository (sdkpackage). But instead of creating immediately the contribution files in “def” folder, I create a specification foder “spec” with 3 files:
(here I will make comments in the code, this will break JSON – for original code use the repository)
component.json
{
“id”: “CheckBoxGroup”, // my component id, the technical name which should not change over time
“title”: “Check Box Group 2.0”, // my description, here you can change something later – like 2.0 indicates it is already moved to 2.0 release
“tooltip”: “Check Box Group”, // the tool tip which will be used for this component
“handlerType”: “sapui5”, // the component type (sapui5 | div | datasource), different templates are used
“parentControl”: “sap.ui.commons.layout.AbsoluteLayout”, // only for sapui5 – what is the parent control which you start extending?
“group”: “ScnCommunityBasics”, // the group which should be assigned
“package”: “basics”, // component package (community specific)
“extension”: “Component”, // extension for common functions (community specific)
“databound”: false, // if it is or not data bound component
“require”: // definition of require statements which we need, this is how the components are loading the files
[
{
“space” : “known”,
“id” : “common_basics”,
}
],
// initial size of the component
“width”: “230”,
“height”: “400”
}
about.json
{
“title”: “Check Box Group 2.0”, // the title for APS, actually same as title of the component, but you can adjust it
“description”: “Check Box Group”, // longer description which we use in APS
“icon”: “CheckBoxGroup.png”, // icon link for APS
“topics”: // APS content, you can add some inplace documentation – it will appear directly in APS screen
[
{
“title” : “Check Box Group”,
“content” : “Check Box Group”
},
{
“title” : “Visualization”,
“content” : “This component is a visualization component. It requires specific space in the application canvas.”
},
]
}
specification.json
This is the main part of the component, here we define properties. The property types are bound to some templates which will be applied with primitive search and replace) to generate ZTL and XML contributions. The specification is also used for the generic generation of APS, this is what Mike has mainly done.
The templates are located here:
- ZTL: sdkpackage/tools/tools.html.generator/src/org/scn/community/spec/ztl
- XML: sdkpackage/tools/tools.html.generator/src/org/scn/community/spec/xml
I know as of today following property types:
| Property Type | Content | ideal aps control |
|---|---|---|
| // data properties | ||
| “type”:”ResultSet”, | data bound component with result set | no control |
| “type”:”ResultCellList”, | selection on result set | no control |
| // primitive | ||
| “type”:”boolean”, | boolean | checkbox |
| “type”:”int”, | integer | spinner |
| “type”:”String”, | string | text |
| // Arrays and Complex | ||
| “type”:”String”, “ztlType”:”SingleArray” | single array | array, “arrayMode”:”OneLevelArray” |
| “type”:”String”, “ztlType”:”DoubleArray” | double array | array, “arrayMode”:”TwoLevelArray” |
| “type”:”String”, “ztlType”:”Choice”, | a choice | combobox |
| “type”: “ScriptText”, | script text (event) | no APS |
For every property we can set, what should be generated. Here is an example for a Choice:
“DDisplayText”:{ // techncial name
“type”:”String”, // the tpye is string, this is what design Studio sees in properties.
// I use string, not the real choice as for string we can use binding.
“value”:”Text”, // default value
“visible”:true, // can be visible or not (eg. some selections are not visible)
“opts”:{ // additional options for the APS / ZTL generation
“ztlType”:”Choice”, // how should this work in ZTL, all Choice parameters can be set by String or constant.
“choiceType”:”MemberDisplay”, // the linked constants in “shared” area of the SCN repository
“ztlFunction”:””, // ztl function, can be empty or “-get”, then we apply another template and make only getter
“desc”:”Display Text”, // desctiprion
“cat”:”Display”, // category in the generated APS, you can use “-” to make sub-categories, eg. Display-Image
“tooltip”:”Display Text”, // tooltip
“apsControl”:”combobox”, // the control which should be used to set the value, see below for types
“options”:[ // the options, here we can place the text and key, not like in the standard properties
{
“key”:”Text”,
“text”:”Text Only”
},
{
“key”:”Text_Value”,
“text”:”Text Value”
},
{
“key”:”Text_Count”,
“text”:”Text Count”
}
]
}
},
Which controls we have for APS?
For today we have:
text
textarea
mapdownload
<special for Mike’s map>
checkbox
spinner
palette
combobox
color
array
-> with sub-types
array-StringArray
array-OneLevelArray
array-TwoLevelArray
columnconfig
Building the APS together
The generic code for APS building is rendering the APS based on the specification. You can see at the end a well defined APS with categories and sub-categories.
Exensibility
Mike has created quite simple API for the building blocks, we can simply add new blocks which only needs to provide the value as string into the Design Studio.
How to start?
Anyone who wants to try out?
Comment here, I will make a description how you can create such component.
What does it mean now for the future development of community SDK components?
in order to create new component, now only 20 minutes is required, not hours as previously. We can concentrate fully on the UI coding, not spending time on technical parts.
Good review, Karol! 🙂
Perhaps internal for us, but related, is I have ideas on how to further refine this existing approach for "one APS to rule them all" approach. It's related to the extending of additional APS controls down the road as needed. Recent ones like 'columnconfig' are borne out of necessity and require adding a few stubs in key places in the property sheet .js file - I'm thinking of how we can make this generic and having the new controls register themselves and add the setValue/getValue logic instead of us having to add yet more "if apscontrol = "xyz" then do this" etc etc.
Again, probably nobody but you and me will care about this as it's more internal SDK housekeeping ( 🙂 ), but the end result will be even more simplification of the APS in terms of extending additional complex property controls down the road.
I hope however that everyone will enjoy the new APS approach and as we enhance anything APS control handler, all components leveraging it will benefit from it at once, and a consistent experience for designers as well will be upheld.
Mike, I am trying to clean up, unfortunately we have produced 109 components, it takes a while to upgrade them to 2.0 release, but today another 6 are upgraded. But, perhaps we do not produce any stable version for this week.
Hi Mike,
I've been looking at trying to merge the functionality of a couple of your components (the leaflet maps and choropleth maps), but have been having trouble deciphering were the APS properties for these componenst are defined. Is it something along the approach outlined in this article?
Specifically, where can I find where the Load GeoJSON File control is defined in the Leaflet Map component?
Kind Regards,
Colin
HI Karol,
While creating a new extension, I came across a small mistake in your guide.
textbox works, but the values are not correctly assigned between the attribute and the APS component. If fact, textbox does not exist as a shared APS component, but textarea yes, and works perferctly 🙂
Just need to rename "textbox" to "textarea" 🙂
changed. probably this got renamed in some refactor... thanks.