Download a Trial

Attend a Webinar

Share This Page


Related Items

Follow FireScope

 

FireScope Grid

FireScope Grid

FireScope Grid is an open source (GNU Public License, v2) jQuery component that adds datagrid behaviors to your HTML tables, regardless of the server-side technology being used. Included in the plugin is a navigation bar that is automatically appended at the beginning or end of a table that enables users to page through results, filter results by any column or sorted on the fly without need to refresh the entire page.

Source code examples are included on the Examples tab, with backend examples available in PHP and ASP.

    Features
  • Paging - Specify how many rows you want displayed at a time and the FireScope Grid will automatically generate navigation links to enable users to page through the results.
  • Sorting - FireScope Grid includes control over which columns users can sort by, including control of the default sort.
  • Filtering - AJAX capability enables on-the-fly filtering of results, with control over which columns to allow filtering.
  • Auto Refresh - AJAX capability enables automatic refresh at user selected intervals.
  • Configurable - Developers have complete control over which columns to allow filtering or sorting, paging of data sets as well as the look and feel of the plugin. Included CSS and icon files can be extended to fit the style of your website.
The following example demonstrates the paging, sorting and filtering capabilities of the FireScope Grid. Click on any column name to sort in ascending order; click a second time to sort in descending order. You will also see three text fields that can be used to filter results; simply type in a criteria for filtering and tab out of the field to activate. Additionally, this example shows off the paging capability of FireScope Grid, as you can see in the paging controls above the table.


Code used to generate this example

  • File firescope_grid_example.php; This page does not require any server-side logic, but contains the layout for the page users will see and instantiates the FireScope Grid. Note that the URL attribute of the FireScope Grid specifies the PHP, ASP or other platform that will generate the dataset that will be displayed by FireScope Grid. 
    
<html>
<head>
<title>FireScope Grid JQuery Example</title>
<script type="text/javascript" src="jquery-1.2.6.js"></script>

<link type="text/css" rel="stylesheet" href="firescope_grid/firescope_grid.css"/>
<script type="text/javascript" src="firescope_grid/jquery.firescope_grid.js"></script>
</head>
<body>

<!-- container for the FireScope Grid //-->
<div id="firescope_grid_example"></div>

<!-- Initialize the FireScope Grid //-->
<script type="text/javascript">

$(document).ready( function() {
	$('#firescope_grid_example').firescope_grid({
		rows: 10,
		url: 'firescope_grid_example_data.php?firescope_grid=yarp', // your server side file
		filterCols: [1,2,3],
		sortCols: ['auto'],
		sortCol: 0,
		navBarShow: 'always',
		navBarAlign: 'right',
		navBarLocation: 'top',
		data: {
			yourparm: 'ok'
		},
		ignore: null				
	});	
}); 
</script>
</body>
</html>
  • File firescope_grid_example_data.php; this will be your code page for delivering the dataset to be used by the FireScope Grid. 
    <?php
