JSDataGrid :: F.A.Q & API :: just another JavaScript DataGrid

F.A.Q.

What is JSDataGrid ?

JSDataGrid is a component based on 7 different classes that would replace magic Flash 7 or greater DataGrid component.

Why JSDataGrid ?

I was looking for a complete, free and customizable DataGrid but I didn't found it. RICO grid, for example, should be a great and free alternative to this one but it's not what I was looking for.

Could I change colors or styles ?

JSDataGrid is CSS based, than you can change every CSS based part.

Have I to update JSDataGrid for each portion of data ?

I have tested successfull JSDataGrid with 10.000 objects and I think there's no problem to manage a large amount of data. However you should use some tricks to manage a really big dataProvider.

Why scroll bar doesn't work in FireFox ?

While I've decieded to create a different DataGrid, I've not used an iframe. The cool thing of an iframe is that you can scroll easyly data inside the fake grid, the bad thing of an iframe is that you cannot use a lot of items or your datagrid will lose performance drammatically. Imagine thousands of items, your browser will be stressed from a really big table and scroll them will be a big work for a lot of CPUs. So I've created an alternative way, in this grid, then there isn't any iframe inside them. I've not yet found a crossbrowser fast way to implement scroll on FireFox too, but with IE and Opera, scrollbar will work good (with Opera you need to click at least one time in the scroll). [ top menu ]

API :: DataGrid Methods

constructor

Any parameter to construct a JSGridObject.

var myDataGrid = new JSDataGrid();

addColumn

You can add a column with a string or with a DataGridColumn variable. The name used in column should be the same of the name of the item to show. If you add, for example, only "name" column, JSDataGrid will show only this value for each dataProvider object. Remember that in every case when you will get selected item, this will return complete, then with age value too. JSDataGrid can contains really complex object, only you will choose what show or not.

var dataProvider = new Array();
dataProvider.push({name:"Andrea Giammarchi", age:27, site:"http://www.devpro.it/"});
var myDataGrid = new JSDataGrid();
myDataGrid.addColumn("name");
var age = new DataGridColumn("age");
myDataGrid.addColumn(age);
myDataGrid.dataProvider = dataProvider;
myDataGrid.show("grid-space");

addColumnAt

This method is the same of addColumn but you need to specify the index of the column. Usually is better use addColumn but if you want modify a column, for example, you can overwrite with this method.

// addColumn example code ...
myDataGrid.addColumn(1, "site");
// age will not be displayed, just name and site
myDataGrid.addColumn(2, age);
// age will be displayed after site column

addEventListener

JSDataGrid has some usefull events that should be used by developers. If you add one or more events listeners you will recieve informations for every called event.

var evtlistener = new Object();
evtlistener.click = function(obj) {
	var choosedItem = obj.target.getItemAt(obj.target.selectedIndex);
	alert(choosedItem);
};

Events list

change , called when a user select another selectable item
click , called when a user click in an item
cellEdit , called when an editable cell changes its valu
cellFocusIn , called when a user start to edit an editable cell of an editable column
cellFocusOut , called when an editable cell lose its focus
cellPress , called when a user click inside a cell
columnStretch , called when user modify the width of a resizable column
headerRelease , called when a user sort a sortable column by its header
itemRollOut , called when a user move the mouse out from an item
itemRollOver , called when a user move the mouse over an item

Each events returns on listenr dedicated function an object that will has two proprieties, type and target. The target will be the DataGrid (you can use one listener with more thn one JSDataGrid) with its proprieties and the type is the event name. [ top menu ]

addItem

You can assign directly a dataProvider array to your DataGrid but you can add runtime an item too. JSDataGrid doesn't loop over itself to know if someone has changed its dataProvider but if you want to add another item, before or after you've drow the DataGrid, you can use this method.

// ... other example code
myDataGrid.show("grid-space");
mybtn.onclick = function(){
	myDataGrid.addItem(
		{name:"Daniele", age:25, site:"http://www.phpsoft.it/"}
	)
};

addItemAt

While addItem add an item at the end of dataProvider, this method add or replace an item in specified index.

