Docs


Sigma Grid Document

Preface

Written in pure javascript, Sigma Grid is an Ajax data grid for displaying and inline editing data in a scrollable and sortable table. With MVC architecture, plenty of attributes and powerful script API, this grid control brings developer more flexibilities and less workload.

Features

  • Lockable header and column
    This feature enable you to keep some columns and/or header always visible in spite of user scrolling grid. Similar to the window freeze panes option in MS Excel.
  • Nested headers
    One of the new features is the ability to have unlimited levels of nested headers. This allows for presentation of adjacent columns related to each other.
  • OGNL format supported
    smooth objects converting between presentation layer and logic layer. hot!
  • Pure javascript codes
    Seamless Integration with any server side solution, such as j2ee, .net, PHP, perl.
  • Cross browers
    IE 5.x+ \ Mozilla 1.4+ supported.
  • Sorting & various data types
    End user can sort records by clicking on the header of a column. Developer can specify sorting way for various types including string�number�boolean�link�select�percent. Developer may define a new data type and a new way to sort.
  • Slice rendering
    You may load thousands rows of data into grid in one time.Slice rendering could help you increase user experience. When this mode activated, everytime the vertical scroll bar is dragged, SigmaGrid will detemine which rows are visible and paint them out.
  • Alignment
    Developer can specify different aligments on different columns.
    Math formulas for cells
    Developer can specify some cells to be a formula instead of a value. What is more, whether a cell is editable could depend on a boolean formula.
  • Resizable Columns
    Columns width could be changed by end user draging columns header.
  • Inline cell editing
    Inline cell editing just as you would in MS Excel. Navigate with the tab or enter key to move between cells . End user also can remove / add / append rows.
  • Remote data manipulation
    Client Side queries can be performed to change the data set. Useful to change the data on the client and submit changes to server.
  • MVC architecture
    Sigma Grid architecture adopts typical MVC (Model-View-Controller) pattern(see following chart). The cell presentation is separate from its internal value.
  • Single selection & multi selection
    Sigma grid has the ability to select non-contiguous rows. This allows for more robust manipulation of records in the Grid.
  • User defined editor & renderer
    Extensibility enable you to replace built-in cell editor with custom external component, present cell data as your customers' wish.
  • Event handlers & user API
    Plentiful attibutes and event handlers give you more flexibility without coding too much.
  • Paging
    This feature enable developer display data page by page. Data will not be retrieved from server side until end user come to the page it is at. Developer can control how many rows are displayed at one time.
  • Online Printing
    Online printing technology, to make it easy to build a traditional-look printable reports without anything installed. hot!
  • Aggregate and aggregate by group
    Build-in functions(min, max, avg, sum, count) helps developer calculate aggregate on client side. What is more, Sigma grid can calculate aggregate group by group without any request to server side.
  • CSS Based Themes
    Sigma grid appearance is controled via a stand-alone CSS(style sheet). Developer can change grid skin by defining themes in different CSS files.
  • Linkable Grids Allow you to create multiple grid instances on one web page. With events and JavaScript API, Developers can implement one-to-many or many-to-many relationships (master-detail) at ease .
  • Various load sources
    Developers can export data to / load data from variouse sources, including in JSON, XML, CSV (Comma Separated Values) format, to support further editing within spreadsheet or any other applications.

Get started

Five steps to make a Sigm grid instance. Click here to see result. Here we go. 

STEP 1. Include Sigma library script and style sheet in your page.

STEP 2. Declare columns array. Each element descibes appearance and behavior of one column in the grid.

	var columns = [		
	    {name:"operating",caption:"operating",
width:200,mode:"string",sortable:true,readonly:true},	
             {name:"budget",caption:"budget",
width:60,mode:"number",format:"#.0",sortable:true,readonly:true},	
             {name:"actual",caption:"actual",
width:60,mode:"number",format:"#.0",sortable:true,readonly:true}
	];
	

STEP 3.  Declare grid global behavior in context.  

	var context = {
	    sequence:true,checkBox:true,
	    readonly:true,sortable:true,paintMode:"all"
	};
	

STEP 4. Get data from anywhere(database, files, JSON objects).  

	var data = [
	    {operating:"Advertising",budget:23.4,actual:10.3},
             {operating:"Bad debts",budget:34.6,actual:21.3},
             {operating:"Cash discounts",budget:98.7,actual:67.4},
             {operating:"Delivery costs",budget:65,actual:78}
         ];
	