if (isset($_REQUEST['firescope_grid'])) {
	try {
		$dbh = new PDO("sqlite:example.sqlite");
		
		$sql = "SELECT * FROM users WHERE 1";
		if ($_REQUEST['firescope_grid_filterCol'] == 1 && strlen($_REQUEST['firescope_grid_filterText']) > 0) {
			$sql.=" AND username LIKE '%".$_REQUEST['firescope_grid_filterText']."%'";
		}
		else if ($_REQUEST['firescope_grid_filterCol'] == 2 && strlen($_REQUEST['firescope_grid_filterText']) > 0) {
			$sql.=" AND name LIKE '%".$_REQUEST['firescope_grid_filterText']."%'";
		}
		else if ($_REQUEST['firescope_grid_filterCol'] == 3 && strlen($_REQUEST['firescope_grid_filterText']) > 0) {
			$sql.=" AND email LIKE '%".$_REQUEST['firescope_grid_filterText']."%'";
		}
		if ($_REQUEST['firescope_grid_sortCol'] == 0) {
			$sql.=" ORDER BY id ".$_REQUEST['firescope_grid_sortOrder'];
		}		
		else if ($_REQUEST['firescope_grid_sortCol'] == 1) {
			$sql.=" ORDER BY username ".$_REQUEST['firescope_grid_sortOrder'];
		}
		else if ($_REQUEST['firescope_grid_sortCol'] == 2) {
			$sql.=" ORDER BY name ".$_REQUEST['firescope_grid_sortOrder'];
		}
		else if ($_REQUEST['firescope_grid_sortCol'] == 3) {
			$sql.=" ORDER BY email ".$_REQUEST['firescope_grid_sortOrder'];
		}
		else if ($_REQUEST['firescope_grid_sortCol'] == 4) {
			$sql.=" ORDER BY last_access ".$_REQUEST['firescope_grid_sortOrder'];
		}
		$qry = $dbh->query($sql);

		$rows = $qry->fetchAll();
		$total = count($rows);
		
		$offset = ($_REQUEST['firescope_grid_page'] - 1) * $_REQUEST['firescope_grid_rows'];
		$rows = array_slice($rows, $offset, $_REQUEST['firescope_grid_rows']);
		// or use mysql_data_seek() 
		// or add a `LIMIT $offset, $_REQUEST['firescope_grid_rows']` to your sql
		
		$output = '
		<table><tr><th>ID</th><th>Username</th><th>Name</th><th>Email</th><th>Last Accessed</th></tr>
		';

		foreach ($rows as $row) {
			$output .= '<tr>
			<td>'.$row['id'].'</td>
			<td>'.$row['username'].'</td>
			<td>'.$row['name'].'</td>
			<td>'.$row['email'].'</td>
			<td>'.date('Y-m-d H:i:s', $row['last_access']).'</td>	
			';
		}
		$output .= '
		</table>';

		ob_clean();
		echo '<span id="firescope_grid_example_total" style="display:none">'.$total.'</span>';
		echo '<span>'.$output.'</span>';
		exit();
		
	} catch(PDOException $e) {
		echo $e->getMessage();
	}	

}

?>
  • File firescope_grid_example.asp; this will be whatever your page is. 
    <html>
<head>
<title>FireScope Grid Example</title>
<script type="text/javascript" src="jquery-1.2.6.js"></script>

<link type="text/css" rel="stylesheet" href="firescope_grid/firescope_grid.css"/>
<script type="text/javascript" src="firescope_grid/jquery.firescope_grid.js"></script>
</head>
<body>

<!-- container for the FireScope Grid //-->
<div id="firescope_grid_example"></div>

<!-- Initialize the FireScope Grid //-->
<script type="text/javascript">

$(document).ready( function() {
	$('#firescope_grid_example').firescope_grid({
		rows: 10,
		url: 'firescope_grid_example_data.asp?firescope_grid=yarp', // your server side file
		filterCols: [1,2,3],
		sortCols: ['auto'],
		sortCol: 0,
		navBarShow: 'always',
		navBarAlign: 'right',
		navBarLocation: 'top',
		data: {
			yourparm: 'ok'
		},
		ignore: null				
	});	
}); 
</script>
</body>
</html>
  • File firescope_grid_example_data.asp; this example represents the page that generates your data. 
    <!--#include virtual="/OpenSource/Grid/firescope_grid_login.asp"-->
<%
Set Conn = Server.CreateObject("ADODB.Connection")
Conn.Open SQLConn


firescope_grid_filterText = ReQuest("firescope_grid_filterText")
firescope_grid_filterCol = ReQuest("firescope_grid_filterCol")
Select case firescope_grid_filterCol
	Case 1 FilterCol = "username"
	Case 2 FilterCol = "name"
	Case 3 FilterCol = "email"
	Case else FilterCol = "username"
end select


firescope_grid_sortOrder = ReQuest("firescope_grid_sortOrder")
firescope_grid_sortCol = ReQuest("firescope_grid_sortCol")
select case firescope_grid_sortCol
	Case 0 SortCol = "ID"
	Case 1 SortCol = "UserName"
	Case 2 SortCol = "name"
	Case 3 SortCol = "email"
	Case 4 SortCol = "last_access"
end select

firescope_grid_rows = ReQuest("firescope_grid_rows")
firescope_grid_page = ReQuest("firescope_grid_page")

SQL = "Select * from users "

If Len(firescope_grid_filterText) > 0 then
	SQL = SQL & " where " & FilterCol & " like '%" & firescope_grid_filterText & "%' "
end if


