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

jqcViewModel


This document matches version 1.6.0 .

The jqcViewModel component is used internally by data bound GUI components. The jqcViewModel references the data objects the GUI component is displaying. When you create a data bound GUI component it creates a jqcViewModel internally, so you don't actually have to create jqcViewModel instances yourself. You still need to understand how they work, though.

The jqcViewModel as jqcDataModel Listener

The jqcViewModel object is designed to function as a jqcDataModel listener. Therefore the jqcViewModel object contains the same functions as the jqcDataModel. This allows a jqcViewModel instance to be registered as a listener with a jqcDataModel. Thus, whenever the jqcDataModel changes, the listening jqcViewModel instances automatically update themselves, and trigger a re-rendering of their GUI components.

Here is an example that shows how a jqcViewModel is added as listener to a jqcDataModel:

<table id="taskTable"     jqc-type="jqcTable"   ></table>
<span  id="taskDataModel" jqc-type="jqcDataModel"></span>

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

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

        var components = null;

        bootModule.postInstantiate = function() {
            components = bootModule.jqc.pageController.components;
        };

        bootModule.postConfigure   = function() {
            var taskTable = components.taskTable;
            taskTable.columns ([ { label : "Title"       , field: "taskTitle" },
                                 { label : "Description" , field: "taskDesc" }
                               ]);
            taskTable.viewModel.idField("taskId");
            
            components.taskDataModel.addListener(taskTable.viewModel);
            
        }

        return bootModule;
    }
</script>

Setting Data on the jqcViewModel Directly

Attaching a jqcViewModel as a listener to a jqcDataModel is mostly useful if more than one GUI component are showing the same data. Thus, they can share the data via a shared jqcDataModel. When the jqcDataModel changes, all the GUI components are notified so they can update themselves.

If only one GUI component is displaying the given data, then you do not need to connect a jqcViewModel to a jqcDataModel. Instead you can call the setData(), addData(), updateData() and removeData() functions directly. Here is an example:

<table id="taskTable" jqc-type="jqcTable" ></table>

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

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

        bootModule.postInstantiate = function() {
            components = bootModule.jqc.pageController.components;
        };

        bootModule.postConfigure   = function() {
            var taskTable = components.taskTable;
            taskTable.columns ([ { label : "Title"       , field: "taskTitle" },
                                 { label : "Description" , field: "taskDesc" }
                               ]);
            taskTable.viewModel.idField("taskId");
            
            taskTable.viewModel.setData([
                { taskId : "4", taskTitle : "Task 4", taskDesc : "This is the fourth task."}
            ]);

        }

        return bootModule;
    }
</script>

This example creates a jqcTable component and a module named bootModule. The bootModule's postConfigure() function configures the jqcTable and calls taskTable.viewModel.setData(). This call sets the data to be displayed in the jqcViewModel of the jqcTable.

jqcViewModel.idField()

To be able to update itself correctly internally, the jqcViewModel needs all data objects given to it to have a unique id as a property. The name of that data object property has to be set via the jqcViewModel.idField() function.

If you look at the example from the previous section, you will notice how the bootModule.postConfigure() function calls the taskTable.viewModel.idField() with the parameter value taskId. If you then look at the data set on the taskTable.viewModel just after that, you can see that the data object in the array has a property called taskId. This property contains unique task IDs. The jqcViewModel used by the taskTable will then use this field to match objects given to it via updateData() and removeData().

View Model Objects

The jqcViewModel creates an array of "view model objects" internally. Each view model object references a data object. The view model objects are created when either setData(), addData(), updateData() or removeData() is called. It is the view model objects which are passed to the filter function and sort function of the jqcViewModel (see below for more information).

A view model object contains the following properties:

PropertyDescription
dataObject The data object this view model object references.
element The HTML element (jQuery enhanced) this view model object is rendered inside. This property should be set by the GUI component once the view model has been rendered the first time. If a GUI component does not use HTML elements to render each view model object (e.g. because it draws them on an HTML5 canvas), this property is just set to null.
modelStatus The modelStatus property tells the status of the view model object. So far it can have one of these values: added, updated, removed, clean.

