widgets and renderers

This section will cover how widgets and renderers work together. It presumes you have completed the previous section. Now that the basic setup is done, we look at the tutorial widget. Open the widget.tutorial.js in your widget directory in your favorite text editor.

(function () {
    var widget = Retina.Widget.extend({
	about: {
            title: "Tutorial Widget",
            name: "tutorial",
	    version: 1,
            author: "Tobias Paczian",
            requires: [ ]
        }
    });

    widget.setup = function () {
	return [ ];
    }
    
    widget.display = function (params) {
	var widget = this;
	var target = params.target;
	
	target.innerHTML = "<p>Hello World</p>";

	return widget;
    };

})();

The first section extends the basic widget object and adds some administrative information. The requires array is a list of external libraries that the widget needs loaded to function. These libraries will be loaded from the directory specified in the library_resource in the Retina init function. The filenames must include the file ending. Retina will make sure that external libraries are not loaded more than once. These libraries are loaded when the widget is loaded and before any other functions are executed.

The setup function must return a list of functions that are called when the widget is loaded. These functions must return a promise. When all setup functions complete, the widget is loaded and the promise returned by Retina.load_widget fulfills.

When the create function is called on a widget, an instance of the widget is created. After creation, the display function of the widget will be called. This can be suppressed by passing true after the parameter attribute in the create function. In the case of our tutorial widget, the display function simply sets the innerHTML property of the target element to a paragraph containing the string hello world.

adding a renderer

To add a renderer to our app, we first create a DOM element to host it. To do so, we modify the display function.

widget.display = function (params) {
    var widget = this;
    var target = params.target;

    var rendererTarget = document.createElement('div');
    target.appendChild(rendererTarget);
    
    return widget;
};

In order to use a renderer, it needs to be loaded first. This is done in the setup section of the widget.

widget.setup = function () {
    return [
        Retina.load_renderer('table')
    ];
};

This will cause the table renderer to be loaded when the widget is loaded. Retina takes care that multiple calls to load the same renderer do not cause multi-loading of the renderer code. Now that the table renderer is loaded, we can use it in the display section of the widget. Since we already have a place to put the table, all we need is some data. The table requires at least a list of column headers and some data. If you want to try out a renderer and do not have data, most of them come with a function called exampleData that returns trivial data to test what the renderer does.

widget.display = function (params) {
    var widget = this;
    var target = params.target;

    var rendererTarget = document.createElement('div');
    target.appendChild(rendererTarget);
   
    var myTable = Retina.Renderer.create('table',
        { 'target': rendererTarget,
          'data': Retina.RendererInstances.table[0].exampleData() } );
    myTable.render();

    return widget;
};

Once the table is created via the Retina.Renderer.create method, it still needs to be rendered by calling the render function. You can update the parameters of a renderer at any time and then call the render function again to display the new data. You can access the parameters of the created renderer via the settings property. For example, lets make the cells in first column of the table editable.

    myTable.settings.editable = { 0: true };
    myTable.render();

You can add multiple instances of the same renderer to a page. Retina stores a reference to every instanciated renderer in the Retina.RendererInstances object. The key is the name of the renderer and the value is a list of the actual instances. The 0 index is the base reference and the actual instances start at index 1. You can see in the example above how the base reference is used to retrieve the exampleData. The myTable instance in the example would be stored in Retina.RendererInstances.table[1].

You should browse through the available renderers in Retina via the renderer list in the menu. Of course you are welcome to create your own renderers. If you want to include a renderer that is not in the directory you picked in the Retina.init function, you can pass the directory to the setup call.

widget.setup = function () {
    return [
        Retina.load_renderer({'name': 'myrenderer', 'resource': 'renderers'})
    ];
};

By default Retina will look in the Retina/renderers directory for the renderer script files. Note that the directory is always relative to the html root directory.

In the next section we will take a look at the

>> data management with stm