if Len(firescope_grid_sortCol) > 0 then
	SQL = SQL & " order by " & SortCol & " " & firescope_grid_sortOrder
End if

Set RS = Server.CreateObject("ADODB.RecordSet")
RS.Open SQL, Conn, 3, 3

if RS.RecordCount > 0 then
	Dim nbrRows
	nbrRows = 0
	Response.write "<span id=""firescope_grid_example_total"" style=""display:none;"">" & RS.RecordCount & "</span>" & vbNewLine
	Response.write "<table width='100%' cellpadding='0' cellspacing='0'>" & vbNewLine
	Response.write "<tr>" & vbNewLine
	Response.write "<th>ID</th><th>Username</th><th>Name</th><th>Email</th><th>Last Accessed</th></tr>" & vbNewLine
	Do Until RS.EOF
		nbrRows = nbrRows + 1
		if (nbrRows <= ((firescope_grid_page - 1) * firescope_grid_rows)) then
			
		ElseIf (nbrRows > ((firescope_grid_page - 1) * firescope_grid_rows + firescope_grid_rows)) then

		Else
			Response.write "<tr>"	 & vbNewLine
			Response.write "<td>" & RS("ID") & "</td>" & vbNewLine
			Response.write "<td>" & RS("Username") & "</td>" & vbNewLine
			Response.write "<td>" & RS("name") & "</td>" & vbNewLine
			Response.write "<td>" & RS("email") & "</td>" & vbNewLine
			Response.write "<td>" & RS("last_access") & "</td>" & vbNewLine
			Response.write "</tr>" & vbNewLine
		End if
	RS.MoveNext
	Loop
	Response.write "</table>" & vbNewLine
END IF

Response.write vbNewLine
Response.write "SQL used to generate the table above: " & vbNewLine
Response.write SQL & vbNewLine

Set RS = Nothing
Conn.Close
%>

 

 

Data sample for table users

  • SQLite Schema 
    <!-- Just the data used in this example //-->
CREATE TABLE "users" (
  "id" INTEGER PRIMARY KEY NOT NULL,
  "username" varchar(20) NOT NULL,
  "name" varchar(20) NOT NULL,
  "password" varchar(20) NOT NULL,
  "email" varchar(20) NOT NULL,
  "last_access" INTEGER NOT NULL
);

INSERT INTO "users" VALUES ('100000001', 'ijohnyjohn47', 'John Smith', '387fdnslfj893', 'ijohnyjohn47@smith.net', '1218647455');
.. as many rows as there are rows ..
INSERT INTO "users" VALUES ('100000003', 'mombo', 'Joe Smith', 'rwerwer2354', 'mombo@smith.net', '1218644455');

 

 

Include FireScope Grid

  • Include the latest version of JQuery and the FireScope Grid JS and CSS in your page <head></head>. 
    
<script type="text/javascript" src="firescope_grid/jquery-1.2.6.js"></script>
<script type="text/javascript" src="firescope_grid/firescope_grid.js"></script>
<style type="text/css" rel="firescope_grid/firescope_grid.css"></style>
  • Check firescope_grid.css and make sure the images are properly referenced. 
    
../firescope_grid/first.png       
../firescope_grid/grid-split.gif  
../firescope_grid/last.png        
../firescope_grid/load.gif        
../firescope_grid/load.png        
../firescope_grid/next.png        
../firescope_grid/prev.png        
../firescope_grid/sort-asc.png    
../firescope_grid/sort-desc.png   
../firescope_grid/sort-none.png
  • Create a container for the FireScope Grid 
    <div id="firescope_grid_example"></div>

Activate

  • Create a call to the FireScope Grid JS in your page. 
    
	<script type="text/javascript">