The value added means that the view model object has just been added (either via a call to setData() or addData() on the jqcViewModel). The GUI component then knows it has to render this view model object from scratch (e.g. create a new HTML element to display it in).

The value updated means that the view model object has just been updated (via a call to updateData() on the jqcViewModel). The GUI component then knows that this view model object has to be re-rendered. It may not need to create new HTML elements for the view model object, but the content of the HTML elements displaying the view model object must be updated.

The value removed means that the view model object has just been removed (via a call to removeData() on the jqcViewModel). The GUI component then know that this view model object should no longer be rendered. The GUI component can then remove the HTML elements that display this view model object.

The value clean means that this view model object has not been changed since the last time it was rendered. The GUI component then knows that it does not need to update the HTML elements rendering this view model object. Once an added or updated view model object has been rendered, its modelStatus is set to clean.

Some GUI components may add more properties to the view model objects. For instance, whether the given object is selected, expanded etc.

Filtering

It is possible to set a filter function on a jqcViewModel. The filter function makes it possible to filter the data objects the GUI component owning the jqcViewModel object shows. Filtering only affects the one jqcViewModel, so if multiple GUI components are bound to the same data model they will not be affected by each other's filtering.

You set a filter function simply by calling the filterFunction() function of the jqcViewModel instance (typically in the postConfigure() of a module). Here is an example:

taskTable.viewModel.filterFunction(function(viewModelObject) {
    if(viewModelObject.dataObject.firstName == "Jakob") return false;
    return true;
});

Sorting

It is possible to set a sorting function on a jqcViewModel. The sort function makes it possible to sort the data objects to display. The sorting of each jqcViewModel is independent of the sorting used in other jqcViewModel instances. Thus, each GUI component can show data from the same jqcDataModel sorted differently by each GUI component's jqcViewModel.

You set a sort function by calling the sortFunction() function of the jqcViewModel instance (typically in the postConfigue() function of a module). Here is an example:

taskTable.viewModel.sortFunction(function(vmoA, vmoB) {
    if(vmoA.dataObject.taskTitle < vmoB.dataObject.taskTitle) return -1;
    if(vmoA.dataObject.taskTitle > vmoB.dataObject.taskTitle) return  1;
    return 0;
});

The two parameters to the sort function are the view model objects to be compared.

Functions

Function Description
idField(idFieldName) This function sets the name of the id field of the data objects referenced by this jqcViewModel. The id field in the data objects must contain the unique id for each data object. This field name is used when updating and removing data objects in the jqcViewModel object. The jqcViewModel object matches the incoming data objects with the internal data objects via the property which name is set in the idField.
parentIdField(idFieldName) This function sets the name of the parent id field of the data objects referenced by this jqcViewModel. The parent id field in the data objects must point to the id of another data object, to which this data object is a child. Thus, even if the list of data objects is kept in a flat array internally, the GUI components can still "glue" them together into a tree structure based on the parent id of each data object.
filterFunction(filterFunction) This function sets a filter function on the jqcViewModel. The filter function is called by the GUI component owning the jqcViewModel when the GUI component iterates all the view model objects during rendering. If the filter function returns true, the given view model object will be rendered. If the filter function returns false, the given view model object will not be rendered. Regardless of what the filter function returns, the view model objects are still kept internally in the jqcViewModel. The filtering only applies during rendering.
sortFunction(sortFunction) This function sets a sort function on the jqcViewModel. The sort function is called internally by the jqcViewModel everytime the view model object array is updated. This happens whenever one of the setData(), addData(), updateDate() or removeData() functions are called.
setData(dataObjectArray) Sets the array of data objects to be displayed by this jqcViewModel
addData(dataObjectArray) Add the array of data objects to the data objects already kept internally in this jqcViewModel
updateData(dataObjectArray) Replaces the data objects kept internally in this jqcViewModel with the data objects passed in this array. The data objects to be replaced are found by matching the incoming data objects against the internal data objects via the property specified via the jqcViewModel.idField() function call.
removeData(dataObjectArray) Removes the data objects kept internally in this jqcViewModel which have the same IDs as the data objects in the given data object array. The data objects to be removed are found by matching the incoming data objects against the internal data objects via the property specified in the jqcViewModel.idField() function call.