SETP 5. Construct a grid instance based on a div named grid, then bind data to grid.   
	grid = new SigmaGrid("grid",context,columns);
	grid.bindData(users);
	

Architecture & model objects

Column Object

SigmaGride creates grid headers according to column object. Column object contains plenty of attributes, and developers could gain flexisible functionanities by setting these attributes.
  1. name 
    To specify which attribute of data object is bind to this column. OGNL is supported, That is to say, if data object contains sub-objects, developers could specify sub-objects' atrribute to bind.   
  2. caption
    To specify columnn header caption.
  3. width;
    To specify column width(px). Default value is 100.   
  4. mode
    To specify data type. SigmaGrid suports number, string, boolean, select as well as user defined data type.
  5. align
    To specify alignment. Could be left,right and center.
  6. readonly
    To specify if column is editable or not. Should be boolean value or expression. e.g. p$("money">50000)ďź?for that column is read only if money attribute is greater than 50000.
  7. sortable
    To specify column is sortableă??
  8. format
    To specify format with which data is displayed. Only for number format. e.g. "#" for no decimals displayed. "#.00" for two decimals displayed. "#.00#" for at least 2 deciamals. "#.0%" for percent format with 1 decimal. 
  9. render
    To specify user defined renderer. See here for more. 
  10. editor
    To specify user defined editor. See here for more.
  11. formula
    To specify an expression by which value can be calcuted out. Expression syntax is javascript compatible. Use function p$("")to get refered cell's value.
  12. _print
    To specify if column is needed to print out.

Data Ojbect & MVC architecture

Sigma Grid architecture adopts typical MVC (Model-View-Controller) pattern(see following chart). Data objects array manages rows data, that is, every grid row has corresponding data object behind. Context object and column object array control global behavior and each column behavior respectively. Once data objects are bind to the grid, each column object will pick up corresponding attribute value and display it within intersection cell. Note that values are picked up by attribute name instead of occurence order. This archetecture separates view & data, bringing us plenty of advantages, such as hidden columns, formular with invisible columns.

 

Context Object

Context Object contains the following attributes, developer can change Sigma Grid behavior by setting those attributes.

  1. readonly
    Boolean. To specify the grid is editable or not.  This would be overriden by declaration some read-only columns.
  2. sortable
    Boolean. To specify the each column is sortable by clicking header. This would be overriden by declaration some sortable columns.
  3. sequence
    Boolean. To specify if row number column is visible or not.
  4. checkBox
    Boolean. To specify if check box column for selection is visible or not. Exclusive with radioBox.
  5. radioBox
    Boolean. To specify if ridio box column for selection is visible or not. Exclusive with checkBox.
  6. locked
    Integer. To specify how many columns are locked. Width of locked columns is not changeable nor scrollable horizontally. 
  7. paintMode
    String. To specify by which mode rows ara rendered. Could be all , view or auto. All for rendering whole grid in one time. View for rendering visible rows only. Auto for rendering row according to rows count, see paintValve.
  8. paintValue
    Ingeter. To specify rows count threshold. All mode is adopted if rows count is less than paintValue, else view mode is adopt.
  9. pageCtl
    Object. To specify Object which assists with paging.
    1. pageSize. Integer. To specify how many rows are in the page.
    2. callback. Funtion. See  here for more. 
  10. aggregate
    Object Array. To specify how aggregates are calculated.
    1. col. String. To specify on which column aggregate is calculated.
    2. exp. String. To specify what aggregate is calculated. Could be min,max,avg,sum,count.
    3. format. String. To specify format in which aggregate is displayed.  e.g. "#" for no decimals displayed. "#.00" for two decimals displayed. "#.00#" for at least 2 deciamals. "#.0%" for percent format with 1 decimal.
    		aggregate:[
    			{col:"number",exp:"sum",format:"#.000"},
    			{col:"percent",exp:"avg"},
    			{col:"age",exp:"max"}
    		]
    		
  11. groupBy
    Object. To specify how aggregates are calculated group by group.
    1. keyName. String. To specify rows are divided on which column value.
    2. groupsOrder. Object. To specify the occurrence order among groups.
      1. column. String. To specify by which column groups are sorted.
      2. order. String. Could be asc or desc.
    3. rowsOrder. Object. To specify the occurrence order inside each group.
      1. column. String. To specify by which column rows are sorted within group.
      2. order. String. Could be asc or desc.
    4. aggregate. Ojbect Array. To specify on which columns aggregates are calculated.
      1. column. String. To specify on which columns aggregate is calculated.
      2. exp. String. To specfiy what aggregate is calculated. Could be min,max,avg,sum,count.
    5. view. String. oThis.rows[0].rowData.p$('period'). oThis.values()['inMoney']
    groupBy:{
    	keyName:"category",
    	groupsOrder:{column:"category",order:"asc"},
    	rowsOrder:{column:"from",order:"asc"},
    	aggregate:[
    		{column:"unitprice",exp:"sum",format:"#.00"},
    		{column:"quantity",exp:"sum",format:"#"}
    	],
    	view:"oThis.rows[0].rowData.p$('category') +"
    +" ' : Price sum is $' + oThis.values()['unitprice'] +"
    +" ' and quantity sum is ' + oThis.values()['quantity']"
    }
    		

