Package zebkit

This is the core package that provides powerful easy OOP concept, packaging and number of utility methods. The package doesn't have any dependencies from others zebkit packages and can be used independently. Briefly the package possibilities are listed below:

  • easy OOP concept. Use "zebkit.Class" and "zebkit.Interface" to declare classes and interfaces
    // declare class A
    var ClassA = zebkit.Class([
        function() { // class constructor
            ...
        },
        // class method
        function a(p1, p2, p3) { ... }
    ]);

    var ClassB = zebkit.Class(ClassA, [
        function() {  // override cotoString.nanstructor
            this.$super(); // call super constructor
        },

        function a(p1, p2, p3) { // override method "a"
            this.$super(p1, p2, p3);  // call super implementation of method "a"
        }
    ]);

    var b = new ClassB(); // instantiate classB
    b.a(1,2,3); // call "a"

    // instantiate anonymous class with new method "b" declared and
    // overridden method "a"
    var bb = new ClassB([
        function a(p1, p2, p3) { // override method "a"
            this.$super(p1, p2, p3);  // call super implementation of method "a"
        },

        function b() { ... } // declare method "b"
    ]);

    b.a();
    b.b();
  • Packaging. Zebkit uses Java-like packaging system where your code is bundled in the number of hierarchical packages.
    // declare package "zebkit.test"
    zebkit.package("test", function(pkg) {
        // declare class "Test" in the package
        pkg.Test = zebkit.Class([ ... ]);
    });

    ...
    // Later on use class "Test" from package "zebkit.test"
    zebkit.require("test", function(test) {
        var test = new test.Test();
    });
  • Resources loading. Resources should be loaded with a special method to guarantee its proper loading in zebkit sequence and the loading completeness.
    // declare package "zebkit.test"
    zebkit.resources("http://my.com/test.jpg", function(img) {
        // handle completely loaded image here
        ...
    });

    zebkit.package("test", function(pkg, Class) {
        // here we can be sure all resources are loaded and ready
    });
  • Declaring number of core API method and classes
    • "zebkit.DoIt" - improves Promise like alternative class
    • "zebkit.URI" - URI helper class
    • "zebkit.Dummy" - dummy class
    • instanceOf(...) method to evaluate zebkit classes and and interfaces inheritance. The method has to be used instead of JS "instanceof" operator to provide have valid result.
    • zebkit.newInstance(...) method
    • zebkit.clone(...) method
    • etc


private <Object> $cache (key)

Get an object by the given key from cache (and cached it if necessary)


Parameters:
  • key <String>

    a key to an object. The key is hierarchical reference starting with the global name space as root. For instance "test.a" key will fetch $global.test.a object.


Returns: <Object>

an object

public <Object> clone (obj)

Clone the given object. The method tries to perform deep cloning by traversing the given object structure recursively. Any part of an object can be marked as not cloneable by adding "$notCloneable" field that equals to true. Also at any level of object structure the cloning can be customized with adding "$clone" method. In this case the method will be used to clone the part of object. clonable


Parameters:
  • obj <Object>

    an object to be cloned


Returns: <Object>

a cloned object

public void dumpError (e)

Dump the given error to output.


Parameters:
  • e <Exception | Object>

    an error.

public void findInTree (root, path, cb, [eq])

Finds an item by xpath-like simplified expression applied to a tree-like structure. Passed tree-like structure doesn't have a special requirements except every item of the structure have to define its kids by exposing "kids" field. The field is array of children elements:

// example of tree-like structure
var treeLikeRoot = {
    value : "Root",
    kids : [
        { value: "Item 1" },
        { value: "Item 2" }
    ]
};

zebkit.findInTree(treeLikeRoot,
    "/item1",
    function(foundElement) {
       ...
       // returning true means stop lookup
       return true;
    },
    function(item, fragment) {
        return item.value === fragment;
    });

The find method traverse the tree-like structure according to the xpath-like expression. To understand if the given tree item confronts with the currently traversing path fragment a special equality method has to be passed. The method gets the traversing tree item and a string path fragment. The method has to decide if the given tree item complies the specified path fragment.


