Class zebkit.Zson <zebkit>

JSON object loader class is a handy way to load hierarchy of objects encoded with JSON format. The class supports standard JSON types plus it extends JSON with a number of features that helps to make object creation more flexible. Zson allows developers to describe creation of any type of object. For instance if you have a class "ABC" with properties "prop1", "prop2", "prop3" you can use instance of the class as a value of a JSON property as follow:

 { "instanceOfABC": {
         "@ABC"  : [],
         "prop1" : "property 1 value",
         "prop2" : true,
         "prop3" : 200
     }
 }

And than:

  // load JSON mentioned above
  zebkit.Zson.then("abc.json", function(zson) {
      zson.get("instanceOfABC");
  });

Features the JSON zson supports are listed below:

  • Access to hierarchical properties You can use dot notation to get a property value. For instance:
{ "a" : {
       "b" : {
           "c" : 100
       }
    }
}

zebkit.Zson.then("abc.json", function(zson) {
    zson.get("a.b.c"); // 100
});
  • Property reference Every string JSON value that starts from "@" considers as reference to another property value in the given JSON.
{  "a" : 100,
   "b" : {
       "c" : "%{a.b}"
   }
}

here property "b.c" equals to 100 since it refers to property "a.b" *

  • Class instantiation Property can be easily initialized with an instantiation of required class. JSON zson considers all properties whose name starts from "@" character as a class name that has to be instantiated:
{  "date": {
      { "@Date" : [] }
    }
}

Here property "date" is set to instance of JS Date class.

  • Factory classes JSON zson follows special pattern to describe special type of property whose value is re-instantiated every time the property is requested. Definition of the property value is the same to class instantiation, but the name of class has to prefixed with "*" character:
{  "date" : {
      "@ *Date" : []
   }
}

Here, every time you call get("date") method a new instance of JS date object will be returned. So every time will have current time.

  • JS Object initialization If you have an object in your code you can easily fulfill properties of the object with JSON zson. For instance you can create zebkit UI panel and adjust its background, border and so on with what is stored in JSON:
{
  "background": "red",
  "layout"    : { "@zebkit.layout.BorderLayout": [] },
  "border"    : { "@zebkit.draw.RoundBorder": [ "black", 2 ] }
}

var pan = new zebkit.ui.Panel();
new zebkit.Zson(pan).then("pan.json", function(zson) {
    // loaded and fulfill panel
    ...
});
  • Expression You can evaluate expression as a property value:
{
    "a": { ".expr":  "100*10" }
}

Here property "a" equals 1000

  • Load external resources You can combine Zson from another Zson:
{
    "a": "%{<json> embedded.json}",
    "b": 100
}

Here property "a" is loaded with properties set with loading external "embedded.json" file

Constructor:
zebkit.Zson ([obj])

Parameters:
  • [obj] <Object>

    a root object to be loaded with the given JSON configuration



public void addClassAliases (aliases)

Adds class aliases


Parameters:
  • aliases <Object>

    dictionary where key is a class alias that can be referenced from JSON and the value is class itself (constructor)

protected <Object> buildValue (d)

Build a value by the given JSON description


Parameters:
  • d <Object>

    a JSON description


Returns: <Object>

a value

public <Object> callMethod (name, d)

Call method.


Parameters:
Returns: <Object>

a method execution result

public <Object> get (key)

Get a property value by the given key. The property name can point to embedded fields:

 new zebkit.Zson().then("my.json", function(zson) {
     zson.get("a.b.c");
 });

Parameters:
  • key <String>

    a property key.


Returns: <Object>

a property value


Throws:

Error if property cannot be found and it doesn't start with "?"

protected <Function> resolveClass (className)

Called every time the given class name has to be transformed into the class object (constructor) reference. The method checks if the given class name is alias that is mapped with the zson to a class.


Parameters:
  • className <String>

    a class name


Returns: <Function>

a class reference

public static <zebkit.DoIt> then (json, [root], [cb])

Build zson from the given json file


Parameters:
  • json <String | Object>

    a JSON or path to JSOn file

  • [root] <Object>

    an object to be filled with the given JSON

  • [cb] <Function>

    a callback function to catch the JSON loading is completed


Returns: <zebkit.DoIt>

a promise to catch result

public <zebkit.DoIt> then (json)

Load and parse the given JSON content.


Parameters:
  • json <String | Object>

    a JSON content. It can be:

    • String
      • JSON string
      • URL to a JSON
    • Object JavaScript object

Returns: <zebkit.DoIt>

a reference to the runner


Example:
// load JSON in zson from a remote site asynchronously
new zebkit.Zson().then("http://test.com/test.json", function(zson) {
        // zson is loaded and ready for use
        zson.get("a.c");
    }
).catch(function(error) {
    // handle error
    ...
});

public <Object> $variables

Internal variables set

public <Boolean> cacheBusting

Cache busting

protected <Object> classAliases

Map of aliases and appropriate classes

protected <Object> content

Original JSON as a JS object

public <Object> root

Object that keeps loaded and resolved content of a JSON

public <zebkit.URI> uri

URL the JSON has been loaded from

public <Boolean> usePropertySetters

The property says if the object introspection is required to try find a setter method for the given key. For instance if an object is loaded with the following JSON:

    {
       "color": "red"
    }

the introspection will cause zson class to try finding "setColor(c)" method in the loaded with the JSON object and call it to set "red" property value.