Zapatec Grid
Javascript Grid Point arrow   Overview
Javascript Grid Point arrow   Demos
Javascript Grid Point arrow   License
Zapatec AJAX Grid Manual

Zapatec AJAX Grid Manual

Contents

    1  Get the Zapatec AJAX Grid files
        1.1  Download the Zip file
        1.2  Unzip zpgrid.zip

    2  Quick Startup
        2.1  Set Up Your Grid
            2.1.1  Insert The Headers
            2.1.2  Path Warning
        2.2  Create the Presentation
        2.3  Attach the Zapatec Grid Object to your Presentation
        2.4  Copy your files to your web server
        2.5  Test the grid application
        2.6  Change Included Files
            2.6.1  Use a Different Theme

    3  Configuration Options
        3.1  Configuration Parameters
            3.1.1  source (string OR object, default null)
            3.1.2  sourceType (string, default null)
            3.1.3  container (string OR object, default null)
            3.1.4  theme (string, default ”)
            3.1.5  callbackHeaderDisplay (function, default null)
            3.1.6  callbackRowDisplay (function, default null)
            3.1.7  sortColumn (int, default null)
            3.1.8  sortDesc (boolean, default false)
            3.1.9  rowsPerPage (int, default 0)
            3.1.10  filterOut (array, default [])

    4  Scenarios
        4.1  Table To Grid
        4.2  Grid Column Types
            4.2.1  HTML Table Column Types
            4.2.2  JSON Column Types
            4.2.3  XML Column Types
        4.3  Controls and Filters
            4.3.1  Filter Based on Selection
            4.3.2  Filter Based on Range
        4.4  Sorting
            4.4.1  Initial Sorting
            4.4.2  User Column Sorting
        4.5  AJAX - in the grid

1  Get the Zapatec AJAX Grid files

1.1  Download the Zip file

The AJAX Grid files are bundled in a zip file. Click on the download link in the Grid section of Zapatec’s web site, and follow the instructions to download the file.

Save the file (zpgrid.zip) to your website’s root folder on your computer or server.

1.2  Unzip zpgrid.zip

  1. On your computer, go to the folder where you saved the file zpgrid.zip.

  2. zpgrid.zip contains a folder called zpgrid that holds all of the files you will need to create your grid.

  3. Open or double-click zpgrid.zip to unzip or unpack it.

2  Quick Startup

If you have not done so follow the instructions in section 1.1. to download and unzip the Grid files.

2.1  Set Up Your Grid

2.1.1  Insert The Headers

In your web editor (Dreamweaver, UltraEdit, etc.), open the web page where you want the grid placed. Insert your cursor before the ending </head> tag. Paste the following style path and script paths before the ending </head> tag:

<!-- Javascript utilities file for the grid -->
<script src="utils/utils.js" type="text/javascript"></script>
<!-- Transport file to fetch data-->
<script src="utils/transport.js" type="text/javascript"></script>
<!-- basic Javascript file for the grid -->
<script src="src/grid.js" type="text/javascript"></script>
<!-- CSS file for basic style in the grid-->
<link href="themes/basic.css" rel="stylesheet" />

The above lines different files located in the grid folder. The files are:

  • utils.js

    Located in the utils folder. General javascript utilities file.

  • transport.js

    Located in the utils folder. Provides the transport calls to fetch data from the server.

  • grid.js

    Located in the src folder. The main javascript grid file.

  • default.css

    Located in the themes folder. Provides basic style for the grid.

2.1.2  Path Warning

If your web page containing the Grid is saved in the zpgrid folder, the above lines will work without any changes. If, however, you save your web page in another location (like directly under your website’s root folder), you will need to adjust the path for these files.

2.2  Create the Presentation

2.3  Attach the Zapatec Grid Object to your Presentation

All you have to do in your HTML page is call Zapatec.Grid to convert a HTML table to a Zapatec Grid

<script type="text/javascript">
   Zapatec.Grid( source: 'myTab');
</script>

where myTab is an id that you have assigned to your HTML table.

<table id='myTab'>
...

You can also attach the Zapatec Grid object using the body onload instead of inside a script tag. Make sure you call Zapatec.Grid AFTER the table is created.

