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

Page Controller


The page controller (jqcPageController) is the center piece of jqComponents. The page controller structures your applications. It handles the initialization of components and modules and functions as a container for both after the application is booted.

The reason it is called a "page controller" and not an "app controller" is that an app can consists of multiple pages, and the page controller only handles a single page.

Creating a Page Controller

When you include the jqComponents JavaScript file (jqc-all.js or a custom build) in your HTML page, the jqComponents JavaScript file will create a page controller and boot it automatically. Automatic creation of the page controller was added in version 1.0.0. Manually creating and booting a page controller is covered later.

Before version 1.4.0 the automatically created page controller was available via the global variable pageController. Since 1.4.0 the global variable pageController has been moved inside a global variable named jqc. Thus, pageController needs to be accessed via the global jqc object, like this: jqc.pageController . This should not affect your code, since the preferred way of accessing the page controller is via the module.jqc.pageController or component.jqc.pageController properties as explained in The Page Controller Boot Process.

Creating a Page Controller Manually

If you don't want jqComponents to automatically create a jqcPageController, you create a page controller like this:

var jqcAutoBoot = false;      //turns off automatic creation and booting of a jqcPageController

var pageController = null;
jQuery(document).ready(function() {
   pageController = jqcPageController();
});

Note: Since 1.4.0 it looks like this:

var jqcAutoBoot = false;      //turns off automatic creation and booting of a jqcPageController

jQuery(document).ready(function() {
   jqc.pageController = jqcPageController();
});

The global variable jqcAutoBoot signals to jqComponents whether or not to create and boot a page controller automatically. When set to false, no page controller is created.

Notice that the page controller should be instantiated inside jQuery's "document - ready" event handler function. This is done to make sure that the page resources are fully loaded before you create the page controller. When jqComponents creates and boots a page controller automatically, it is also done inside a "document - ready" event handler function.

Booting the Page Controller

If you create your own page controller, you will also have to boot it manually. You do so using the boot() function. Here is an example:

var jqcAutoBoot = false;

var pageController = null;
jQuery(document).ready(function() {
   pageController = jqcPageController();
   pageController.boot();
});

Note: Since 1.4.0 it should look like this:

var jqcAutoBoot = false;
jQuery(document).ready(function() {
   jqc.pageController = jqcPageController();
   jqc.pageController.boot();
});

Exactly what happens when the page controller is booting is explained in the page controller boot process text.

If you let jqComponents create a page controller for you, jqComponents will also boot it for you.

Adding Modules

Modules contain your application specific code. You can add one or more modules to the page controller in two ways:

  1. Via HTML by adding a jqc-module attribute to an HTML element.
  2. Programmatically using the addModule(id, moduleObject) function on the page controller.

Adding Modules Via HTML

You can add a module to the page controller by inserting a jqc-module HTML attribute into an HTML element somewhere in your HTML page. The module does not use the HTML element for anything else than being a declarative way of adding a module. Therefore it is recommended that you use an empty span element to declare modules, since an empty span element will not have any visual impact on your HTML page. Here is an example:

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

This example adds a module named bootModule to the page controller. When booting, the page controller scans the page for elements with a jqc-module attribute. The value of the jqc-module attribute is assumed to be the name of a module factory function. In the example above the module factory function is assumed to be named bootModule(). Here is an example that includes both the module declaration and the module factory:

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

<script>
function bootModule() {
    var module = {};

    module.postRender = function() {
        //do something after components have rendered themselves.
    }

    return module;
}
</script>

As mentioned, you can add more than one module to the page controller. Just insert an HTML element with a jqc-module attribute and a corresponding factory function for each module.

You can also move the jqc-module attribute inside the script element, like this:

<script jqc-module="bootModule">

function bootModule() {
    var module = {};

    module.postRender = function() {
        //do something after components have rendered themselves.
    }

    return module;
}
</script>

This version is a bit shorter / cleaner, as you don't have any empty HTML elements to represent modules.

Adding Modules Programmatically

The only way to add modules programmatically is by creating and booting a page controller yourself. There is no other way to plug in modules programmatically. Here is an example of how that is done (after version 1.4.0):

<script>
var jqcAutoBoot = false;
jQuery(document).ready(function() {
    jqc.pageController = jqcPageController();

    jqc.pageController.addModule("bootModule", bootModule());

    jqc.pageController.boot();
});
</script>

<script>
function bootModule() {
    var module = {};

    module.postRender = function() {

    }

    return module;
}
</script>

Modules added programmatically should be added before calling pageController.boot(). Otherwise the module will not have its postRegister(), postInstantiate(), postConfigure(), postLayout() and postRender() functions called.