$(document).ready( function() {
	var options = {
		url: 'yourserversidescript.ext',
		rows: 50
	};
	var firescope_grid = $('#firescope_grid_example').firescope_grid(options);	
}); 
</script>

    JS Options

    Pass any or all of these options to the JS firescope_grid() call 
    
	var options = {
        // important options
        url: '',                 // ;url to get data from via ajax         
        rows: 25,                // #; nbr rows to show at a time; x rows = 1 page
        selectorHeader: 'tr th', // null|*; selector used to find() the table header
                
        // other options
        total: 0,                // #; total nbr rows to be shown
        height: 'auto',          // auto|#px|#%; auto - uses variable height of data; px - absolute; % - relative to parent container
        page: 1,                 // #; initial page to load; most likely 1
        
        data: {},                // ;additional parameters to send attached to url; your scripts query string perhaps?
        dataType: 'html',        // html; data format returned from ajax call; todo json|others?
		
        ajaxTimeout: 600000,     // ajax timeout in ms
        ajaxRefresh: null,       // null|#; ajax refresh in ms; must be > 1000 and > than time to return your data
        
        sortCols: ['auto'],      // array[#]|array['auto']; array of column numbers to allow sorting; auto - all columns (0 based index)
        sortCol: 0,              // #; initial column number to sort by (0 based index)
        sortOrder: 'asc',        // asc|desc; initial sort order of sortCol
        sortType: 'server',      // server; server - sort server side; todo client|auto
        
        filterCols: ['auto'],    // array[#]|array['auto']; array of column numbers to display filter text boxes above; auto - all columns (0 based index)
        filterCol: -1,           // #; initial filter column; -1 filter ignore; (0 based index)
        filterText: '',          // ; initial filter text for filterCol
        filterType: 'auto',      // server|client|auto; server - filter server side via your code; client - filter by js; auto - try to use js if makes sense

        returnSortColName: false,   // true|false; return sorting column name; useful if column name same as db field name or for custom messages
        returnFilterColName: false, // true|false; return filtering column name; useful if column name same as db field name or for custom messages
        
        navBarShow: 'auto',        // never|always|auto; never - never show; always - always show; auto - show if more rows than total rows, hide otherwise
        navBarAlign: 'right',      // left|right|center; css text-align
        navBarLocation: 'top',     // top|bottom; where to place navigation bar
        navCustomLocation: 'left', // left|right; where to place custom msg, if any, in relation to other nav bar components
            
        cssRowEven:      null,     // null|{css:value}|'csstag'; css for every other row
        cssRowOdd:       null,     // null|{css:value}|'csstag'; css for every other row
        cssRowMouseOver: null,     // null|{css:value}|'csstag'; css for mouse over
		
        msgFilterHelp:             '',
        msgPagesExceedMax:         'There are only {nbr_pages} pages.',
        msgPageExceedMax:          'There is only {nbr_pages} page.',
        msgEnterAValidPageNbr:     'Enter a valid page number.',
        msgURLInvalid:             'Invalid url for data. Trying current url..',
        msgLoading:                ' Loading..',
        msgNetworkError:           'Retrieve data.',
        msgReloadPage:             'Reload page.',
        msgStatusDispFromToTotal:  'Displaying {from} to {to} of {total}',
        msgStatusDispFromTo:       'Displaying {from} to {to}',
        msgStatusDispNone:         'No results',		
        msgRows:                   '', // Rows
        msgRefresh:                ' Refresh',
        msgCustom:					['none'],	// ['none']|[*]; custom messages to appear in nav bar

        selectorFooter: null,     // null|*; selector used to find() the table footer, if any  
        selectorResult: null, 	  // null|*; selector used to parse result; useful if dont have control over result
        selectorIgnoreRows: null, // null|*; selector used to igonre when couting nbr rows for nav
        
        ignore: ''                // placeholder; ignore
	};

     

    JS Methods

    The FireScope Grid uses these method internally, but you can call them through your JS if needed. 
    	
	firescope_grid.gotoPage(page); // go to the specified page number; first page starts at 1
	firescope_grid.nextPage();     // go to the next page, if any
	firescope_grid.prevPage();     // go to the previous page, if any
	firescope_grid.firstPage();    // go to the first page
	firescope_grid.lastPage();     // go to the last page

 