<body onload='Zapatec.Grid( source: 'myTab')'>

2.4  Copy your files to your web server

Using your editing or FTP program, copy or "put" your web page and the entire tree folder to the root of your website.

2.5  Test the grid application

Using your web browser, navigate to the web page that you created to include the Zapatec AJAX Grid. Congratulations! You have set up the most basic version of the Zapatec AJAX Grid! Now, on to the fun and exciting features you can change with this highly adaptable application!

2.6  Change Included Files

You can change the theme of the grid by choosing to include a different file in your header.

2.6.1  Use a Different Theme

One of the lines you inserted in Section 2.1.1 includes the default.css file in the themes folder. This is one of the themes that comes with the Zapatec AJAX Grid. You can choose between several themes by changing the file called by the path. Look in the themes folder for more options.

3  Configuration Options

You can also pass a set of parameters when you create the grid to control the grid behavior. The primary parameters are to define the source of data for the grid.

3.1  Configuration Parameters

3.1.1  source (string OR object, default null)

Where is the origin of the grid data?

This option is coupled with the sourceType option (see 3.1.2).

This option defines where the source of the grid is coming from. Depending on the sourceType option your source will be either a String or an Object. The String will be either the ID of container, the URL, or the External Filename. The Object will either be a TABLE DOM object, JSON Object, or XMLDocument Object.

Possible source values:

  • HTML table - table DOM object or its id, sourceType: ’html’

  • JSON object or string - JSON object or string, sourceType: ’json’

  • JSON external file - URL of JSON data source, sourceType: ’json/url’;

  • XMLDocument object or XML string - XMLDocument object or XML string, sourceType: ’xml’;

  • XML external file - URL of XML data source, sourceType: ’xml/url’.

Here are some examples:

From Table ID see Phone Bill Demo

<table id='myTable'>...</table>
...
source: 'myTable', // ID of TABLE
sourceType: 'html'

An alternate way to define the source as a table OBJECT

source: document.getElementById('myTable'), // Object of TABLE
sourceType: 'html'

From JSON External File see JSON Account Demo

source: 'json_demo.txt',
sourceType: 'json/url',

From JSON Object see Yahoo Demo

source: objJsonSource,
sourceType: 'json',

From XML File

source: 'xml_url.xml',
sourceType: 'xml/url',

3.1.2  sourceType (string, default null)

What is the type of origin of the grid data?

Used together with source option to specify how source should be processed.

Otherwise ignored.

Possible source types: ’html’, ’json’, ’json/url’, ’xml’, ’xml/url’.

3.1.3  container (string OR object, default null)

Where is the grid placed?

Element or id of element that will hold the grid.

If callbackHeaderDisplay and callbackRowDisplay options are defined, grid will be drawn using those functions and container option is ignored.

Also can be used instead of source option. If source option is not defined, first child table of container element is used as source.

3.1.4  theme (string, default ”)

Which theme is used to present the grid?

Theme name that will be used to display the grid. Themes are located in the zpgrid/themes directory.

Corresponding CSS file will be picked and added into the HTML document head element automatically.

NOTE: This is Case insensitive.

3.1.5  callbackHeaderDisplay (function, default null)

Callback function to display grid header.

This options gives you the abililty to perform more complex data manipulation before the grid is presented.

see Yahoo Demo

Used togeter with callbackRowDisplay option as alternetive way to display grid, oterwise ignored.

Receives reference to header object with following properties: userTableStyle: table style attribute defined by user [string], userStyle: header tr style attribute defined by user [string], fields: [ title: field title [string], userStyle: table cell style attribute defined by user [string], onclick: table cell onclick attribute value as string [string] , ... ]

3.1.6  callbackRowDisplay (function, default null)

Callback function to display grid row.

see Yahoo Demo

Used togeter with callbackHeaderDisplay option as alternetive way to display grid, oterwise ignored.

Receives reference to row object with following properties: id: row number in the order of source [number], selected: indicates that this row is selected [boolean], onclick: onclick attribute value as string [string], cells: [ data: mixedValue: cell value [any], compareValue: cell value to compare during sorting [any] , userStyle: table cell style attribute defined by user [string] , ... ], userStyle: table row style attribute defined by user [string]

