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 Boot Process


This document matches version 1.6.0.

When you call the boot() function on the jqcPageController instance, the page controller boot process starts. The boot process initializes the components and modules so that the page is ready to serve the user.

The Boot Phases

The boot process progress through a set of phases, as illustrated in this diagram:

The jqComponents page controller boot process

The boot process passes through the following phases:

  1. Instantiate modules
  2. Register component factories
  3. Call postRegister() on modules
  4. Instantiate components
  5. Call postInstantiate() on modules
  6. Configure components
  7. Call postConfigure() on modules
  8. Layout components
  9. Call postLayout() on modules
  10. Render components
  11. Call postRender() on modules

First the page controller scans the HTML page for HTML elements with a jqc-module attribute. The value of the jqc-module attributes are interpreted as the name of a factory function which returns a module JavaScript object when called. The page controller calls the factory function and keeps the module JavaScript internally.

Second, the page controller registers all component factory functions internally in its factories property. This is done by executing the page controller's register() function. Once this function has finished executing the factories object contains a set of component factory functions. These functions are properties of the factories object. The property name for each factory function is the same name you use in the jqc-type attribute. See fourth phase.

Third, the page controller calls the postRegister() function on all module objects which has such a function. Inside this function each module gets the chance to add component factories to the page controller, before the page controller scans the HTML page for components to instantiate.

Fourth, the page controller scans the HTML page for HTML elements with a jqc-type attribute. The values of the jqc-type attributes are interpreted as the property name (in the factories object) of a factory function which can instantiate the components. For instance, after the register phase is executed, the factories object will contain a property named jqcLabel which points to a factory function which can create components of type jqcLabel. When you put a jqc-type="jqcLabel" attribute on an HTML element, this function is called to create the corresponding component for that HTML element.

Fifth, the page controller calls the postInstantiate() function on all modules which have such a function. Inside this function the modules gets the chance to add components to the page controller which are instantiated by the modules themselves, instead of by the page controller.

Sixth, the page controller iterates through all its components and checks if they have a configure() function. If they do, then this configure() function is called. This function enables the component to configure itself. A component may contain hard coded configuration, or it may look at the HTML element it is associated with for configuration (e.g. via attributes or nested elements).

Seventh, the page controller calls the postConfigure() function on all modules that have such a function. Inside this function each module has the chance to configure the components after instantiation, knowing that all components have been instantiated at this time. For instance, it is typically in the postConfigure() function that event listeners are attached to the components.

Eighth, the page controller iterates through all its components and checks if they have a layout() function. If they do, then this function is called. Most components do not have a layout function. It is primarily the jqcResponsiveLayoutManager which has this function. In this function the jqcResponsiveLayoutManager calculates the widths of cells in the grid.

Ninth, the page controller calls the postLayout() function on all modules that have this function. Inside this function each module has the chance to make changes to the components based on their width. The layout phase determines the width of visual components (or their container elements), if you use the built-in responsive layout manager. If you use something else for layout, e.g. Bootstrap, then this phase is not any different from the postConfigure() phase.

Tenth, the page controller iterates through all its components and checks if they have a render() function. If they do, then this function is called. Visual components typically have a render() function, while non-visual components like remote data services and timers do not. Inside the render() function visual components can generate HTML via JavaScript, jQuery, call functions on a HTML5 canvas, WebGL, D3 or whatever else they might need to render themselves.

Eleventh, the page controller calls the postRender() function on all modules that have this function. Inside this function each module has the chance to perform any final initialization of the page they might desire. It is typically in this function that modules may call remote data services to load the initial data to be displayed in the page.

This means, that the page controller may call the following functions on modules:

postRegister()
postInstantiate();
postConfigure();
postLayout();
postRender();

And the page controller may call the following functions on components:

configure();
layout();
render();

This may look complicated, but it actually isn't so bad. Modules and components flow through the phases together, and for every step in the process, the modules gets a chance to act in between the calls to the components.

The Page Controller After Booting

Once the page controller has booted the page, it becomes passive. From there on, all activity takes place in components and modules.

After booting the page controller looks like this:

The page controller after booting

The page controller contains these JavaScript objects:

The factories object contains a set of factory functions for creating components. Once the page is booted you will most often not need to access this.

The components object contains all components instantiated by (or added to) the page controller. The property name of a component is the same name as you give the id of the component. For components added via an HTML element, that is the value of the id attribute of that HTML element. Thus, if you add a component using this HTML:

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

Then you can access that component via the page controller like this:

pageController.components.myLabel

The modules object contains all modules instantiated by, or added to, the page controller. The property name of a module is the id given to it in the id attribute if created via an HTML element, or the id passes as first parameter to the addModule(id, moduleObject) function call. Thus, if the id of a module is myPageModule then you can access it via the page controller like this:

pageController.modules.myPageModule

The jqc Objects

One final thing worth mentioning is that the page controller inserts a jqc object into every component and module. That means, that a property named jqc is added to every component and module.

The jqc object can be referenced simply by referencing the component or module and then append .jqc to the reference. Then you have access to the jqc object. Example:

pageController.components.myLabel.jqc

The jqc object contains the following properties:

The id is the id given to the component or module, either via its HTML element id attribute, or via the first parameter in the page controller function calls addComponent(id, componentObject) or addModule(id, moduleObject).

The element property contains the HTML element the component is associated with. This is the HTML element that contains the jqc-type attribute for this component. The element property is a jQuery enhanced DOM element, so you can call all the jQuery functions you are used to (e.g. html(), text(), show(), hide() etc.). Modules do not have an element property in their jqc object, even if they were created via an HTML element.

The pageController property contains a reference to the page controller object itself. That way components and modules can access the page controller without knowing what name the page controller variable was given in the HTML page.

That is pretty much it. After this you are ready to create your first jqComponents application.