User API

SigmaGrid

Methods

  1. SigmaGrid(dom,context,columns)
    To create sigma grid. 

    Parameters

    • dom - Should be id or DOM object of a div on which grid is created.
    • context - Context object. 
    • columns - Columns objects array. 

    Returned - An instance of sigma grid.
    Sample var grid = new SigmaGrid();

  2. bindData(data)
    To bind data to grid.

    Parameter

    • data - Data objects array. 

    Returned - Void.
    Sample grid.bindData([{},{},...]);

  3. addRow(rowData)
    To add one row to the grid.

    Parameter

    • rowData - Data object. Null allowed for an empty row.

    Returned - Void.
    Sample grid.addRow(null);

  4. deleteSelectedRows()
    To delete all the selected rows.

    Parameter - Void.

    Returned - Void.
    Sample grid.deleteSelectedRows();

  5. loadFirstPage()
    To load the first page. Use this function instead of bindData if pageCtl is specified.

    Parameter - Void.

    Returned - Void.
    Sample grid.loadFirstPage();

  6. getValue()
    To get the whole data objects array within grid.

    Parameter - Void.

    Returned - the whole data objects array within grid.
    Sample var data = grid.getValue();

  7. getSelectedRows()
    To get SigmaRow objects array in selected rows. If you want to get the data array, use getSelectedRowsValue instead.

    Parameter - Void.
    Returned - SigmaRow objects array in selected rows.
    Sample var rows = grid.getSelectedRows();

  8. getSelectedRowsValue(colNames)
    To get data array of selected rows. Only data for colNames will be retrieved.

    Parameter

    • colNames. Columns names array. Empty array for all columns.

    Returned - Data array.
    Sample var values = grid.getSelectedRowsValue(["firstName","lastName","orderId"]);

  9. getColByName(colName).

    To get Column object with the specified name.
    Parameter

    • colName. Column name.

    Returned - Column object.

  10. selectAll(selected).

    To mark all the rows selected or unselected.
    Parameter

    • selected. Boolean. True for selected, false for unselected. 

    Returned - None.

Events

Sigma Grid trigers some special function when events are fired. Developer can provide event handler by overriding these functions.
e.g. grid.onXXX = function(){...your logic goes here...} .
  • onRowSelected(evt)
    Fired after - Some row is selected or un-selected.
    Parameters
    • evt.selected - Boolean. Indicate row is selected or un-selected.
    • evt.row - Sigma row object. The row which is selected or un-selected. 
    Returned - Void.
  • onCellValueChanged(evt)
    Fired after - Some cell is edited.
    Parameters
    • evt.cell - Sigma cell object. The cell which is changed.
    • evt.oldValue - The cell value before being changed.
    • newValue - The cell value after being changed. 
    Returned - Void.
  • onCellClicked(evt)
    Fired after - Some cell is clicked by user.
    Parameter
    • evt.cell - Sigma cell object. The cell which is clicked. 
    Returned - Void.

SigmaRow

Methods
  1. setSelected(selected)
    To set cell selected or un-selected.

    Parameter

    • selected - Boolean. True for selected. False for un-selected.  

    Returned - Void.
    Sample row.setSelected(true);

  2. getCellValue(column)
    To get the cell value of specified column.

    Paramter

    • column - Column object. The column where the cell is at.  

    Returned - The cell value.
    Sample
    var column = grid.getColByName("name");
    var name = row.getCellValue(column);

  3. cells()
    To get all the cells array which the row contains.

    Returned - A map from column name to cell value. Note that the returned value is kind of map. Developer can get some specific cell value by row.cells()["colName"] .
    Sample
    var cells = row.cells(); var cell = cells["colName"];

