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

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