To get cell value as string, use its toString() method. E.g. objRow.cells[0].data.toString()

3.1.7  sortColumn (int, default null)

Which column should the grid be initially sorted?

see Stock Performance Demo

Number of column to sort initially.

First column number is 0.

If not set, initially grid will not be sorted.

3.1.8  sortDesc (boolean, default false)

Should the sortColumn be initially sorted in descending order?

Used together with sortColumn option. Otherwise ignored.

If true, initially grid will be sorted in descending order.

3.1.9  rowsPerPage (int, default 0)

How many grid rows should be displayed per grid page?

see Phone Bill Demo

If this option is NOT defined then the FULL grid is displayed. When set, will trigger the display of the pager under the grid providing a way for the user to move forwad and backwards in the data set.

3.1.10  filterOut (array, default [])

Provides a way to add checkboxs to filter in/out items in your grid?

see JSON Demo

This option allows you to add Filter controls to your grid.

It generates a list of check boxes (container) for unique values in the specified column (column) that you can include in a form. The user then can click on the checkboxes to include or exclude rows from the grid that match these values.

Array of associative arrays.

Following properties of associative array are recognized:

  • container OR callback:

    • container:element or id of element that will hold the list of values to filter out;

    • callback:callback function used as alternative way to display filter out list;

  • column: number of column to use as source of values to filter out. First column number is 0.

Only one of "callback" and "container" properties should be defined. If they are defined both, "callback" takes precedence over "container".

callback scenario is passed an array of objects. The object has the properties value and onclick, where value is a unique value of column and onclick is the string to call the function to filter the grid.

see Account Filter in JSON Demo

4  Scenarios

4.1  Table To Grid

The easiest way to generate a Zapatec Grid is to use an HTML table.

We use The Stock Performance demo to analyze how to convert a standard HTML table to a Zapatec Grid.

see Stock Performance Demo

The following shows the HTML of the Stock Performance demo that is needed to convert the HTML table to a Zapatec Grid.

  • Notice the use of ids for the DIV and the TABLE. These are used by the Javascript code later to determine where to put the grid and where the data is located.

  • In the table header the different data types tell the grid how to sort the data

<div class='zpGridDefault' id="myGrid">
<table id='myTab'>
<tr>
	<th>Symbol</th>
	<th>Name</th>
	<th class='zpGridTypeFloat'>Mkt Cap</th>
	<th class='zpGridTypeFloat'>Last</th>
	<th class='zpGridTypeFloat'>P/E</th>
	<th class='zpGridTypeInt'>Volume</th>
	<th>Tick Trend</th>
</tr>
<tr>
	<td> MSFT </td>
	<td> MICROSOFT CP </td>
	<td> 283.0B </td>
	<td> 26.59 <td>
	<td> 91,307,152	 </td>
	<td> ==-=== </td>
</tr>

source: ’myTab’

Define the Source Type of the data. In this case it is HTML.

sourceType: ’html’

Define the container where the Zapatec Grid will be displayed. In this case in the DIV that has ID myGrid.

container: ’myGrid’

Define the theme for the Zapatec Grid.

theme: ’default’

Here is how you create an instance of the Zapatec Grid with the above Configuration Parameters:

<script type="text/javascript">
var myTable = new Zapatec.Grid({
	source: 'myTab',
	sourceType: 'html',
	theme: 'default',
	container: 'myGrid'
});
</script>

The contents of the HTML TABLE, myTab, are moved to the DIV, myGrid.

4.2  Grid Column Types

NOTE: If there is NO column type defined then the default is String.

The following list defines the Column Types

  • zpGridTypeString - String

  • zpGridTypeStringInsensitive - String case insensitive

  • zpGridTypeInt - Integer

  • zpGridTypeFloat - Float

  • zpGridTypeDate - Date

  • zpGridTypeTimestampLocale - UNIX timestamp (value displayed in locale format)

  • zpGridTypeTimestampMMDDYYYY - UNIX timestamp (value displayed in MM/DD/YYYY)

  • zpGridTypeTimestampDDMMYYYY - UNIX timestamp (value displayed in DD/MM/YYYY)

  • zpGridTypeTimestampYYYYMMDD - UNIX timestamp (value displayed in YYYY/MM/DD)

  • zpGridTypeBoolean - Boolean