Server Side

  • Server side variables sent by FireScope Grid on the load, paging, sorting, and filtering of FireScope Grid 
    	
	firescope_grid_page           // requested page; 1-index
	firescope_grid_rows           // requested number of rows
	firescope_grid_offset         // db offset; calculation of (firescope_grid_page - 1) * firescope_grid_rows
	firescope_grid_sortCol        // column to sort by; 0-index
	firescope_grid_sortOrder      // how to sort; asc|desc
	firescope_grid_filterCol      // column to filter by, if any
	firescope_grid_filterText     // text to filter with, if any
	firescope_grid_sortColName    // if returnSortColName, name of column sorting by
	firescope_grid_filterColName  // if returnFilterColName, name of column filtering by
	{any other parms you sent}
  • Required containers to pass your table back to FireScope Grid in 
    	
	echo '<span id="firescope_grid_example_total" style="display:none">'.$total.'</span>';  // total number of rows, after filter
	echo '<span>'.$your_html_table.'</span>';
    Note: the id "firescope_grid_example_total" is dervied from your name for the FireScope grid container. This allows multiple grids to exist on the same page. So from:
    var firescope_grid = $('#firescope_grid_example').firescope_grid(options);
    append "_total" to your FireScope grid container id, is this example: "firescope_grid_example".

 

 

Download Links

FireScope Grid 0.1.5
2009-06-29

FireScope Grid 0.1.4
2009-02-13

FireScope Grid 0.1.3
2008-08-26

FireScope Grid 0.1.2
2008-08-18

FireScope Grid 0.1.1
2008-07-23

Changelog

  • 0.1.5 2009-06-29
    - added filterClear, defaulted to true; clears the filter text on click
    - added selectRowsEnabled, default to true; to disable/enable selection of rows to show
    - added methods disableSelectRows()/enableSelectRows()
    - added dataOnce for custom parms to be used on intial load of grid
    - added method setDataOnce() to populate dataOnce
    - added method setData() to populate/change user parm data
    - added method updateData() to update user parm data
    - added method setCfg() to change cfg options
    - added filterColOptions[] which allows a select box of options to be specified for filter
    - added filterMulti to turn on filtering by multiple columns
    - added filterMultiText for return data to filter by
    - fixes for nav button staying disabled when using page methods
    - fixes for single filter not being cleared when another filter was typed in
    - change serverType defaulted to 'server'; client side filtering only works if all results on one page
  • 0.1.4 2009-02-13
    - renamed parm timeout to ajaxTimeout
    - added parm ajaxRefresh, to auto refresh the current grid page in X ms
        must be > 1000 and should be > than time to return your data
        will not refresh till prior ajax call ends
    - added msgRows, defaulted to blank
    - added msgRefresh, defaulted to ' Refresh', only shown if using ajaxRefresh
    - added selectorResult, defaulted to null; usefull if your result contians more then just a table; used to to find the table
    - added cssEvenRow, cssOddRow; in case table doesnt already have its own css
    - firescope_grid_total replaced with calling id + '_total' to allow moultiple grids on one page
    - new default images and css - if nbr results less than nbr requested rows, assume end of results found and display correct nbr rows - if selectorHeader not sent or found, use first row of table as header
    - fixes for entering page number; allow backspace, del, etc
    - fixes for filtering indicator and double filter on keypress enter and then blur
    - fixes for next page and start page buttons when nbr pages not known and nav bar is set to auto
    - fixes for showing nav buttons as disabled; other css fixes for ie7
  • 0.1.3 2008-08-26
    - return error message if no results returned
    - added msgCustom to add array fo custom html elements to nav bar, if any
    - added navCustomLocation to add custom msgs, if any, to left or right of nav bar
    - added firescope_grid_offset parm to be returned on ajax calls;
        to save a user calculation of: (firescope_grid_page - 1) * firescope_grid_rows,
    - fixed; when total not provided, display correct x rows of y instead of x of -1
    - fixed; css changes for IE
  • 0.1.2 2008-08-18
    - added selectorFooter // null|*; selector used to find() the table footer, if any
    - added returnSortColName // true|false; return sorting column name;
        useful if column name same as db field name or for custom messages
    - added returnFilterColName // true|false; return filtering column name;
        useful if column name same as db field name or for custom messages
    - if nbr of rows returned from table less than requested, next and last page buttons disabled
    - <span id="firescope_grid_total" style="display:none">'.$total.'</span> is no longer required;
        but it is still recommended and useful if you want to display page # of pages
  • 0.1.1 2008-07-23
    - added selectorHeader
    - fixed cfg.nbrPages, display of pages and records in edge cases
  • 0.1.0 2008-06-09
    - initial version
    - inspired by flexigrid and ingrid
    - no actuall code used from flexigrid nor ingrid
    - ideas for css, images, and layoout inspired by flexigrid and ingrid

 

 

Contact

Discuss at FireScope forums