Subject of configuration

Zebra UI provides rich set of various classes and interfaces that are responsible for different aspects of the package functionality. To keep all these things under control Zebra applies JSON configuration that helps to do control the following things:

  • Installing various UI managers that makes Zebra UI alive: event manager, paint manager, focus manager, popup manager and many others
  • Defining shared global UI objects like colors, borders etc
  • Defining default values for UI components properties and fields. Every Zebra UI component can be customized by configuration. Customization means you can defined values the properties of the specified UI component has to be set by default. It gives possibility to control look and feel, add own UI themes and palettes. Technically zebra JSON configuration fills UI classes with number of static fields that are applied as default properties for every instance of the classes.For example, if you need all instantiated “zebra.ui.Button” components have to have black background write the following JSON configuration:
     
    ...
    {
      "Button" : {
          "background": "black"
      }
    }
    ...
    

Configuration(s) loading

Zebra load configuration as follow:

  • Detect URL to “zebra.json” configuration file:
    • if “zebra.json” zebra environment variable is defined zebra will use URL defined with the variable to fetch zebra configuration file
    • Otherwise zebra will fetches “zebra.json” configuration file from the same place where zebra code is placed.
  • Loads UI “zebra.json” configuration by URL defined on previous step
  • Check if other configuration files has been added to configuration chain and load its
  • Makes a composition from the loaded JSON configurations
  • Parses and interprets the final configuration composition
  • Applies configuration objects to “zebra.ui” package

By default zebra runtime artifacts looks as follow :

    +
    |
    +--- zebra.js       // zebra JS code  
    +--- zebra.min.js
    +--- zebra.json     // zebra UI configuration  
    +--- zebra.png      // zebra icons set

JSON configuration format

“zebra.util.Bag” class is designed to load a composition of JSON files and to interpret the result composed JSON. Interpretation means existent of rules to handle extra semantic some JSON keys and values can have. The semantic extends simple JSON format with number of useful things. When developers load JSON using “zebra.util.Bag” they also can specify a target object to which the JSON fields have to be applied. In other words an object can be loaded with its properties from JSON. For instance:

{
    background: "red",
    size      : [10, 100],
    location  : [30, 30]
}

Let’s use the JSON to initialize “zebra.ui.Panel” fields:



var pan = new zebra.ui.Panel();
var bag = zebra.util.Bag(pan);
bag.load(jsonString);

The code above causes the UI panel instance background, size and location properties set:

  • background is set by calling “setBackground(bg)” method
  • size is set by calling “setSize(width, height)” method
  • location is set by calling “setLocation(x,y)” method

JSON value reference

JSON value can be a key reference to another value. The reference starts from “@” character, everything what follows the character is considered as a key name where the referenced value is stored. For instance the value “@a.b.c” references to a value that is stored by “a.b.c” key. The sample below illustrates simple JSON that contains one reference:

{
   "a": { 
        "b": 100,
        "c": 200
   },
   "d": {
      "e": "@a.b"
   } 
}

a.b => 100
a.c => 100
d.e => 100 // referenced value

JSON Class instantiation

Zebra extends JSON with a special value type that defines a class to be instantiated as the JSON property value. The description has to follow the pattern shown below:

  {
     "$ClassName": [ arg1, arg2 ],  // class name has to start from "$" character, 
                                    // constructor arguments list can be empty
      // optional list of attributes that will be set for instantiated class
     property1 : value1,  
     property2 : value2,
     ...
     propertyN: valueN  
  }

For example, let’s instantiate “zebra.ui.Panel” class and initialize “classInstatce” JSON property with the value:

{
   "classInstance": { 
        "$zebra.ui.Panel": []
   } 
}

JSON inheritance

To avoid JSON properties duplication and reducing JSON size special JSON property name “$inherit” can be used. The value of the property has to point to another JSON property.

{
   "baseValue": { 
        "a": 100,
        "b" : true
   },

   "extendedBaseValue": {
       "$inherit": [ "baseValue" ], // inherit all properties starting from "baseValue"
       "c"       : "abc"
   }
}

// the JSON property values  
baseValue.a => 100
baseValue.b => true

extendedBaseValue.c => "abc"
extendedBaseValue.a => 100
extendedBaseValue.b => true

JSON conditional values

Conditional property gives a possibility to initialize JSON properties only if the specified condition is true. Conditional property starts from “?” character than follows a condition that has to be evaluated:

{
    "?zebra.isTouchable": {
         "title": "This device has touch screen"
    },
   
    "?zebra.isTouchable === false": {
         "title": "This device doesn't have touch screen"
    }
}