Documentation

1 Getting Started
2 Design Overview
3 Page Controller Boot Process
4 Your First App
5 Page Controller
6 Modules
7 Components
8 jqcEmpty
9 jqcLabel
10 jqcButton
11 jqcLayer
12 jqcPanelDeck
13 jqcAccordion
14 jqcProgressBar
15 Data Binding & Remote Data Synchronization
16 jqcDataService
17 jqcDataModel
18 jqcViewModel
19 jqcList
20 jqcTable
21 jqcForm
22 jqcResponsiveLayoutManager
23 jqcTreeList
24 Demos

Modules


Modules are where you put your application specific code. Modules are ordinary JavaScript objects. The page controller adds your modules to itself during its boot process.

Adding Modules to the Page Controller

Adding modules to the page controller is covered detail in the text about the page controller.

Here is a simple example though:


<span jqc-module="myModule"></span>

<script>
function myModule() {
    var module = {};
    
    //add functions to the module
    
    return module;
}
</script>

The page controller detects all HTML elements with jqc-module attributes when the page controller boots. These HTML elements only serve as declarative configuration of the page controller, so it is best to use a non-visual element like an empty span element.

The span element in the example above contains the jqc-module attribute with the value myModule . The page controller then looks for a global JavaScript function called myModule(). If the page controller finds the function it will call it and store the returned module object internally in its own modules object.

The JavaScript function myModule() is a factory function which creates a JavaScript object - a module. A module can contain a set of boot phase functions, and all the custom functions your applications need. The boot phase functions are covered later in this text.

If you only have one instance of the module (which is the most common situation) you can also move the jqc-module attribute inside the script element, like this:

<script jqc-module="myModule">

function myModule() {
    var module = {};

    //add functions to the module

    return module;
}
</script>

The Module Factory Function

The module factory function needs to return a JavaScript object containing all fields and functions the module should have. The module factory function can just create a JavaScript object and add fields and functions to it, as shown in this module factory example:

<script jqc-module="myModule">

function myModule() {
    var module = {};

    module.counter = 0;
    
    module.postRender = function(){
        console.log(module.counter);
    }

    return module;
}
</script>

From version 1.7.0 the module factory function has an empty JavaScript object passed to it as argument. This empty JavaScript object can be used as the module object. Thus, the module factory function does not need to create nor return a module object. This makes your code a bit shorter. Here is how that looks:

<script jqc-module="myModule">

function myModule(module) {
    module.counter = 0;
    
    module.postRender = function(){
        console.log(module.counter);
    }
}
</script>

Notice how the factory function now declares the module as a parameter, and adds a field and a function to it.

Multiple Instances of the Same Module

A module will only be created once, unless your HTML page contains multiple HTML elements with same value for the jqc-module attribute. Actually, you could create multiple instances of the same module like this:

<span id="myModule1" jqc-module="myModule"></span>
<span id="myModule2" jqc-module="myModule"></span>

This example declares two modules with different id attributes, but using the same module factory function. The page controller will store these two modules internally by the value of their id attribute instead of their module factory function name.

The Module ID

A module is stored internally in the page controller based on its id. If the HTML element declaring the module does not contain an id attribute, then the module factory function name is used as the id of the module. Look at this example:

<span jqc-module="mathModule"></span>

The id of this module becomes mathModule.

If you add an id attribute to the HTML element then the value of this id attribute will be used as the module id. Look at this example:

<span id="math" jqc-module="mathModule"></span>

The id of the module declared by this HTML element will be math since that is the value of the HTML element's id attribute. Thus, the page controller will store the module internally in its modules object using the id math. You can then access the module via jqc.pageController.math.

Before version 1.4.0 the id attribute was mandatory in HTML elements declaring a module, but since 1.4.0 it is optional.

A Multi Module Example

Here is a code example that adds two modules to the page controller using HTML elements. The example adds two components too.

<!DOCTYPE html>
<html>

<head>
    <script  src="http://code.jquery.com/jquery-1.11.1.min.js"></script>

    <script  src="/js/jqc/1.5.0/jqc-all.js"></script>
    <link   href="/js/jqc/1.5.0/jqc-all.css" rel="stylesheet" type="text/css">
</head>

<body>

<span   id="myLabel"   jqc-type="jqcLabel"></span>
<button id="myButton"  jqc-type="jqcButton">Click</button>

<span jqc-module="bootModule"></span>
<span jqc-module="myModule"></span>

<script>

    function bootModule() {
        var bootModule = {};

        bootModule.postConfigure = function() {
            bootModule.jqc.pageController.components.myButton.click(function() {
                bootModule.jqc.pageController.modules.myModule.buttonClicked();
            });

        }

        return bootModule;
    }

    function myModule() {
        var module = {};

        module.buttonClicked = function() {
            module.jqc.pageController.components.myLabel.setHtml("You clicked the button!");
        }

        return module;
    }
</script>

</body>
</html>

Module Functions

A module can contain the following boot phase functions:

Function NameDescription
postRegister() Called by the page controller after registration of the core component factories. Inside this function a module can register its own component factories before the page controller scans the HTML page for components (HTML elements with a jqc-type attribute).
postInstantiate() Called by the page controller after all components found in the HTML page have been instantiated. Inside this function a module can add its own component objects, in case the module has instantiated a module itself. The page controller will then take care of calling configure(), layout() and render() on the component.
postConfigure() Called by the page controller after all components have been configured (had their configure() function called). Inside this method the module can add any configuration to the components the app might need. This could be setting URLs on a data service component, or adding event listener callback functions etc.
postLayout() Called by the page controller after all components have been laid out (had their layout() function called). You will not often need to implement this function.
postRender() Called by the page controller after all components have been rendered for the first time (had their render() function called). Inside this function the module can perform any final initialization of the app necessary. For instance, it will typically be inside this function that the module will trigger calls to remote data services (which in turn will trigger updates to the GUI when data is returned from the remote services.)

A module does not have to implement all of these functions. In fact, a module does not need to implement any of these functions. It depends on what your module needs to do to the page and its components before the application is ready to serve the user.

A module can also contain other functions than the boot phase functions. It can contain application specific functions. For instance, a submitForm() function, or addTask() function, or whatever else your application needs. These functions will typically get called by event listener callback functions registered on components. For instance, the submitForm() function might get called by the event listener added to a "submit" button.

You can split your application specific code into as many modules as you like. You might want to create a specific "boot initialization" module which just configures components and adds event listener callback functions to components. And you might want to keep all the application specific functions in their own module(s). It is really up to you how you divide your code into modules.