This is part of a tutorial series on creating extension components for Design Studio.
Last time, we added data binding to our gauge. Now it is time to add some built in conditional formatting. In this installment, we'll review the relevant SDK features and next time, we'll add the conditional formatting. Here is what we'd like to have:
For defining the conditional formatting, we can make use of a couple of new property features introduced in Design Studio 1.6: Objects and Arrays.
Have you ever wanted to be able to nest custom properties within a hierarchy, like the expandable property hierarchies that you see in the design panel of Design Studio 1.6? You can have them, but using the property type Object. If a property is of type Object, it may have other properties as children.
<property id="objectExample" type="Object" title="This is an Object">
<property id="firstChild" type="int" title="An Int" />
<property id="secondChild" type="String" title="A String" />
<property id="thirdChild" type="Color" title="A Color" />
</property>
This results in an objectExample property, that when collapsed in the properties pane looks like this:
When expanded, the individual child properties are visible.
Objects are normal JavaScript objects when working in component.js and we will use them extensively in the next iinstalment
The array is simply a list of n elements of a given property type. The property type may be an int, String or Object. Declaring an array is simple, you declare the property type as array; and then you can nest another property declaration inside.
<property id="arrayExample" type="Array" title="This is an Array">
<property id="arrayEntry" type="String" title="Entry" />
</property>
This gives you a list with 0..n members of the inner declaration. If not given any default members, the properties pane will initially show the value "<no entries>". Note that as of 1.6SP0, you can't give default values, so this is always the case. (You can (must) initialize the component with an empty value. See the warning note, below)
If the user opens the list editor, she gets a normal Design Studio list editor dialog.
She can add, remove and reorder entries as she pleases.
Afterwards, she'll see the number of list entries in the main properties pane. To view the actual entries, she'll have to go to the dialog again.
If you wish to work with an array within the component.js or contribution.ztl, you can. The array is a normal JavaScript array and you can work with it as such. Here is a JavaScript for loop snippet for compoennt.js, iterating over the contents of arrayExample:
var index;
for (index = 0; index < arrayExample.length; index++){
var arrayEntry = arrayExample[index];
...
}
Let's make our new arrayExample property scriptable. For starters, we'll follow the usual pattern for manipulating properties in component.js, as originally outlined in Part 3d.
First, we add the local copy of the property:
//New with part 7
me._arrayExample = [];
And we add the getter/setter function:
me.getArrayExample = function(value) {
if (value === undefined) {
if (me._arrayExample === undefined){
return [];
}
else {
return me._arrayExample;
}
} else {
me._arrayExample = value;
return this;
}
};
So far, so standard. Now if you've worked with standard array object in Design Studio's scripting language, you're probably aware that the standard Javascript array manipulation functions, pop(), push() and shift() are available. Let's also make sure that they are available for our custom property. It's actually quite easy and the methodology works as such:
It is important to note here that array properties are immutable. If we simply execute a JavaScript shift on the array itself, we'll be able to return the first element, but the array property itself will remain unchanged. Repeated shift() operations will always return that same, original, first element; without altering the array as a normal shift would.
With this in mind, we can decorate the contribution.ztl with scripting functions for shift, push, pop and get operations:
//Get/Set, push, pop and shift for arrayExample
/* push. */
void arrayExamplePush(/* String to be pushed to end of array */ String addedString) {*
var tempVar = this.arrayExample;
tempVar.push(addedString);
this.arrayExample = tempVar;
*}
/* pop. */
String arrayExamplePop() {*
var tempVar = this.arrayExample || [];
var returnMe = tempVar.pop();
this.arrayExample = tempVar;
return returnMe;
*}
/* pop. */
String arrayExampleShift() {*
var tempVar = this.arrayExample || [];
var returnMe = tempVar.shift();
this.arrayExample = tempVar;
return returnMe;
*}
/* Returns the full string array. */
StringArray getArrayExample() {*
var returnMe = this.arrayExample || [];
if (returnMe.length > 0){
return returnMe;
}
else {
return [""];
}
//return [""];
*}
Currently (as of Design Studio 1.6 SP0), there is a bug in array property handling. If you have an empty array (one with no elements, according to the properties pane) and attempt to access it in contribution.ztl , you'll get a script error. If the array has at least one value, this error does not happen. This probably won't be fixed before SP2, but the workaround is quite simple. Simply declare an empty default value for the property. It will be properly initialized and your contribution.ztl won't throw exceptions. So even though you can't actually declare any default values, if you have an array, you should still declare an empty default value.
<initialization>
...
<defaultValue property="arrayExample"></defaultValue>
</initialization>
The test app is in the git repository for this version, alongside the extension and is demonstrated in the following video:
Next time, we'll put our new knowledge of arrays and objects to work, defining conditional formatting for our gauge. (hint, the array will contain objects and each object will define a conditional formatting rule)
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
User | Count |
---|---|
26 | |
22 | |
19 | |
13 | |
10 | |
9 | |
9 | |
8 | |
7 | |
7 |