myDataGrid.addItemAt(0,{name:"Daniele", age:25, site:"http://www.phpsoft.it/"});
// will replace, for example, item with my name and my age at 0 index

draw

This method will create JSDataGrid in a dedicated div or element with a unique id. Remember that if you want to set some grig proprieties you should do before to call this method.

<div id="grid-space"></div>
<script>myDataGrid.draw("grid-space");</script>

editField

This method accepts index, columnName and new data for field to edit.

// ... other example code
myDataGrid.show("grid-space");
mybtn.onclick = function(){
	myDataGrid.editField(0, "age", 28);
	// will change Andrea  age in first item
};

getColumnAt

This method will return the DataGridColumn object.

alert(myDataGrid.getColumnAt(2).columnName); // site

getColumnIndex

This method will return the index of the column with that name. For example if you need to get a column but you don't know if it's yet on second position, you should use this method to get that column.

alert(myDataGrid.getColumnIndex("site")); // 2 , because site is the third column

getDataProvider

[NEW on V0.2] This method will return the grid dataprovider.

var dataProvider = new Array();
dataProvider.push({name:"Andrea Giammarchi", age:27, site:"http://www.devpro.it/"});
dataProvider.push({name:"Daniele", age:25, site:"http://www.phpsoft.it/"});
var myDataGrid = new JSDataGrid();
myDataGrid.dataProvider = dataProvider;
myDataGrid.show("grid-space");
mybtn.onclick = function(){
	dataProvider = myDataGrid.getDataProvider();
};

getItemAt

Returns an item on index position.

mybtn.onclick = function(){
	alert(myDataGrid.getItemAt(0).name); // Andrea Giammarchi
};

getRowHeight

If you set a fixed height for a JSDataGrid object, this method will returns its value.

myDataGrid.setRowHeight(50);
alert(myDataGrid.getRowHeight()); // 50

getSize

If you set a size for a JSDataGrid object, this method will returns its value as an array with width on index 0 and height on index 1.

myDataGrid.setSize(500, 300);
alert(myDataGrid.getSize()); // [500,300]

removeAllColumns

This method removes every column from a JSDataGrid object. This method doesn't modify internal dataprovider.

myDataGrid.removeAllColumns();
myDataGrid.addColumn("name"); // only name will be displayed

removeAllItems

This method will remove dataProvider and all its items from a JSDataGrid object.

myDataGrid.removeAllItems();

removeColumnAt

If you need to remove a column from your DataGrid, just use this method with column index.

myDataGrid.removeColumnAt(myDataGrid.getColumnIndex("age"));
// only name and site column will be displayed

removeItem

This method will remove last item displayed on datagrid.

var dataProvider = new Array();
dataProvider.push({name:"Andrea Giammarchi", age:27, site:"http://www.devpro.it/"});
dataProvider.push({name:"Daniele", age:25, site:"http://www.phpsoft.it/"});
var myDataGrid = new JSDataGrid();
myDataGrid.dataProvider = dataProvider;
myDataGrid.show("grid-space");
myDataGrid.removeItem(); // will remain only first item

removeItemAt

As removeItem method, with this one you can remove every item you want, by index value.

var dataProvider = new Array();
dataProvider.push({name:"Andrea Giammarchi", age:27, site:"http://www.devpro.it/"});
dataProvider.push({name:"Daniele", age:25, site:"http://www.phpsoft.it/"});
var myDataGrid = new JSDataGrid();
myDataGrid.dataProvider = dataProvider;
myDataGrid.show("grid-space");
myDataGrid.removeItemAt(0); // will remain only second item, as first

replaceItemAt

This method will replace choosed item with another.

var dataProvider = new Array();
dataProvider.push({name:"Andrea Giammarchi", age:27, site:"http://www.devpro.it/"});
dataProvider.push({name:"Daniele", age:25, site:"http://www.phpsoft.it/"});
var myDataGrid = new JSDataGrid();
myDataGrid.dataProvider = dataProvider;
myDataGrid.show("grid-space");
myDataGrid.replaceItemAt(1,{name:"piero.mac", age:undefined, site:""});

scrollTo

With this method, if scrollbar is visible, JSDataGrid object will scroll to choosed item.

