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) {

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

zebkit.Zson ([obj])

  • [obj] <Object>

    a root object to be loaded with the given JSON configuration

public void addClassAliases (aliases)

Adds class aliases

  • 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

  • d <Object>

    a JSON description

Returns: <Object>

a value

public <Object> callMethod (name, d)

Call the given method defined with the Zson class instance and pass the given arguments to the method.

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) {

  • key <String>

    a property key.

Returns: <Object>

a property value


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

protected <Object> merge (dest, src, [recursively])

Merge values of the given destination object with the values of the specified source object.

  • dest <Object>

    a destination object

  • src <Object>

    a source object

  • [recursively] <Boolean>

    flag that indicates if the complex properties of destination object has to be traversing recursively. By default the flag is true. The destination property value is considered not traversable if its class defines "mergeable" property that is set top true.

Returns: <Object>

a merged destination object.

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.

  • 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

  • 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.

  • 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

// load JSON in zson from a remote site asynchronously
new zebkit.Zson().then("", function(zson) {
        // zson is loaded and ready for use
).catch(function(error) {
    // handle error

protected <Object> $variables

Internal variables set

public <String> baseUri

Base URI to be used to build paths to external resources. The path is used for references that occur in zson.

public <Boolean> cacheBusting

Cache busting flag.

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.