Skip to Content
Author's profile photo David Stocker

Your First Extension: Part 7a – Property Arrays and Complex Properties

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:

  • A default color – We already have this with colorCode.
  • A way to define measure threshold values and accompanying colors – essentially conditional formatting.  This would be a list of threshold value/color pairs.
    • As we walk through the list, if the threshold value has been met, then the associated color would be the color assigned to the gauge. 
    • When we’re reached the end, the last valid color is the one assigned and if none of the thresholds have been met, then we use the default. 

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.

The Object

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” />


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

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” />


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];



Arrays and Scripting

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:

  1. Create a new variable and set it equal to the array.  This does not create a pointer to the original, but rather creates a copy.
  2. Execute the pop/push/shift on the copy.
  3. Set the value of the original to the now altered copy.
  4. Return the pop/push/shift.

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;


  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 [“”];


Important Note!

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.



  <defaultValue property=”arrayExample”></defaultValue>


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)

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Michael Howles
      Michael Howles

      Thanks for the write-up and in particular, the information on the default values.  This is basically my hold-up on adopting them in the new complex object/array approach until we can use defaults.

      Author's profile photo Former Member
      Former Member


      I have added an array in contribution.xml file.




        title="Show Hide Columns">

        <property id="visProperty" type="boolean" title="Define column's visibility properties" />


      But in design studio, Array always comes with default value as false, when i add item in array. I want to make default value as true.

      Please let me know, how to do it ?