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 mike.howles4 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.
- SAP Managed Tags:
5 Comments
