PJgrid©
Interactive web datagrid
Contents
Reference Guide
Overview and features
PJgrid is an opensource js/Ajax library allowing to implement into a web application the look and feel of a desktop datagrid.

PJgrid has a rare combination of features:
  • lightweight (60kB) and standard compliance (strict.dtd) for maximum compatibility
  • full client-based: data handling is offline, only retrieval and modification require connection
  • real, whole length scrolling, without any pagination, also with very very big tables
  • interaction with system clipboard, both copy and paste
  • full customizable heading and row appearance
  • extremely simple use, come with wide documentation, including client and server side examples
  • free for personal and commercial use

The power of PJgrid resides in three technical choices:

1 - Data retrieval with Ajax
The unparsed ASCII flow of an Ajax response (responseText) is the fastest way for a browser to get online data from a server. This applies for every browser up to some tens of MBs. Splitting larger flows into 10-20 MBs transactions allows to mantain the best speed almost everytime.

2 - Data storage with javascript
The best way to store data (tens of MBs) in one html page is a monodimensional js array. HTML elements are two heavy, because of DOM structure. HTML 5 local database has to come and will be limited to few MBs.
PJgrid simply creates the illusion of scrolling by:
  • creating a fake scrollbar based on rows number
  • while scrolling, reading rows as strings from the array and splitting columns with a separator
  • putting data into a short fix html table
The RAM consumption of the browser is comparable to that of other desktop grids.

3 - Standard and simple HTML
The use of strict HTML DTD is the only way to obtain the same layout, exact up to 1 pixel, on every browser. We don't use any framework (like JQuery) to stay as light and indipendent as possible. Some additional js library for desktop-like effects (drag&drop and resize) is directly included into the library.

Features list:

Performance Data volume: 20MB per single Ajax transaction, total volume limited by client RAM
Rows number: 500k
Columns number: 2k
Data functions Displaying: ASCII values
Scrolling: full and live scrolling of all rows
Sorting: on single and multiple columns
Filtering: on single and multiple columns, using math operands and regexp
Modification: update, insert, delete; automatic or forced commit
System interaction Clipboard: copy and paste from and to rows selection
Interface Standard grid: resizable columns
Customizable grid: heading and rows, with html template
Selection: single and multiple rows (contiguous or not)
Programming Library: js objects exposing properties, methods and events Graphic: HTML templates
Interaction: js events in template objects; grid object exposing current row data
Events: for loading, scrolling and modification
Compatibility Prerequisites: HTML 4.01 (strict.dtd), javascript 1.3, CSS2
Browser support: IE7+, FF3.6+, Chrome3+, Safari3+, Opera10+
License
PJgrid is released under the GNU Lesser General Public License. This means that:
  • you can freely use this software for every personal or commercial purpose
  • you can link this library into every kind of software, free or not free
  • you can modify the code, since you remain under LGPL license
  • if you distribute this software you MUST send a copy of the LGPL license and leave in the scripts the copyright note:
    =============================================================================
    PJgrid - Copyright 2012 ALPJ srl - www.alpj.com/PJgrid
    =============================================================================
    
     PJgrid is free software: you can redistribute it and/or modify
     it under the terms of the GNU Lesser General Public License as published by
     the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.
    
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
    
     You should have received a copy of the GNU Lesser General Public License
     along with this program.  If not, see http://www.gnu.org/licenses/.
    
    =============================================================================
    
Installing
PJgrid is a set of four javascript files, to be included into an html page. The inclusion requires the following steps:
  1. html page: MUST use a strict mode (<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">)
  2. inclusion of pjAjax.js (in HEAD or BODY)
  3. inclusion of pjDocument.js (in HEAD or BODY)
  4. inclusion of pjRecordSet.js (in HEAD or BODY)
  5. inclusion of pjGrid.js (in HEAD or BODY)
  6. your code for instanciating pjRecordSet and pjGrid objects
  7. a place into the html where to put the grid
Example:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
...
  <script src="pjAjax.js"></script>
  <script src="pjDocument.js"></script>
  <script src="pjRecordset.js"></script>
  <script src="pjGrid.js"></script>
...
  <script>
    var myRecordSet=new pjRecordSet;
    ...
    var myGrid=new pjGrid();
    ...
  </script>

The use of strict mode could seem a little rigid, but it's fundamental for a correct rendering of the grid on every browser. If necessary, you can enclose the grid into an iframe and limit there the strict mode.
WARNING: pjDocument.js declares the code for onmousemove and onmousedown events of body, overwriting previous declarations. If required, insert your event code at the end of pjDocument.js
How the grid works
PjGrid id built over 4 elements:
  1. the html grid
    The secret of pjGrid is to draw a fix grid and let data flow into it. This grid uses two templates: the first one for the heading, the second one for every row in the grid. The first action (the "draw" method) lets the object gain its space in the page, put the heading at the beginning and a correct number of rows in the center. These html elements wont be modified: the data flow will only change the content of cells. The scrollbar on the right is not really connected to the visible grid. The bar has the width of the cursor itself and contains an hidden element with the height that the whole grid should have (template height * numer of rows).

  2. the recordset
    All data are loaded into a js object based over an array: the pjRecordSet object. When a pjRecordSet object is first created and then attached to a pjGrid one, every action is directly handled by the grid: loading, filtering, sorting and modifications.

  3. the ajax interface
    The pjRecordset can manage data statically included into the script (in our trivial examples) or dynamically loaded from a server (in reality). The ajax interface of the recordset is used directy by the grid for loading data and saving modifications in connection with a server-side script and a database.

  4. the document interactivity
    PjGrid comes with two desktop-like features, provided by the pjDocument script: popups with screen freeze and resize of elements by dragging,

So this is the complete commands sequence to instanciate a grid:
<element id='myDiv' ... point where the grid will be drawed 

<script ... library scripts inclusion

<script>
  var myRecordSet=new pjRecordSet;
  myRecordSet.fields=['...',...];
  myRecordSet.ajaxMethod='...';
  myRecordSet.ajaxAddress="..."; 
                          
  var myGrid=new pjGrid();
  myGrid.template='...';
  myGrid.headerTemplate='...';
  myGrid.attachRecordSet(myRecordSet);
  myGrid.draw(document.getElementById('myDiv'));
  myGrid.load();  
Example 1: loading data into the grid
Example 2: customizing heading and rows
Example 3: working with external data
Example 4: adding events to the grid
Complete objects reference
pjRecordSet ajaxAddress The web address of the server script called by ajax
ajaxMethod The method (POST or GET) for the server script called by ajax
load() Activates the dialog with the ajax source. The action to perform is read by the 'action' attribute of the object. Returned values: null, because the result is retuned asynchronously by ajax.


pjGrid ajaxAddress The web address of the server script called by ajax
ajaxMethod The method (POST or GET) for the server script called by ajax
load() Activates the dialog with the ajax source. The action to perform is read by the 'action' attribute of the object. Returned values: null, because the result is retuned asynchronously by ajax.


pjDocument ajaxAddress The web address of the server script called by ajax
ajaxMethod The method (POST or GET) for the server script called by ajax
load() Activates the dialog with the ajax source. The action to perform is read by the 'action' attribute of the object. Returned values: null, because the result is retuned asynchronously by ajax.


pjAjax action(ajax) The callback function of the ajax call, to be overloaded. Passing the ajax object itself as parameter allow to apply the reflection tecnique.
address The web address of the server script called.
asynch Asynchronous/synchronous property of the base ajax object. Default: true.
parameters Custom parameters for the ajax call.
type The method (POST or GET) for the server script.