ParamQuery Grid keeps its data and view separate (literally). And it has two display modes: Virtual and non - virtual mode. Non - virtual mode is the default mode whereby all the rows and columns are displayed at once in the viewport. While in virtual mode or performance mode, it displays or renders only the rows and columns which fit in its scrollable viewport. It's the virtual mode that empowers grid to display unlimited rows and columns. It can be enabled simply by setting the options virtualX ( for columns virtualization ) and virtualY ( for rows virtualization ) to true. Grid refreshes its view ( and refresh event is fired ) whenever the following takes place:
ParamQuery Grid stores data for both local & remote requests in dataModel.data which is a 2 dimensional array or JSON (array of key/value paired objects). It refreshes its local copy of data for remote requests whenever the following takes place:
dataModel.data can be manipulated directly for both local and remote requests.
refreshDataAndView() is invoked usually after direct manipulation of dataModel properties
to put the data and view in sync. refresh() is invoked usually after modification
of the grid DOM.
ParamQuery includes 3 independent jQueryUI widgets/components : pqPager, pqScrollBar
and pqSelect. pqPager has class pq-pager, hence reference to pqPager inside the
grid can be obtained using $( ".pq-pager", $grid ).pqPager(). Similarly reference
to vertical and horizontal scrollbars can be obtained by $( ".pq-sb-vert",
$grid ).pqScrollBar() & $( ".pq-sb-horiz", $grid ).pqScrollBar() respectively.
If you use ParamQuery with npm then you may skip to next section.
To use ParamQuery without npm first of all include these js and css files in the header section of the web page.
Any version of jQuery can be used but jQueryUI version should be 1.11.4+
<!--jQuery dependency, any stable version of jQuery-->
<script src="https://unpkg.com/[email protected]/dist/jquery.js"></script>
<!--jQueryUI version 1.11.4 -->
<link rel="stylesheet" href="https://code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.css" />
<script src="https://code.jquery.com/ui/1.11.4/jquery-ui.min.js"></script>
<!--ParamQuery Grid css files-->
<link rel="stylesheet" href="path to pqgrid.(min/dev).css" />
<!--add pqgrid.ui.css for jQueryUI theme support-->
<link rel="stylesheet" href="path to pqgrid.ui.(min/dev).css" />
<!--ParamQuery Grid custom theme e.g., office, bootstrap, rosy, chocolate, etc (optional)-->
<link rel="stylesheet" href="path to custom theme pqgrid.css" />
<!--Include jsZip file (v2.5.0) before pqgrid js file to support xlsx and zip export (optional)-->
<script type="text/javascript" src="path to jsZip.js" ></script>
<!--ParamQuery Grid js files-->
<script type="text/javascript" src="path to pqgrid.(min/dev).js" ></script>
<!--ParamQuery Grid localization file-->
<script src="localize/pq-localize-xx.js"></script>
<!--Include pqTouch file to provide support for touch devices (optional)-->
<script type="text/javascript" src="path to pqtouch.min.js" ></script>
Sample jsfiddle
<!--jQuery dependency, any stable version of jQuery-->
<script src="https://unpkg.com/[email protected]/dist/jquery.js"></script>
<!--jQueryUI version 1.12 -->
<link href="https://unpkg.com/[email protected]/jquery-ui.css" rel="stylesheet" />
<link href="https://unpkg.com/[email protected]/jquery-ui.structure.css" rel="stylesheet" />
<link href="https://unpkg.com/[email protected]/jquery-ui.theme.css" rel="stylesheet" />
<script src="https://unpkg.com/[email protected]/jquery-ui.js"></script>
<!--ParamQuery Grid css files-->
<link rel="stylesheet" href="path to pqgrid.(min/dev).css" />
<!--add pqgrid.ui.css for jQueryUI theme support-->
<link rel="stylesheet" href="path to pqgrid.ui.(min/dev).css" />
<!--ParamQuery Grid custom theme e.g., office, bootstrap, rosy, chocolate, etc (optional)-->
<link rel="stylesheet" href="path to custom theme pqgrid.css" />
<!--Include jsZip file (v2.5.0) before pqgrid js file to support xlsx and zip export (optional)-->
<script type="text/javascript" src="path to jsZip.js" ></script>
<!--ParamQuery Grid js files-->
<script type="text/javascript" src="path to pqgrid.(min/dev).js" ></script>
<!--ParamQuery Grid localization file-->
<script src="localize/pq-localize-xx.js"></script>
<!--Include pqTouch file to provide support for touch devices (optional)-->
<script type="text/javascript" src="path to pqtouch.min.js" ></script>
Sample stackblitz
jQuery, jQueryui dependency files can either point to CDN repositories (recommended) or they can point to the files kept on server locally.
Compatibility chart between jQuery and jQueryUI
| jQuery | jQueryUI |
|---|---|
| v1.x.x, v2.x.x | v1.11.4, v1.12.x |
| v3.x.x | v1.12.x |
Free version of pqgrid can be installed though a nodejs package manager e.g, npm or yarn.
npm i pqgridf
pqgridf has following peer dependencies which can also be installed through a package manager.
jquery
jquery-ui-pack
@types/jquery
@types/jqueryui
jszip
Dependencies are kept as peer dependencies for efficiency, though you can make them private dependencies by editing package.json file inside pqgrid package if there is any version conflict with any other package. e.g, pqgrid is dependent upon version 2.5 of jsZip and if there is any other package in your project with peer dependency on jsZip any other version, then you can make jsZip a private dependency either in pqgrid or that other package.
pqgridf exports pq module which is imported into your application by
import pq from 'pqgridf';
All css files for pqgridf and dependencies are included in styles.css ( for Angular ) using @import
/* Add application styles & imports to this file! */ @import '~jquery-ui-pack/jquery-ui.css'; @import '~jquery-ui-pack/jquery-ui.structure.css'; @import '~jquery-ui-pack/jquery-ui.theme.css'; @import '~pqgridf/pqgrid.min.css'; @import '~pqgridf/pqgrid.ui.min.css'; @import '~pqgridf/themes/steelblue/pqgrid.css';
Within the jQuery ready function, initialize the grid as $( ".selector" ).pqGrid( obj ); where obj is a PlainObject passed to the pqGrid constructor function.
obj provides information about width, height, columns information, data, location and type of data, etc.
colModel and dataModel are the 2 main keys of information in the obj.
As their names indicate, the main role of dataModel is to provide data and data related information to the grid whereas colModel provides information specific to the columns i.e titles, widths, data type (used for sorting), etc. Please check API section to see the comprehensive list of options which can be used in obj, dataModel and colModel.
$(function(){
//JSON data (array of objects) can be defined locally
//or might be a response from an AJAX call from web server/service.
var data = [
{ rank: 1, company: 'Exxon Mobil', revenues: 339938.0, profits: 36130.0 },
{ rank: 2, company: 'Wal-Mart Stores', revenues: 315654.0, profits: 11231.0 },
{ rank: 3, company: 'Royal Dutch Shell', revenues: 306731.0, profits: 25311.0 },
{ rank: 4, company: 'BP', revenues: 267600.0, profits: 22341.0 },
{ rank: 5, company: 'General Motors', revenues: 192604.0, profits: -10567.0 },
{ rank: 6, company: 'Chevron', revenues: 189481.0, profits: 14099.0 },
{ rank: 7, company: 'DaimlerChrysler', revenues: 186106.3, profits: 3536.3 },
{ rank: 8, company: 'Toyota Motor', revenues: 185805.0, profits: 12119.6 },
{ rank: 9, company: 'Ford Motor', revenues: 177210.0, profits: 2024.0 },
{ rank: 10, company: 'ConocoPhillips', revenues: 166683.0, profits: 13529.0 },
{ rank: 11, company: 'General Electric', revenues: 157153.0, profits: 16353.0 },
{ rank: 12, company: 'Total', revenues: 152360.7, profits: 15250.0 },
{ rank: 13, company: 'ING Group', revenues: 138235.3, profits: 8958.9 },
{ rank: 14, company: 'Citigroup', revenues: 131045.0, profits: 24589.0 },
{ rank: 15, company: 'AXA', revenues: 129839.2, profits: 5186.5 },
{ rank: 16, company: 'Allianz', revenues: 121406.0, profits: 5442.4 },
{ rank: 17, company: 'Volkswagen', revenues: 118376.6, profits: 1391.7 },
{ rank: 18, company: 'Fortis', revenues: 112351.4, profits: 4896.3 },
{ rank: 19, company: 'Crédit Agricole', revenues: 110764.6, profits: 7434.3 },
{ rank: 20, company: 'American Intl. Group', revenues: 108905.0, profits: 10477.0 }
];
//array of columns.
var colModel = [
{
title: "Rank", //title of column.
width: 100, //initial width of column
dataType: "integer", //data type of column
dataIndx: "rank" //should match one of the keys in row data.
},
{
title: "Company",
width: 200,
dataType: "string",
dataIndx: "company"
},
{
title: "Revenues ($ millions)",
width: 150,
dataType: "float",
align: "right",
dataIndx: "revenues"
},
{
title: "Profits ($ millions)",
width: 150,
dataType: "float",
align: "right",
dataIndx: "profits"
}
];
//main object to be passed to pqGrid constructor.
var obj = {
width: 700, //width of grid
height: 400, //height of grid
colModel: colModel,
dataModel: {data: data}
};
$("#grid_json").pqGrid( obj );
});
In the body tag define the div tag/tags which act as placeholders for the grid.
<div id="grid_json"></div>
There exist a number of ways to load data in pqGrid which are based on open standards
& RESTful architecture. At a top level, these can be categorized into 2 cases depending
upon value of dataModel.location.
Case I: dataModel.location = 'local';
When dataModel.location is local, it's the responsibility of implementor to assign
data to the grid manually
i.e., $grid.pqGrid( 'option', 'dataModel.data', data); where data is in format of
array of rows. dataModel.location = 'local' doesn't necessarily mean local data.
The data can reside locally in the browser within script tags or could be fetched
from remote web server / service using synchronous or asynchronous AJAX calls. Assignment
of data to grid is usually followed by a call to
refreshDataAndView() in order to process and render data in the grid. Remote
paging, remote sorting and remote filtering are bit tedious to implement when dataModel.location
is local.
Case II: dataModel.location = 'remote';
When dataModel.location is remote, grid loads data on its own from remote location.
There is no need to manually make an AJAX call and assign data to dataModel. In
this case number of options have to be provided to pqGrid i.e., dataModel.url /
dataModel.getUrl, dataModel.getData,
dataModel.dataType,
dataModel.method etc.
When dataModel.url is provided, Grid constructs the query strings ( for GET requests
) or POST data on its own and send fields to the remote server having pq_ prefix
e.g. pq_curpage, pq_rpp, etc. In some cases when more control is required over query
strings / POST data sent to server, implementor may decide to construct these parameters
on his own by implementing dataModel.getUrl callback. In some other cases, it's
merely required to add/append rather than replace more bits of information to the
fields send by pqGrid to server. As such it's prudent to use
dataModel.postData and
dataModel.postDataOnce options. dataModel.getData callback acts as a
sieve to separate wheat from chaff. In pqGrid's context chaff is the response received
from the server and wheat is the useful and acceptable data pieces for the grid.
refreshDataAndView() is called manually or automatically by the grid whenever reload
/ refresh of data from remote server is required. Local paging, local sorting and
local filtering can be implemented even when dataModel.location is remote.
For remote paging, filtering & sorting, the grid sends the following fields of information to the server
as GET or POST requests.
By default the fields are serialized to string with JSON.stringify before sending it to the server.
Serialization can be turned off by setting stringify option of pqGrid to false.
| Type | Request variables | |
|---|---|---|
| Name | Value | |
| Paging | pq_datatype | dataModel.dataType |
| pq_curpage | pageModel.curPage |
|
| pq_rpp | pageModel.rPP |
|
| Sorting | pq_datatype | dataModel.dataType |
| pq_sort | sortModel.sorter
e.g., pq_sort: [{"dataIndx":"ShipCountry","dir":"up"}, {"dataIndx":"ContactName","dir":"down"}]
|
|
| Filtering | pq_datatype | dataModel.dataType |
| pq_filter |
Object variable having fields named "mode" and "data".
The value of "mode" is taken from filterModel.mode and "data" is an array of objects constructed from individual column.filter
e.g.,
pq_filter: { "mode": "AND", "data": [{"dataIndx":"ShipCountry","value":"fr","condition":"begin"},
{"dataIndx":"ContactName","value":"pa","condition":"begin"}]} |
|
Any jQueryUI theme can be used by replacing base with the name of desired theme in the above lists of jQuery dependencies. The following is a list of ready to use 24 jQueryUI themes:
<link rel="stylesheet"
href="https://code.jquery.com/ui/1.11.4/themes/remdond/jquery-ui.css" />
instead of
<link rel="stylesheet"
href="https://code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.css" />
To create your own custom theme or even to customize any of the above themes, visit
here http://jqueryui.com/themeroller/
Style alternate rows in jQueryUI themes
There is lack of appropriate class to style alternate rows in jQueryUI themes. However
custom color/style to alternate rows can be added with the below rule
.pq-grid-oddRow > td{
/* add your styles here */
}
Using jQueryUI and custom icons
Icons are used at many places in the grid e.g. in toolbar, pager, grouping icons,
etc. ParamQuery Grid is jQuery theme ready and hence relies upon jQueryUI icons.
Reference to a list of all jQuery icons can be obtained from
http://jqueryui.com/themeroller/ and icon class names can be gathered by
hovering mouse over the icons. The icon class names can be used in API of the grid.
If jQueryui icons don't satisfy your taste or need, you can create your own icons
of dimensions 16px x 16px, use them in CSS classes and assign those class names
to applicable parameters in API of the grid.
Significance of dataModel.data
The grid data is stored in dataModel.data in the form of an array of rows. When we use local paging, dataModel.data contains all the data of all the pages. But when we use remote paging, dataModel.data contains only the data on current page. In the latter case, dataModel.data is refreshed every time we move from page to page or we hit refresh button in the pager.
These are some of the variable names used in API and examples which are named so by convention.
$grid is the name of jQuery object that refers to grid container div.
var $grid = $( ".selector" ); // e.g., $( "#grid_json" );
//it can also be obtained from evt.target inside event callback functions.
var $grid = $( event.target ).closest( '.pq-grid' );
//it can also be obtained from grid variable.
var $grid = grid.widget();
All pqgrid methods can be called with this variable as
$grid.pqGrid( 'method_name', parameters );
grid is the name of javascript object that refers to a live instance of pqGrid.
var grid = pq.grid( "#grid_json", options ); //constructor (>= v3.2.0)
//it can also be obtained from $grid variable as.
var grid = $grid.pqGrid('instance'); //jQueryUI >= v1.11
var grid = $grid.pqGrid('getInstance').grid;
//can also be obtained directly from context of event callback functions.
var grid = this;
All pqgrid methods can be called with this variable as
grid.method_name( parameters );
rowIndx is zero based index of a row relative to page 1, row 1. So first row has
rowIndx = 0, 2nd row has rowIndx = 1 and so on. It's easy to get reference to a
row data if rowIndx is known. For example if we need a reference to 50th row, we
can simply get it as var rowData = dataModel.data[49]; where 49 is rowIndx of 50th
row. It would work the same whether we use local paging, remote paging or no paging
at all.
rowIndxPage is zero based index of a row relative to the current page. There are
number of instances when rowIndxPage is easier to use as compared to rowIndx e.g., while inserting a new row
on the current page. Also when we use remote paging, rowIndxPage makes better sense as dataModel.data
contains data on current page only.
rowData signifies data for a row, it is extracted from the grid data by dataModel.data[ indx ]
where indx is substituted by rowIndx in case of local data, while rowIndxPage in case of remote paging.
dataIndx is the name of field/key in JSON data or numeric index of field in array
data. A field or cell value can be obtained from row data by rowData[ dataIndx ].
colIndx is zero based numeric index of column in colModel array. column and hence its properties
can be accessed from colModel as colModel[ colIndx ]. It also signifies the physical order of a column,
so column with colIndx of 0 is at the leftmost corner of the grid and so on.
There are 2 different syntactic ways to call pq methods having same end result:
$( ".selector" ).widgetName( 'method_name', parameters );
e.g., $grid.pqGrid( 'refreshRow', { rowIndx: 2} ) where $grid is the jQuery object wrapped on grid container DOM element.
This one is safer ( in the sense it prevents accidental or intentional calling of pqGrid private methods )
but it's verbose, bit slower and
garbles up the call stack with intermediate calls to jQueryUI framework.
This way of method calling is used for jQuery only.
instance.method_name( parameters ) e.g.,
grid.refreshRow( { rowIndx: 2 } ) where grid is a live instance of pqGrid.
This one is faster and concise.
This way of method calling is used for Angular, jQuery, React or Vue.
PQ has a powerful event system to inform about interesting points in the lifecycle of widget.
Event listeners are implemented by writing a callback function that is called by the widget when the specified event occurs.
Every event listener function has 2 arguments: event and ui where
event is an object that provides information about the event
in terms of type of event, target, currentTarget, coordinates (pageX, pageY, etc) of the event in case of keyboard or mouse event,
ui is an object that provides information about grid specific properties, e.g., rowIndx, rowData, colIndx, dataIndx, etc.There are 3 ways to bind pq events.
pq.grid( selector, {
beforeSort: function( evt, ui ){
//code here
},
//other options.
});
or set options after initialization i.e.,
grid.option( "beforeSort", function( evt, ui ){
//code here
});
This one is fast and easy way to listen to events but has limitation of one callback per event and can't listen to bubbled events.
grid.on( "beforeSort", function( evt, ui ){
//code here.
});
Multiple event listeners can be implemented and multiple events can be specified in a single call by specifying
space separated list of events. one and off are also supported for instance listeners.
This is also easy and quick way of binding event listeners but these can't be used to listen to bubbled events.
If more than one listener is implemented for a single event, they are called in the same order as they are added.
$( ".selector" ).on( "pqGrid:beforeSort", function( evt, ui ){
//code here.
});
It's disabled by default for performance reasons. It can be turned on by setting trigger option to true.
DOM events and bubbling ( applicable to jQuery/ plain js only ):
By default the PQ events are not emitted to DOM elements since v3.2.0 which if required can be
turned on by specifying trigger option in the widget to true.
The events also don't bubble by default since v3.2.0.
Consider case of nested grids where event listener is bound to outer grid for some event;
when same event is emitted by inner grid event bubbling leads
to invocation of event listener of the outer grid. This can lead to issues unless we are careful to check the currentTarget of event.
Again if required, bubbling can be turned on by setting option bubble to true.
instance listeners > DOM event listeners > callback option.
It's possible to callstopImmediatePropagation() on the event object
to stop further handling of the event by other pending listeners. It's also possible to stop further propagation to parent handlers
or bubbling of event by returning false or calling stopPropagation()
on the event object.
Context of events: The context ( i.e., this variable ) is instance of the grid inside callback options ( 1st way ) and instance listeners ( 2nd way ),
while it's a reference to DOM element of the widget inside DOM event listeners ( 3rd way ).
Summary of differences between versions:
| Feature | version < v3.2.0 | version >= v3.2.0 |
|---|---|---|
| Instance listeners | Not available. | Available |
| Event type | widgetName + "event name" all in lowercase e.g., pqgridbeforesort |
widgetName+":event name" e.g., pqGrid:beforeSort |
Context i.e., this of callback options and instance listeners |
DOM element of the widget | instance of the widget in instance listeners while DOM element of the widget in DOM event listeners |
| Bubbling and emission of events on DOM nodes | true by default | false by default |
How to refresh the data or view of grid
pqGrid tries to refresh view on its own prior to version 2.0.2 in most cases when dataModel properties are changed. This behaviour is sometimes undesirable e.g. consecutive calls to API changing dataModel properties may lead to undesirable refreshes and reloads of data which is not good for performance. This has changed starting from 2.0.2 whereby the data or view of grid can be refreshed in a more controlled manner. pqGrid can be refreshed in various ways depending upon what or which part of the grid needs to be refreshed. Please see the below comparison table to know which method to use:
| refresh | refreshView | refreshDataAndView | |
|---|---|---|---|
| Refresh Column Header | Yes | Yes | Yes |
| Refresh view for updated rows | Yes | Yes | Yes |
| Refresh view for added rows | No | Yes | Yes |
| Refresh view for removed rows | No | Yes | Yes |
| Reload data from server (location = 'remote') | No | No | Yes |
| Reload data from dataModel.data (location = 'local') | - | Yes | Yes |
| Refresh local paging | No | Yes | Yes |
| Refresh local sorting | No | No | Yes |
| Refresh local filtering | No | No | Yes |
| Refresh row grouping | No | Yes | Yes |
If you are updating lot of rows let's say hundreds or thousands of them with API methods such as updateRow, addClass, removeClass, attr, removeAttr,
the grid is bound to get slow because the view is refreshed by these methods by default and DOM updates are inherently slow.
In order to prevent refresh of view with each method call, refresh parameter to these methods can be passed as false and
one final consolidated refresh can be done with a call to refresh method in the end.
Same logic can be applied to other methods in the API which cause a view refresh e.g., addRow, deleteRow.
These methods also accept refresh as parameter which can be passed as false.
But instead of refresh, these require refreshView in the end because these methods change the number of rows.
There are few callbacks such as column.render & rowInit
in which view refresh is not required and is unnecessary waste of resources.
These callbacks are invoked at a time when view of the grid is being prepared and refresh of the view is anyway due after these callbacks.
So for performance sake it's prudent to pass refresh: false as parameters if any of these methods
addClass, removeClass, attr, removeAttr
are called from these callbacks.
How to change locale of a grid / grids
$.extend($.paramquery.pqGrid.prototype.options, $.paramquery.pqGrid.regional[locale]);
$.extend($.paramquery.pqPager.prototype.options, $.paramquery.pqPager.regional[locale]);
where locale is to be substituted with the locale name.
$.extend($.paramquery.pqGrid.prototype.options, $.paramquery.pqGrid.regional['ja']);
$.extend($.paramquery.pqPager.prototype.options, $.paramquery.pqPager.regional['ja']);
$grid.pqGrid("option", $.paramquery.pqGrid.regional[locale]);
$grid.find(".pq-pager").pqPager("option", $.paramquery.pqPager.regional[locale]);
$grid.pqGrid({ strNoRows : 'No Rows found.' });
or
$grid.pqGrid( 'option', { strNoRows : 'No Rows found.' });
Further Reading
How to use jQuery UI widgets