If you do not create and boot the page controller yourself, add modules via HTML elements. That is the only way to have the modules added correctly when you do not create the page controller yourself. This is not a problem though, since there is no functional difference between adding a module programmatically and via HTML elements.

Accessing Modules

Modules are accessible via the page controller's modules property in the same way components are accessible via the page controller's components property. Here is an example showing two modules with one accessing the other:

<span jqc-module="module1"></span>
<span jqc-module="module2"></span>

<script>
function module1 () {
    var module = {};

    module.myUtil = function() {
        //implement some utility functionality
    }

    return module;
}


function module2() {
    var module = {};

    module.postRender = function() {
        var modules = module.jqc.pageController.modules;

        modules.module1.myUtil();
    }

    return module;
}
</script>

Notice how module2 accesses module1 from inside its postRender() function.

Having modules be able to access each other is really useful when splitting your application into multiple modules.

In case you want the id of the module to be different than the module factory function name, you can set an id attribute ion the HTML element declaring the module. Here is an example showing that:

<span id="module1" jqc-module="module1Factory"></span>
<span id="module2" jqc-module="module2Factory"></span>

<script>
function module1Factory () {
    var module = {};


    module.myUtil = function() {
        //implement some utility functionality
    }

    return module;
}

function module2Factory() {
    var module = {};


    module.postRender = function() {
        var modules = module.jqc.pageController.modules;

        modules.module1.myUtil();
    }

    return module;
}
</script>

Adding Components

Components contain reusable functionality like GUI components, timers, data services etc. You can add components to the page controller in two ways:

  1. Via HTML by adding a jqc-type attribute to the HTML element you want to attach the component to.
  2. Programmatically via the addComponent(id, componentObject, componentElement) function on the page controller.

Adding Components Via HTML

Adding components via HTML looks like this:

<span id="myLabel" jqc-type="jqcLabel"></span>

It is the jqc-type attribute inside an HTML element that signals to the page controller that a component should be created. The value of the jqc-type attribute is the type of component to create. In this example it is a jqcLabel component that is created.

When the page controller boots it scans the HTML page for components and instantiates and initializes them. This happens no matter if the page controller is created automatically or manually. The component scan happens during boot of the page controller, and booting has to happen regardless of how the page controller is created.

Adding Components Programmatically

You add components programmatically to the page controller via the addComponent() function. The addComponent(id, componentObject, componentElement) function takes three parameters. The first parameter is the id of the component. You can access the component via this id as a property in the page controller's components object (e.g components.myLabel). The second parameter is the component JavaScript object. The third is the HTML element that the component is associated with (attached to). This has to be a jQuery enhanced DOM element (e.g jQuery("#myLabel")).

You can add components programmatically to the page controller in two ways. Both ways use the page controller's addComponent() function, but the function calls are located in different places.

The first method is to call addComponents() from inside the postInstantiate() function of a module. This method works whether you use an automatically or manually created page controller. Thus, this is the recommended way to add components programmatically.

Here is an example of how to add a component to the page controller programmatically from inside the postInstantiate() function of a module:

<span id="myLabel" jqc-type="jqcLabel"></span>

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

<script>
function bootModule() {
    var module = {};

    module.postInstantiate = function() {
        module.jqc.pageController.addComponent("myLabel", jqcLabel(), jQuery("#myLabel") );
    }

    return module;
}
</script>

The second method of adding components to the page controller is to add the components to the page controller before the page controller is booted. This method can only be used if you create and boot the page controller manually. Here is how that looks (after version 1.4.0):

var jqcAutoBoot = false;
jQuery(document).ready(function() {
    jqc.pageController = jqcPageController();

    jqc.pageController.addComponent("myLabel", jqcLabel(), jQuery("#myLabel") );

    jqc.pageController.boot();
});

Components added to the page controller this way should be added to the page controller before calling pageController.boot(). Otherwise the component will not have its configure(), layout() and render() functions called by the page controller.

Adding Custom Components

You can add your own custom components to the page controller too. You can do so via HTML or programmatically.

Adding Custom Components Via HTML

To be able to add a custom component via HTML you must first have registered a component factory for the given component type. From version 1.4.0 that too can be done via HTML. Here is an example that registers a component factory with the page controller via HTML:

<span jqc-factory="myComponent"></span>    

The jqc-factory attribute signals to the page controller that a component factory function named myComponent() should be registered. All components with a jqc-type attribute value of myComponent will be created using this factory function.

You can also register a custom component factory programmatically from inside a module's postRegister() function. You will see how that looks later.

Once a component factory is registered (via HTML or programmatically), you can use the component type inside the jqc-type attribute to create instances of your custom component. Here is an example:

<span jqc-factory="myComponent"></span>

<span id="myComponent1" jqc-type="myComponent"></span>
<span id="myComponent2" jqc-type="myComponent"></span>

Adding Custom Components Programmatically

Adding custom component factories programmatically can be done from inside the postRegister() function of a module. Here is an example of how that looks:

<span id="myComponent" jqc-type="myComponent"></span>


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

<script>
function bootModule() {
    var module = {};

    module.postRegister = function() {
        module.jqc.pageController.addFactory("myComponent", myComponent);
    }

    return module;
}

function myComponent() {
    var component = {};

    component.render = function() {
        component.jqc.element.html("This is myComponent");
    }

    return component;
}
</script>

Once the custom component factory is registered you can use the registered component type in the jqc-type attributes just like with built-in components.

You can also just add a custom component without registering a component factory for it. Here is an example of how that looks:

<span id="myComponent"></span>

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

<script>
function bootModule() {
    var module = {};

    module.postInstantiate = function() {
        module.jqc.pageController.addComponent("myComponent", myComponent(), jQuery("#myComponent"));
    }

    return module;
}

function myComponent() {
    var component = {};

    component.render = function() {
        component.jqc.element.html("This is myComponent");
    }

    return component;
}
</script>

This example adds a custom component programmatically by calling the component factory function directly in the call to addComponent(). The page controller can still use this component, but it doesn't know the component type.

If you create a page controller manually, you can also add custom component factories and components to the page controller before booting it. Here is an example that adds a custom component in two different ways before booting the page controller:

var jqcAutoBoot = false;
jQuery(document).ready(function() {
    jqc.pageController = jqcPageController();

    jqc.pageController.addFactory("myComponent", myComponent);

    var myComponentObj = jqc.pageController.factories.myComponent();

    jqc.pageController.addComponent("myComponent1", myComponentObj, jQuery("#myComponent1") );

    jqc.pageController.addComponent("myComponent2", myComponent(), jQuery("#myComponent2") );

    jqc.pageController.boot();
});

Accessing Components

Each component added to the page controller which has an id will be accessible via the pageController.components object. The id given the component will be the property name of that component in the components object. Here is an example:

<span id="myLabel" jqc-type="jqcLabel"></span>

<span jqc-module="bootModule"></span>
    
    
<script>
function bootModule() {
    var module = {};
    
    module.postRender = function() {
        module.jqc.pageController.components.myLabel.html("This is the text of my label");
    } 
    
    return module;
}
</script>    

This example creates a component and a module, and accesses the component via the page controller's components object from inside the module's postRender() function. Notice how the id of the component, myLabel, is also used as the component's property name inside the components object.

Components without an id (no id attribute in HTML element or null as id in addComponent() call) will still be added and managed by the page controller, but they will not be accessible via the pageController.components object.

Properties

PropertyDescription
factoriesAn object containing all component factory functions in the page controller. Each factory is accessible via property corresponding to the component type it creates, so the jqcLabel factory is accessible via factories.jqcLabel etc.
componentsAn object containing all components in the page which have an id. Each component is accessible via property corresponding to the component id.
modulesAn object containing all modules in the page which have an id. Each module is accessible via property corresponding to the component id.

Functions

FunctionDescription
boot()Boots the page controller and initializes the components and modules.
addFactory(componentType, factoryFunction) Adds a factory function for the given component type. The component type can then be used inside jqc-type attributes in your HTML page, and the page controller will use the factory function to create a component of that type.

The componentType parameter is the name of the component type to add the factory function for. For instance, the type could be myAppImageSlideshow. You can then use myAppImageSlideshow as component type (value) inside jqc-type attributes in your HTML page.

The factoryFunction is a JavaScript function which returns a component JavaScript object.
addComponent(id, componentObject, componentElement) Adds a component object to the page controller programmatically.

The id parameter is the id you want to give the component. The component can referenced via pageController.components[id] after being added.

The componentObject is the JavaScript component object containing one of more of the functions configure(), layout() and render() (+ whatever else variables and functions your component needs).

The componentElement is the jQuery enhanced DOM element which the component is to be attached to. You will usually select the element from the page using jQuery("#id"). The element does not have to have the same id as the id parameter, but this is normal to do. If your component doesn't need a DOM element, just pass null in the componentElement parameter.
addModule(id, moduleObject) Adds a module to the page controller programmatically.
lookupFunction(functionName) Looks up a global function or a function inside a module or component based on a function name (e.g. myFunction() or myModule.doThisOrThat()). Returns a reference to the given function if found. Added in version 1.4.0.