Joose and Grace helper functions

Joose

Joose comes bundled with Grace and is a complete object system for JavaScript, based on concepts from many programming languages such as Ruby, Smalltalk, Perl and, well, JavaScript. It provides "keywords" or "syntactic sugar" for attribute declaration, object construction, inheritance and more.

The default dizmo scaffold generated by Grace uses Joose for the class definitions.

After styling the UI elements, dizmoSpace sends the dizmo an event called “dizmoready”. By default, this event initiates the class Main of your project (implemented in Main.js).

Grace helper functions

One of the files generated by Grace is Dizmo.js in the folder '/src/javascript/' with the JavaScript API Wrapper class. Aforementioned class serves as a basic wrapper around the API provided by dizmo. The provided wrapper contains the bare essentials and some starting points. You can add and modifiy this class as your project grows.

Overview of Grace helper functions

save

The function save saves the provided value in the provided path. This will make it persistent: On a reload of the dizmo, the value will still be at the same place (at the saved path).

dizmo.save(path, value);

load

The function load loads a path that was previously saved with the above described save function. The values loaded are JavaScript types. So if you have saved a number, you will get a number back; if you saved an object, you will get an object back.

dizmo.load(path, value);

publish

The function publish saves the provided value in the provided path. If no path is provided (the function is called only with the value), the default publish path is 'stdout'.

dizmo.publish(path, value);

unpublish

The function unpublish deletes the published path. If no path is provided (the function is called only with the value), this function deletes the default publish path 'stdout'.

dizmo.unpublish(path);

Note: The functions save and load write and read from the subtree /dizmos/[dizmoID]/privateStorage. The functions publish and unpublish write and read from the subtree /dizmos/[dizmoID]/publicStorage. Please look up chapter Persistence for an in-depth description of data persistence.

Predefined events

A set of predefined events are available. You can register to these by calling the following statement in your code:

jQuery(events).on('dizmo.turned', function(e, side) {
// Do something here
});

The event object is provided and only used to attach events to it.

dizmo.turned

The event dizmo.turned is triggered when the dizmo is turned. Example:

jQuery(events).on('dizmo.turned', function(e, side) {
    if (side === 'front') {
        // do something when turned to front
    } else {
        // do something when turned to back
    }
});

dizmo.resized

The event dizmo.resized is triggered when the dizmo is resized (either width or height). Example:

jQuery(events).on('dizmo.resized', function(e, width, height) {
    jQuery(.mycontainer).width(width);
    jQuery(.mycontainer).height(height);
});

dizmo.onmodechanged

Triggered when the display mode of dizmoSpace is changed. Possible provided values are: ‘presentation’, ‘edit’, ‘development’.

jQuery(events).on('dizmo.onmodechanged', function(e, mode) {
    // do something when switched to a different mode
    });

dizmo.docked

The event dizmo.docked is triggered when the dizmo is docked to another dizmo (the dizmo is dragged side by side to another dizmo). Example:

jQuery(events).on('dizmo.docked', function(e) {
    // do something when the dizmo is docked
});

dizmo.undocked

The event dizmo.undocked is triggered when the dizmo undockes (the dizmo is dragged away from the other dizmo). Example:

jQuery(events).on('dizmo.undocked', function(e) {
    // do something when the dizmo is undocked
});

The file application.js

You can write all your code in the provided application.js file if you do not wish to work with the helper functions provided by Grace (and use Grace only to build, test, deploy and upload dizmos).

If you use the provided structure and helper functions, it is highly recommended to split your JavaScript code into single classes, giving each class its own file. This will give you a much better overview. Grace parses your application.js file and checks if the first line starts with a //= require MyClass. This is the starting point, meaning that your first class file should be something like a main in other languages. In every JavaScript file you create, you can add the //= require Path/To/Class/File at the beginning to include another file. It is important that you do not add the .js at the end. The following is an example set up:

application.js

//= require MyMain
document.addEventListener('dizmoready', function() {
    main = new MyProject.MyMain()
});

MyMain.js

//= require Dizmo.js
//= require MyUtils.js

Class('MyProject.MyMain', {
    has: {
        log: {
            is: 'r',
                init: MyProject.MyUtils.logWithType
        }
    }

    after: {
        initialize: function() {
            var self = this;

            self.draw('circle'))
        }
    }
});

MyUtils.js

Class('MyProject.utils.MyUtils', {
    my: {
        methods: {
            logWithType: function(val) {
                console.log(jQuery.type(val), val);
            }
        }
    }
});

The folder structure for this would look as following:

MyProject

— src
    |— application.js
    |-- javascript
    |   |— Main.js
        |— Dizmo.js
        |— MyUtils.js

Practical example

Our Main class will provide the functionality for Gauge. We are going to extend the Main class, which then is included into 'application.js' with

//= require Main`

External resources