Parameters:
  • root <Object>

    a tree root element. If the element has a children elements the children have to be stored in "kids" field as an array.

  • path <String>

    a path-like expression. The path has to satisfy number of requirements:

    • has to start with "." or "/" or "//" character
    • has to define path part after "/" or "//"
    • path part can be either "*" or a name
    • optionally an attribute or/and its value can be defined as "[@<attr_name>=<attr_value>]"
    • attribute value is optional and can be boolean (true or false), integer, null or string value
    • string attribute value has to be wrapped with single quotes

    For examples:

    • "//*" traverse all tree elements
    • "//*[@a=10]" traverse all tree elements that has an attribute "a" that equals 10
    • "//*[@a]" traverse all tree elements that has an attribute "a" defined
    • "/Item1/Item2" find an element by exact path
    • ".//" traverse all tree elements including the root element
  • cb <Function>

    callback function that is called every time a new tree element matches the given path fragment. The function has to return true if the tree look up has to be interrupted

  • [eq] <Function>

    an equality function. The function gets current evaluated tree element and a path fragment against which the tree element has to be evaluated. It is expected the method returns boolean value to say if the given passed tree element matches the path fragment. If the parameter is not passed or null then default equality method is used. The default method expects a tree item has "path" field that is matched with given path fragment.

public <Function> getPropertyGetter (obj, name)

Get a property getter method if it is declared with the class of the specified object for the given property. Getter is a method whose name matches the following patterns: "get" or "is" where the first letter of the property name is in upper case. For instance getter method for property "color" has to have name "getColor".


Parameters:
  • obj <Object>

    an object instance

  • name <String>

    a property name


Returns: <Function>

a method that can be used as a getter for the given property

public <Function> getPropertySetter (obj, name)

Get a property setter method if it is declared with the class of the specified object for the given property. Setter is a method whose name matches the following pattern: "set" where the first letter of the property name is in upper case. For instance setter method for property "color" has to have name "setColor".


Parameters:
  • obj <Object>

    an object instance

  • name <String>

    a property name


Returns: <Function>

a method that can be used as a setter for the given property

public <Object> getPropertyValue (obj, path, [useGetter])

Get property value for the given object and the specified property path


Parameters:
  • obj <Object>

    a target object. as the target object

  • path <String>

    property path.

  • [useGetter] <Boolean>

    says too try getter method when it exists. By default the parameter is false


Returns: <Object>

a property value

public <zebkit.DoIt> image (ph, [fireErr])

Load image or complete the given image loading.


Parameters:
  • ph <String | Image>

    path or image to complete loading.

  • [fireErr] <Boolean>

    flag to force or preserve error firing.


Returns: <zebkit.DoIt>
public <Boolean> instanceOf (obj, clazz)

Test if the given object is instance of the specified class or interface. It is preferable to use this method instead of JavaScript "instanceof" operator whenever you are dealing with zebkit classes and interfaces.


Parameters:
  • obj <Object>

    an object to be evaluated

  • clazz <Function>

    a class or interface


Returns: <Boolean>

true if a passed object is instance of the given class or interface

public <Boolean> isAtomic (v)

Test if the given value has atomic type (String, Number or Boolean).


Parameters:
Returns: <Boolean>

true if the value has atomic type

public <Boolean> isBoolean (v)

Check if the given value is boolean


Parameters:
Returns: <Boolean>

true if the given value is boolean

public <Boolean> isNumber (v)

Check if the given value is number


Parameters:
Returns: <Boolean>

true if the given value is number

public <Boolean> isString (v)

Check if the given value is string


Parameters:
Returns: <Boolean>

true if the given value is string

public <zebkit.Listener> ListenersClass ([events])

This method allows to declare a listeners container class for the given dedicated event types.

// create listener container to keep three different events
// handlers
var MyListenerContainerClass = zebkit.ListenersClass("event1",
                                                     "event2",
                                                     "event3");
// instantiate listener class container
var listeners = new MyListenerContainerClass();

// add "event1" listener
listeners.add(function event1() {
    ...
});

// add "event2" listener
listeners.add(function event2() {
   ...
});

// add listener for both event1 and event2 events
listeners.add(function() {
   ...
});

// and firing event1 to registered handlers
listeners.event1(...);

// and firing event2 to registered handlers
listeners.event2(...);

Parameters:
  • [events] <String> (*..n)

    events types the listeners container has to support


Returns: <zebkit.Listener>

a listener container class

public <Object> newInstance (clazz, [args])

Instantiate a new class instance of the given class with the specified constructor arguments.


Parameters:
Returns: <Object>

a new instance of the given class initialized with the specified arguments

public <Object> properties (target, p)

Populate the given target object with the properties set. The properties set is a dictionary that keeps properties names and its corresponding values. The method detects if a property setter method exits and call it to apply the property value. Otherwise property is initialized as a field. Setter method is a method that matches "set" pattern.


Parameters:
  • target <Object>

    a target object

  • p <Object>

    a properties set


Returns: <Object>

an object with the populated properties set.


private <Object> $global

Reference to global space.

public <Environment> environment

Reference to zebkit environment. Environment is basic, minimal API zebkit and its components require.