mybtn.onclick = function(){
	myDataGrid.scrollTo(
		Math.floor(
			myDataGrid.dataProvider.length/2
		)
	);
	// will scroll to the middle of the DataGrid
};

setRowHeight

This method will set prefixed height for each row. By default datagrid try to generate automatically its rows height but if you need a different height you should use this method before to draw the grid. Remember that grid try to respect default or given size (setSize) than you should check manually the result of this method with all common browser to be sure that grid is displayed correctly.

myDataGrid.setRowHeight(50); // 50 pixel each row of each item
myDataGrid.show("grid-space");

setSize

With this method you can set the size of the datagrid. Use it before draw it. Default size value is 500 pixels for the width and 300 pixels for the height.

myDataGrid.setSize(400, 180);
myDataGrid.show("grid-space");

sortItems

By default if you choose to show JSDataGrid headers theese will sort by integer or string value its dataProvider. If you need to sort differently a column you should pass a dedicated function to this method.

function compareFunc(a,b) {
	var result = 0;
	if(a + b < b)
		result = -1;
	else if(a + b > b)
		result = 1;
	return result;
};
myDataGrid.sortItems(compareFunc);

sortItemsBy

If JSDataGrid object has sortableColumns and choosed column is sortable too, you can use this method to sort that column with specified order ("ASC" or "DESC").

myDataGrid.sortItemsBy("age", "ASC");

API :: DataGrid Proprieties

columnIndex

Whe a user click on a selectable header, this value will contains its index. [ top menu ]

dataProvider

This is the items list (inside an array) used by JSDataGrid object. [ top menu ]

editable

If you need that some column should be editable in-place, you need to set this value true. It's false by default. [ top menu ]

focusedCell

When an editable cell get focus, this parameter will contain its two coordinates.

columnIndex , the index of the column of the cell
itemIndex , the index of the item of that cell

You can use this usefull parameter to modify other item values too when a cell has been edited. [ top menu ]

htmlText

If you need to write html inside your cells, you need to enable this value switching to true. It's false by default. [ top menu ]

index

This will be last selected column index. [ top menu ]

itemIndex

This will be last selected item index. [ top menu ]

multipleSelection

If you need to manage more than one item each time you should switch this variable to true. It's false by default. [ top menu ]

resizableColumns

If you want that a user cannot resize some resizable columns you should swith this value to false. It's true by default. [ top menu ]

selectable

If you don't need selection for each item, single or multiple, you should switch this value to off. It's true by default. [ top menu ]

selectedIndex

This parameter will contains last selected item (it's index). [ top menu ]

selectedIndices

This parameter is an array and will contains all selected indicies for each selected item. If multipleSelection is not true, this array will contains only last selected index. [ top menu ]

selectedItem

This parameter will contains last selected item. [ top menu ]

selectedItems

This parameter is an array and will contains all selected items. If multipleSelection is not true, this array will contains only last selected item. [ top menu ]

showHeaders

This boolean parameter will allow developers to show or to don't show DataGrid headers. It's true by default, switch to false if you don't want to show headers. [ top menu ]

sortableColumns

Every column is sortable by default then if you don't specify each column as not sortable you should switch this parameter to false, then every column will automatically be unsortable.

API :: DataGridColumn Methods

constructor

A string that rappresents the columnName used to display items inside a JSDataGrid object.

var myColumn = new DataGridColumn("name");

API :: DataGridColumn Proprieties

columnName

This is the name used to display items parameters inside a grid. [ top menu ]

editable

This value allows user to edit items in place. It's false by default. [ top menu ]

headerText

This is the text displayed on headers, it's the same of columnName by default but you can change before to add column. [ top menu ]

resizable

This parameter allows user to resize this column if JSDataGrid object is resizable. [ top menu ]

sortable

This parameter allows developers to sort this column if JSDataGrid object is sortable. [ top menu ]

sortOnHeaderRelease

This parameter allows user to sort header click this column if JSDataGrid object is sortable. [ top menu ]

width

This parameter is the width in pixels of this column, 0 by default (genereted automatically by JSDataGrid render class). [ top menu ]