.. image:: https://raw.githubusercontent.com/score-framework/py.doc/master/docs/score-banner.png :target: http://score-framework.org

The SCORE Framework_ is a collection of harmonized python and javascript libraries for the development of large scale web projects. Powered by strg.at_.

.. _The SCORE Framework: http://score-framework.org .. _strg.at: http://strg.at

score.oop

.. _js_oop:

This module provides helpers for supporting an object oriented programming style, which is our preferred way of programming in javascript. Several implementation details are heavily dependent on personal taste, which means that it is well possible that you might encounter some alien definitions.

The whole module tries to mimic classes in python for two reasons:

• we are also python developers, and
• python, the programming language, has much more elegant design decisions than javascript when it comes to OOP [#]_.

Creating Classes

The basic usage of the module is as follows::

var Animal = oop.Class({

    __init__: function(self) {
        console.log('Animal constructor')
    }

});

This call creates a trivial class that will log a debug message into the console whenever the it is instantiated. Note that the first argument to all functions is always the current object, i.e. this. This saves us a lot of time, as the usual var self = this; declaration is sometimes forgotten.

The object passed to the function oop.Class is stored unmodified as the __conf__ property of the class. This means that the following code will print true::

var conf = {

    __init__: function(self) {
        console.log('Animal constructor')
    }

};
var Animal = oop.Class(conf);
console.log(Animal.__conf__ === conf);

A best practise is to provide a class name as __name__, which will then be available as an attribute to the class::

var Animal = oop.Class({
    __name__: 'Animal',

    __init__: function(self) {
        console.log(self.__class__.__name__ + ' constructor')
    }

});

Attributes

You can define the default values of attributes as well. Such values are specific to each object, meaning that the following code will print two distinct speed values::

var Animal = oop.Class({
    __name__: 'Animal',

    __init__: function(self) {
        console.log('Animal constructor')
    },

    speed: 10

});

var a = new Animal();
a.speed = 9;
var b = new Animal();
a.speed = 8;
console.log(a.speed); // 8
console.log(b.speed); // 10

Sub-Classing

In order to create a sub-class, you only need to pass the configuration value __parent__::

var Animal = oop.Class({
    __name__: 'Animal',

    __init__: function(self) {
        console.log('Animal constructor')
    }

});

var Bird = oop.Class({
    __name__: 'Bird',
    __parent__: Animal,

    __init__: function(self) {
        console.log('Bird constructor')
        self.__super__();
    }

});

var swallow = new Bird();
swallow instanceof Animal;
swallow instanceof Bird;

The above code will call the child constructor, followed by the base constructor. As you can see, the matching function of the base class can always be accessed via self.__super__(). This is true for all member functions, not just the constructor::

var Animal = oop.Class({
    __name__: 'Animal',

    carry: function(self, object) {
        console.log('Carrying ' + object);
    },

    drop: function(self, object) {
        console.log('Dropping ' + object);
    }

});

var Bird = oop.Class({
    __name__: 'Bird',

    speed: 10,

    carry: function(self, object) {
        self.__super__(object);
        self.speed = 1;
    },

    drop: function(self) {
        self.__super__();
        self.speed = 10;
    }

});

var swallow = new Bird();
swallow.carry('coconut');

Static Attributes

You can assign static values to the class (in contrast to the objects of the class) by passing another configuration value called __static__::

var Animal = oop.Class({
    __name__: 'Animal',

    __static__: {
        minSpeed: 9,
        maxSpeed: 11
    }

    __init__: function(self) {
        var cls = self.__class__;
        var diff = cls.maxSpeed - cls.minSpeed;
        self.speed = (int) (Math.random() * diff) + cls.minSpeed;
    }

});

console.log(Animal.minSpeed); // 9
console.log(Animal.maxSpeed); // 11

var a = new Animal();
console.log(a.minSpeed); // undefined

All non-function values of the __static__ object will only be accessible through the class itself. Functions, on the other hand, will be accessible through instances of the class, too. Note that the first parameter to static functions is always the class itself::

var Animal = oop.Class({
    __name__: 'Animal',

    __static__: {
        minSpeed: 9,
        maxSpeed: 11,
        randomSpeed: function(cls) {
            var diff = cls.maxSpeed - cls.minSpeed;
            return (int) (Math.random() * diff) + cls.minSpeed;
        }
    }

    __init__: function(self) {
        self.speed = self.__class__.randomSpeed();
    }

});

console.log(Animal.randomSpeed()); // 9
console.log(Animal.randomSpeed()); // 10

var a = new Animal();
console.log(a.randomSpeed()); // 11

The cls parameter will receive the class the static function was called on, not the one it was defined in. The following code uses different min and max values for the same calculation, for example::

var Snail = oop.Class({
    __name__: 'Snail',
    __parent__: Animal,

    __static__: {
        minSpeed: 0,
        maxSpeed: 1
    }

});

var otto = new Snail();
console.log(otto.speed); // 1

Events

It is possible to mark a class as an events source by providing an __events__ configuration::

var Animal = oop.Class({
    __name__: 'Animal',
    __events__: ['running', 'stopping'],

    run: function(self) {
        self.trigger('running', self.speed);
    },

    // ....

});

var otto = new Snail();

otto.on('running', function(speed) {
    console.log('Otto started running at speed ' + speed);
});

Providing a list of possible __events__ creates the two methods on and trigger. The trigger function just needs the name of an event, but all additional arguments will be delegated to the callback functions registered with on. The context of the callback (i.e. the this value) is always the object triggering the event.

Both functions will throw an Error if the provided event name was not configured. It is possible to allow arbitrary events on a class by setting the __events__ value to True::

var Dog = oop.Class({
    __name__: 'Dog',
    __parent__: Animal,
    __events__: true
});

var otis = Dog();

otis.on('bork', function() {
    console.log('Not barking!');
});

Static Events

It is also possible to configure event handling at the class level. In such cases, the context of these callbacks is the class::

var Animal = oop.Class({
    __name__: 'Animal',

    __static__: {
        __events__: ['create'],
    }

    __init__: function(self) {
        Snail.trigger('create', self);
    }

});

Animal.on('create', function(snail) {
    console.log('Created new ' + this.__name__);
});

var Snail = oop.Class({
    __name__: 'Snail',
    __parent__: Animal

});

new Snail(); // prints "Created new Snail" 

License

Copyright © 2015-2017 STRG.AT GmbH, Vienna, Austria

All files in and beneath this directory are part of The SCORE Framework. The SCORE Framework and all its parts are free software: you can redistribute them and/or modify them under the terms of the GNU Lesser General Public License version 3 as published by the Free Software Foundation which is in the file named COPYING.LESSER.txt.

The SCORE Framework and all its parts are distributed without any WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. For more details see the GNU Lesser General Public License.

If you have not received a copy of the GNU Lesser General Public License see http://www.gnu.org/licenses/.

The License-Agreement realised between you as Licensee and STRG.AT GmbH as Licenser including the issue of its valid conclusion and its pre- and post-contractual effects is governed by the laws of Austria. Any disputes concerning this License-Agreement including the issue of its valid conclusion and its pre- and post-contractual effects are exclusively decided by the competent court, in whose district STRG.AT GmbH has its registered seat, at the discretion of STRG.AT GmbH also the competent court, in whose district the Licensee has his registered seat, an establishment or assets.

Footnotes

.. [#] This is mostly because javascript evolved under the influence of various browser vendors and committees with very few opportunities for breaking changes, whereas python has a benovelent dictator and has undergone radical rewrites in the past.