4.2.1  HTML Table Column Types

The first row of your table should define the type of data for each column.

In the TABLE TH CLASS define the Zapatec Column Type.

In the Stock Performance example the Column Types are as follows:

<tr>
	<th>Symbol</th>
	<th>Name</th>
	<th class='zpGridTypeFloat'>Mkt Cap</th>
	<th class='zpGridTypeFloat'>Last</th>
	<th class='zpGridTypeFloat'>P/E</th>
	<th class='zpGridTypeInt'>Volume</th>
	<th>Tick Trend</th>
</tr>

4.2.2  JSON Column Types

For JSON you need to define the column headers in the fields collection.

see JSON Text File

"fields": [
      {"title": "Date", "dataType": "date"},
      {"title": "Account", "dataType": "string"},
      {"title": "Full Name", "dataType": "istring", "style": "font-weight: bold"},
      {"title": "Ref#", "dataType": "integer"},
      {"title": "Amount", "dataType": "float"}
   ],

4.2.3  XML Column Types

For XML you need to define the column headers in the fields collection.

see JSON Text File

<fields>
	<field>
		<title>Date</title>
		<datatype>date</datatype>
	</field>
	<field>
		<title>Account</title>
		<datatype>string</datatype>
	</field>
	<field style="font-weight: bold">
		<title>Full Name</title>
		<datatype>istring</datatype>
	</field>
	<field>
		<title>Ref#</title>
		<datatype>integer</datatype>
	</field>
	<field>
		<title>Amount</title>
		<datatype>float</datatype>
	</field>
</fields>

4.3  Controls and Filters

The Zapatec Grid can automatically define checkboxes for the grid.

You can automatically define the controls for a filter using the option filterOut.

Each control is basically a way to filter the grid based on column contents and user criteria.

There are 2 types of filters you can apply to a Zapatec Grid. One is based on Selection and the other is based on Range.

4.3.1  Filter Based on Selection

see Phone Bill Demo

filterOut: [{container: 'myFilterOut', column: 3}]

The above filterOut will put the control in the container myFilterOut in our Form. The actual control will be a set of checkboxes where each check box is a unique value of the column defined in filterOut. If the check box is ON then that all rows with that column value are displayed, if OFF then rows with this column value are NOT displayed.

filterOut: [
{container: 'myFilterOut', column: 0},
{callback: callback_Acct, column: 1} // Filter Acct
]

The above filterOut creates two different filters. The first one similar to the previous example. The second one uses a callback which provides the flexiblity of customizing the checkbox layout.

4.3.2  Filter Based on Range

see JSON Demo
If you want to filter the grid based on a range of values for a column you call the Zapatec Grid function limitRange(colNumber, minValue, maxValue), where colNumber is the column to filter (1st column is 0), minValue is the minimum value for range, and maxValue is the maximum value for the range.

For example, if you want to show all rows whose 1st column has a value between 10 and 20 then you would call the function as follows: limitRange(0, 10, 20).

4.4  Sorting

see Stock Performance Demo

The grid column is sorted based on the Column Types, see 4.2.

4.4.1  Initial Sorting

If you want the grid to be Initially sorted then set the options sortColumn and sortDesc.

For example if you want the 1st column in your grid to be sorted in ascending order then just set sortColumn to 0.

Anoter example, if you want the 2nd column in your grid to be sorted in descending order then set sortColumn to 1 and sortDesc to true.

If you do NOT want your grid Initially sorted then do NOT set the option sortColumn.

4.4.2  User Column Sorting

You can click on the column header in 1st row to sort grid based on this column.

The column will toggle between ascending and descending on multiple clicks.

4.5  AJAX - in the grid

How can I implement AJAX in the Zapatec Grid?

see JSON Demo

The Zapatec Grid has built in functionality for AJAX fetching after the page had been displayed. You just define the source as either JSON or XML and sourceType to be a server side file.

Last modified: Friday, January 13th, 2006 4:51:31pm



Contact Us | Employment

© 2004 Zapatec, Inc.