Implementing The Block Controller

coServ provides a front-end engine (wFront.js) which should be included in a coServ application. The front-end engine creates a controller for each block and it also provide several helper functions to assist controllers to perform their tasks.

The front-end engine can be accessed as _wf or __. Of all its available functions, probably the only one that is useful to you is the getController() function. With this function, you'll be able to find the controller of any block in a page, and use the controller to interact with that block. For example:

var  blkCtrl = __.getController('a_block_id');
// do something about that block

Now, let's get back to the controller. coServ binds a controller to each block. Each controller has several built-in functions which will be explained later. Every controller is customizable. That means you can define your own function in a controller. Assuming we have a "calculator" block and its controller is customized as:

var  currentValue = 0;

ctrl.calculate = function(op)  {
    switch (op)  {
        case '+':
            currentValue += getInput();
            break;

        case '-':
            currentValue -= getInput();
            break;
    }
    displayResult( currentValue );
}

function getInput()  {
    return  parseInt( ctrl.sel('#panel').val() );
}

function displayResult(result) {
    return  ctrl.sel(#panel')vale( result );
}

There are three functions defined in the controller: ctrl.calculate(), getInput() and displayResult(). If a function is to be accessible outside of a controller, it should be defined as ctrl.xxx(). So in our example above, the getInut() and displayResult() functions are not visible outside of the controller.

Controller built-in functions

Each controller has the following built-in functions:

ctrl.getTarget()

This function returns the container which hosts (embeds) the current block.

ctrl.getParent()

Using this function to get the controller of the parent block.

ctrl.sel(selector)

This is similar to the jQuery $() function except that it only searches the DOM object within the scope fo the current block. This helps us not to accidentally refer to selectors in other blocks.

ctrl.embed(selector, blockPath, params, callback)

This function can dynamically embed a block from the client side. Its parameters are:

selector : a CSS selector to indicate which tag will be used as the container to embed the new block. This parameter is required.
blockPath : a file path relative to the '$web_root/$website_name/themes/$theme/block/views' directory. With this parameter, coServ can locate the all the related files of the embedded block. This parameter is required.
params: The actual input to a block. This parameter is optional.
callback: When the embedded block is fully loaded and displayed on a page, the callback function will be invoked with a parameter which is the controller of the newly embedded block. This parameter is optional.

Let's see an example:

ctrl.embed('#conatiner', '/calendar', function(calendarCtrl) {
    calendarCtrl.getCurrentDate();
});

The sample code above will embed a block ('/calendar') to a #container tag. When the block is loaded, the callback function will envoked with its controller (calendarCtrl) so we can query the current date.

ctrl.embed() is polyformed

The ctrl.embed() function can be invoked with various parameter combinations. Below are all possible signatures:

ctrl.embed( selector, blockPath ) : this is the minum form.
ctrl.embed( selector, blockPath, params ) : no call back needed.
ctrl.embed( selector, blockPath, callback ) : the block does not need input.

ctrl.reload(blockPath, options, callback)

This function can reload the block itself in the client side. This function accepts the following parameters:

blockPath : a file path relative to the '$web_root/$website_name/themes/$theme/block/views' directory. With this parameter, coServ can locate the all the related files of the target block. This parameter is optional.
params: The actual input to a block. This parameter is optional.
callback: When the block is fully loaded and displayed on a page, the callback function will be invoked with a parameter which is the controller of the newly load block. This parameter is optional.

ctrl.reload() is polyformed

The ctrl.reload() function can be invoked with various parameter combinations. Below are all possible signatures:

ctrl.reload(): reloading the same block without input and callback.
ctrl.reload( blockPath ): replacing the existing block with another block (designated by blockPath) without input and callback.
ctrl.reload( params ): reloading the same block with new inputs and without callback.
ctrl.reload( callback ): reloading the same block without input but callback is required.
ctrl.reload( blockPath, params ): replacing the existing block with another block (designated by blockPath) and providing inputs.
ctrl.reload( params, callback ): reloading the same block with new inputs and callback.
ctrl.reload( blockPath, params, callback ): all three parameters are provided.

ctrl.addHandler(event, controller)

This function is used for a block to accept event handler. The 'event' parameter is a string and its value is defined by the developer of the block. Consider the following example:

ctrl.embed('#conatiner', '/calendar', function(calendarCtrl) {
    calendarCtrl.addHandler('dateChanged', function(date)  {
        // a new date chosen, do something about it
    );
});

where a block embeds a calendar block and register a callback function to the 'dateChanged' event of the calendar block.

ctrl.callHandler(event, args)

This function is used when a block wants to notify all the listeners of a particular event. Following teh addHandler() example above, the calendar block can notify its event listeners this way:

ctrl.dateChanged = function() {
    ctrl.callHandler('dateChanged', {date: getDate()});
}

function getDate()  {
    // get the selected date of the calendar
}

Implementing The Block Controller