Attributes
  1. grid - Sigma grid object. The grid instance where the row is at.
  2. rowData - Data object. The corresponding data object of the row. 
  3. _index - Integer. The row index. 
  4. _selected - Boolean. Indicate row is selected or not.  

SigmaCell

Methods
  1. isReadonly()
    To get a boolean indicating cell is read only or not.

    Parameter - Void.

    Returned - Boolean. A boolean indicating cell is read only or not.
    Sample var r = cell.isReadonly();

  2. setValue(newData,evtTrigger)
    To set cell to a new value.

    Parameters 

    • newData - The new cell value.
    • evtTrigger - Boolean. True to triger onCellValueChanged function. Null is allowed for false.

    Returned - Void.
    Sample cell.setValue(100);

  3. getValue()
    Get cell value.

    Parameter - Void.

    Returned - Cell value.
    Sample var r = cell.getValue();

  4. repaint()
    To force grid to repaint cell.

    Parameter - Void.

    Returned - Void.
    Sample cell.repaint();

Attributes
  1. col - Column object. The column where cell is at. 
  2. row - Sigma row object. The row where cell is at.

User defined renderer

User defined renderer should be a function object with a method named paint, which should be declared as.

Parameters

  • grid - Sigma grid object. The grid instance where renderer is in.
  • row - Sigma row object. The row where renderer is at.
  • col - Sigma column objcet. The column where renderer is at.
  • Returned - Html string to render cell value.
Sample
var sgrid_StringRender = new function(){
	this.paint = function(grid,row,col){
		var data = row.getCellValue(col);
		if(data===null ||  data===undefined){
			return "";
		}
		return data;
	}
}
	

User defined editor

Editor is an area for user input when some cell is clicked to be editable. User defined editor should be a function object with a method named paint, which should be declared as.

Parameters

  • grid - Sigma grid object. The grid instance where editor is in.
  • row - Sigma row object. The row where editor is at.
  • col - Sigma column objcet. The column where editor is at.
  • Returned - Html string to render editor.
Sample
var sgrid_StringEditor = new function(){
	this.paint = function(grid,row,col){
		var data = row.getCellValue(col);
		var s = [];
		s[s.length] = '<input type=text onblur="s_grid_cellBlur('
		s[s.length]= grid.id+',this.parentNode,event);"'
		s[s.length] ='" onkeydown="s_grid_cellFocusHandle('
		s[s.length] = grid.id;
		s[s.length] =',this.parentNode,event);" ';
                s[s.length] ='style="border-width:0px;height:19px;width:100%;" maxsize=255';
		s[s.length] =' />';
		return s.join('');
	}
}
	

Note
User defined editor should assist SigmaGrid in cells focus managament. The recommended way is to call s_grid_cellBlur in editor onblur event handler and to call s_grid_cellFocusHandle in editor onkeydown handler. Once user presses enter key or tab key, editor will lose focus and Sigma will accept input and render it out. We don't encourage you to define a new renderer if you don't have excellent practice.  

Embeded paging object pageCtl

When you want present data page by pay, you need to implement a pageCtl object in context.

Attribut:
  1. pageSize - Integer. Indicate max rows count page would contain.
  2. callback - Function. See paging callback function below.

Paging callback function

Parameter

  • pageCtl - PageCtl object. The pageCtl object which takes this function as its callback function.
  • Returned - Page object.  See page object below.
Sample
function pageLoad(pageCtl){
	var page = null;
	var index = pageCtl.page.index;
	//TODO: load the page elements 
	var elements = ...
	//TODO: calculate total number of elements;
	var total = ...
	page.index = index;
	page.elements = elements;
	page.total = total;
	return page;
}
	

Page Object

Page Object should be a data object without any method.  Page Object should contain the following attributes. 

  1. index Current page index. Based on zero.
  2. total:How many rows in total allover the pages. SigmaPageCtl determine total page number through this attribute.
  3. elements Data array. The array length should not be greater than Sigma Grid pageSize(defined in context).
Sample
{
	index:0,
	total:600,
	elements:[
		{personnel:"Office",budget:"540000",actual:"530000",diffrence:"10000"},
		{personnel:"Store",budget:"60000",actual:"62000",diffrence:"2000"},
		{personnel:"Salespeople",budget:"800000",actual:"820000",diffrence:"20000"},
		{personnel:"Others",budget:"380000",actual:"350000",diffrence:"30000"}
	]
}
	

All contents are (c) Copyright 2005 - 2007, Sigma Software Inc. All rights Reserved