tgrid : lightweight jQuery datagrid plugin

• Home
• News
• Documentation
• Demos

When You want to use tgrid plugin, first You need to construct the function which inherits the jsModel function / object. Here's how

function coreSettings(){this.prefix = "url-of-the-script-which-lists-the-records-or-fetches-them";}var core = new coreSettings();
function myModel(id)
{
    this.id = id;
    this.__defined_cols = ["login","first_name","last_name"];
}

myModel.prototype = new jsModel();
var mm = new myModel("mm");

$(document).ready(function(){
    $("#mm_table").tgrid({object: mm});
    mm.rf();    
});

You also need to insert all the required dependencies:

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3/jquery.min.js"></script>
<script type="text/javascript" src="jquery.tools.js"></script>
<script type="text/javascript" src="jquery.tgrid.js"></script>

That doesn't seem like a pain, ain't it? ;) Sorting functionality was inherited from tablesorter plugin so You can sort using a click and sort through multiple columns using the Schift key. However my plugin implements the sorting a bit different. You can obviously see __defined_cols parameter. Well, this is responsible for both displaying the columns as well sorting them. When You click on some column, an AJAX request is executed (using POST method) and there will be a POST key called "order_by" which will have the combination of columns [for example "order_by" => "first_name asc, last_name desc"].

Now, the requirements a.k.a. why that stupid fragment of code just doesn't work?

For starters, the plugin needs to know where to search the data for ;) You set this in jsModel class. Of course the second solution is to modify the tgrid class so that it would input this functionality as one of parameters, however there are a couple of no-no's for me. The main ones are:

1. I didn't wanted to make a constructor which took a whole big dictionary of parameters
2. The tgrid plugin is a part of my framework, so what i normally do is input the name of the class inside the framework and everything works out of the box :) it's just easier for me.

Ok, enough of this, let us see the default definition of "create_fetch_params" function. This is the one which gets the list of the records from the server:

if (this.__other_params && typeof(this.__other_params) == "function") 
{
	return {url: core.prefix, params: $.extend(this.__other_params(),{"page":this.page,"per_page":this.per_page, "filter": $(this.filter).val()})};
}
return {url: core.prefix, params: {"page":this.page,"per_page":this.per_page,"filter": $(this.filter).val()}};	

OK, so what that basically means is that You can define a __other_params function inside Your inherited object and put all Your desired parameters into it. For example:

function myModel(id)
{
	this.id = id;
	//blah blah blah
	this.__other_params = function() {
		return {"these":"are","my":"post","params"};
	}
}

What this also means is that the model sends "page" and "per_page" fields so that You could use it in SQL query. Again - in my framework, the whole SQL Query get's created automatically, but You need to do it manually, unless You have some way of automating it :) Further configuration

You can add two other neat things: edit href and check box to each record. In order to do this You need to extend Your model just like that:

function myModel(id)
{
	this.id = id;
	//blah blah blah
	this.colName = "id";
	this.editHref = function(r): { return "javascript:mm.edytuj("+r[this.colName]+");"; };
	this.checkBoxName = "record";
}	

Please note few facts:

• each record in record list must of course include a field named exactly like "colName" value - in this simple example: "id".
• the editHref is an actual href ;) so there's no need to input <a href= into it.
• checkBoxName will be extended with the array suffix so record will become record[] for each record.

The plugin assumes, that the output from the server will contain structure like that: (JSON-encoded of course)

{"out":[array of records],"count":number-of-records,"config":name of the object - mm in this example"}

The "config" key is crutial. You see, i had a bit of a problem when using several grids on the same page and tried to refresh them one after another - it just wasn't working. So, the plugin sends the variable name as POST parameter and the server is supposed to echo it back. It's kind of stupid and ugly solution, but as i said - the plugin is a "still in developement" thing.

Displaying the data.

You can display any column from the array __defined_cols. The default behaviour is of course - displaying the content as a text. However You can override the default behaviour by creating "renderers" dictionary inside the model. Here's how:

function myModel(id)
{
	this.id = id;
	//blah blah blah
	this.renderers = {
		"login": function(x, r){ return "Hi, my name is "+r["login"]; }
	}
}

As You can see, the function takes two arguments. The first one is the value of the column You are displaying. The second one is the whole record.

Filtering

Adding filtering support is very easy - You just need to add an input text field in Your html code which would have a name "mm_filter" where mm would be Your jsModel object variable. Then, You need to call enableFiltering() method after You initialize Your object (this is crutial because of filthy internet explorer of course... no comments :/). Please refer to the demos page to see the basic example.

CReating, Updating and Deleting the data [CRUD]

The jsModel class can handle filling the form with data retrieved from the server. You can then easily submit the form via AJAX or do anything You want with it ;). In the previous example the editHref parameter was pointing to the edytuj function of the jsModel class. You need to see if the parameters fit Your needs. Let's now see the defaults (please note, that the default url is also core.prefix):

params = {"config":this.id, id":id}	

Well, the output must have JSON-encoded array with the main field "rekord" (no, it's not record. I'm from poland and part of the code was written using english naming, part in polish ;) i don't have much time to fix it right now.). You also need to prepare the form and the field names in the form must correspond to the ones returned by the backend script. Please refer to the "CRUD demo" example.