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

jqcTable


This document matches version 1.6.0 .

The jqcTable component is used to display data objects in tables. It is able to show an array of JavaScript objects in a table with one field per column.

jqcTable Example

Here is an example that shows how to use a jqcTable in your applications:

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

Notice how the columns() function is called with an array of objects, each representing a column (vertically) in the table. Each column has a label which is shown in the header row in that column, and a field which is the data object field to display in data rows in that column.

Notice too, that the viewModel.idField() is set. This is necessary for the viewModel to be able to update itself correctly internally. See jqcViewModel.idField() for information about that.

Selecting Rows

The jqcTable listens for single clicks on rows (on the tr elements). When a row is clicked the jqcTable records that internally, and marks that row as selected.

When a table row is selected the jqcTable also adds the CSS class jqcTableRowSelected to the corresponding tr element. By default there is no styling for this CSS class but you can add styling for it yourself. For instance:

.jqcTableRowSelected {
    background-color: #66ff66;
}

This CSS rule would set the background color of the selected rows to a light green color.

If you click again on a row that is already selected, the jqcTable unselects the row, and removes the CSS class jqcTableRowSelected.

Only a single row can be selected at a time with a regular mouse click. If a row is already selected and another row is selected, then the previously selected row is unselected. If you want to select multiple rows in the table, press CTRL down on the keyboard while clicking the rows to select. When CTRL is pressed down while clicking on a table row, the previously selected rows are not unselected.

You can also select and unselect rows using the select(viewModelObject), unselect(viewModelobject) and unselectAllRows() functions. The first two functions require that you already have a reference to the viewModelObject for the row you want to select or unselect. You can obtain that via the clickRow() and dblclickRow() listener functions on jqcTable.

You can access all the selected rows via the function selectedRows(). This function returns an array of viewModelObjects corresponding to the selected rows.

Adding Click Listeners

You can add single click and double click listeners to the jqcTable component using the clickRow() and dblclickRow() functions. 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.clickRow(function(viewModelObject) {
                //do something with clicked viewModelObject
            });

            taskTable.dblclickRow(function(viewModelObject) {
                //do something with double clicked viewModelObject
            });
            

            taskTable.viewModel.setData([
                { taskId : "4", taskTitle : "Task 4", taskDesc : "This is the fourth task."}
            ]);
        }

        return bootModule;
    }
</script>

You can also add click and double click listeners declaratively via the the jqc-click-row and jqc-dblclick-row HTML attributes. Here is an example:

<table id="taskTable" jqc-type="jqcTable"
    
    jqc-click-row="bootModule.clickRow"
    jqc-dblclick-row="bootModule.dblClickRow"
    ></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."}
            ]);
        }

        bootModule.clickRow = function(viewModelObject) {
            //do something with clicked viewModelObject
        }

        bootModule.dblclickRow = function(viewModelObject) {
            //do something with double clicked viewModelObject
        }

        return bootModule;
    }
</script>

Column Renderers

If the default rendering of the columns doesn't meet your needs, you can set your own column render functions for the jqcTable. Here is a code example:


var taskTable = components.taskTable;
taskTable.columns ([ { label : "Title"       , field: "taskTitle" },
                     { label : "Description" , field: "taskDesc" },
                     { label : "Action"      , renderer : function(field, viewModelObject, tableCell) { ... }
                   ]);
taskTable.viewModel.idField("taskId");

taskTable.viewModel.setData([
    { taskId : "4", taskTitle : "Task 4", taskDesc : "This is the fourth task."}
]);

taskTable.viewModel.setData([
    { taskId : "4", taskTitle : "Task 4", taskDesc : "This is the fourth task."}
]);

Notice the renderer property on the third column object. This property contains a function which can render the table cell.

The column renderer function takes three parameters: field, viewModelObject and tableCell.

The field parameter contains the name of the data object field (property) that is being rendered (in the example above that would be action.

The viewModelObject parameter contains the view model object matching the current table row. It is typically from the viewModelObject.dataObject that you need to extract the columnProperty (e.g. viewModelObject.dataObject[columnProperty]), provided that the columnProperty actually exists in the data object.

The tableCell parameter contains the HTML table cell (td) into which the column renderer should render its content. The tableCell is a jQuery enhanced DOM element so you can use the standard jQuery functions on it.

In the example above, the column renderer creates a button, sets a click listener on it, and appends the button to the tableCell. The column rendered for the column property action is thus a button, not a property extracted from the data object for that row.

Attributes

You can use the following attributes inside the HTML element declaring the jqcTable:

AttributeDescription
jqc-click-row Sets the name of a global JavaScript function, or a function in a module or component, to call when a row in the jqcTable is clicked. E.g. rowClicked or myModule.rowClicked .
jqc-dblclick-row Sets the name of a global JavaScript function, or a function in a module or component, to call when a row in the jqcTable is double clicked. E.g. rowDblClicked or myModule.rowDblClicked .

Properties

PropertyDescription
viewModel The jqcViewModel containing the data objects (wrapped in view model objects) to be displayed in this jqcTable.

Functions

FunctionDescription
columns(columnsArray) The columns() function configures the jqcTable columns. The function takes an array of JavaScript objects of the form
{ label : "Name", field : "taskName", renderer : function(){ } } .
The label field of each object defines the label of the column in the table. The label is displayed in a header row above each column. The field field of each object defines which field (property) from the data objects to display in this column. The renderer field of each column object can contain a function which can render the HTML to show inside the table cell.
clickRow(clickListener) The clickRow() function can be used to set a listener function on the jqcTable instance which is called whenever a table row is clicked.
dblclickRow(dblclickListener) The dblclickRow() function can be used to set a listener function on the jqcTable instance which is called whenever a table row is double clicked. Note: A double click seems to trigger two single clicks events before the double click event.
selectRow(viewModelObject) The selectRow() function selects a certain row in the table. You need a reference to the viewModelObject for the row you want to select.
unselectRow(viewModelObject) The unselectRow() function unselects a certain row in the table. You need a reference to the viewModelObject for the row you want to select.
unselectAllRows() The unselectAllRows() function unselects all table rows.
selectedRows() The selectedRows() function returns an array of viewModelObjects corresponding to the rows which are currently selected in the table.