Zapatec AJAX Grid Manual

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

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

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

<!-- Javascript Zapatec utilities file -->  
<script type="text/javascript" src="../utils/zapatec.js"></script>
<!-- Javascript file to support grid -->
<script type="text/javascript" src="src/zpgrid.js"></script>

<!-- optional Javascript file needed only for editable grids -->
<script type="text/javascript" src="src/zpgrid-editable.js"></script>

<script src="zapatec/utils/utils.js" type="text/javascript"></script>
<script src="zapatec/utils/transport.js" type="text/javascript"></script> 
<script src="zapatec/utils/zpwidget.js" type="text/javascript"></script> 
<script src="zapatec/zpgrid/src/zpgrid.js" type="text/javascript"></script>

<script type="text/javascript" src="../utils/zapatec.js"></script>
<script type="text/javascript" src="src/zpgrid.js"></script>

In the HTML page, create a new Zapatec.Grid object to convert a HTML table to a Zapatec Grid. The following example creates a Zapatec grid in a DIV whose ID is gridContainer from the data in a table whose ID is "gridSourceTable":

<div style="display: none">
  <!-- Define grid data source table -->
  <table id="gridSourceTable">
    ...
  </table>
</div>

<!-- Define grid container -->
<div id="gridContainer"></div>

<script type="text/javascript">
  // Initialize grid
  var objGrid = new Zapatec.Grid({
    // Use HTML table with id "gridSourceTable" as grid data source
    source: 'gridSourceTable',
    sourceType: 'html',
    // Use "winxp" theme
    theme: 'themes/winxp.css',
    // Put the grid into element with id "gridContainer"
    container: 'gridContainer',
    // Use paging, display 20 rows per page
    rowsPerPage: 20
  });
</script>

Using your editing or FTP program, copy or move your web page and the entire tree folder to any directory in the web server public area.

Using your web browser, navigate to the web page created to include the Zapatec AJAX Grid. You have set up the most basic version of the Zapatec AJAX Grid! Now, you can change this highly adaptable application with the help of multiple features provided.

For a grid that fetches data from the server, be aware that the server must specify the charset if it serves pages containing extended ASCII or UNICODE characters. This is accomplished by specifying the appropriate content-type header, such as Content-type: text/plain; charset=utf-8 or Content-type: text/plain; charset=windows-1251.

For a PHP script, an example would be:

<? header("Content-type: text/plain; charset=utf-8") ?>

For an XML data source, you should also set encoding inside the document:

<?xml version="1.0" encoding="utf-8"?>

If you want to convert your HTML table into a grid, there is no need to adjust your HTML page by inserting additional modules. zpgrid-html.js is included by default inside zpgrid.js.

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

<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>
</table>
</div>

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

<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>

<td class="zpGridTypeInt zpGridTypeHidden" . . . >Item</td>

<td width="10px" class="zpGridTypeInt zpGridTypeNosort">Item</td>

<td width="10px" class="zpGridTypeInt 
zpGridTypeNosort zpGridTypeSortBy2">Item</td>

JSON format can be used as a source for your grid. JSON is a lightweight data-interchange format. It provides the quick performance during initial processing of the data performed by the grid. It can represent integer, real number, string, an ordered sequence of values, and a collection of name/value pairs.

JSON format is an internal grid format. zpgrid-html.js and zpgrid-xml.js convert data in JSON format.

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

source: oGridSource,
sourceType: 'json',

"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"}
   ],

"rows": [
      {"cells":[
        {"v": "10/03/2005"},
        {"v": "SMITH-001"},
        {"v": "Smith, John"},
        {"v": 123},
        {"v": -100.01, "style": "color: #ff0000"}
      ]}   

fields:
  [
    {
      ...
      hidden: true
      ...
    },
    ...
  ],

fields:
  [
    {
      ...
      columnWidth: "10px",
      nosort: true,
      ...
    },
    ...
  ],

To use XML format as a data input format you should have zpgrid-xml.js module attached to the head tag of your web page.

<script type="text/javascript" src="../src/zpgrid-xml.js"></script>

zpgrid-xml.js is a plugin for Zapatec Grid that makes it possible to input data from XML source.

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

<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>

<field style="font-weight: bold">

<field hidden="true" . . . >

<field width="10px"  nosort="true" sortbycolumn="2" . . . >

<?xml version="1.0"?>
<grid norefresh="true">
   <table>
     <atkey>Primary key value</atkey>
     <atid>0</atid>
     <afterkey>Primary key value</afterkey>
     <afterid>0</afterid>
     <howmany>0</howmany>
     <rows>
       <row style="background: #eee">
         <cell style="color: #f00">Value</cell>
         ...
       </row>
       ...
     </rows>
   </table>
   ...
 </grid>

The source sets the origin of the grid data. The source is a required option, unless you are using the container option to specify the source.

This option is coupled with the sourceType option. Depending on the value of the sourceType option, the source is either a string or an object. If it is a string, the source value is the ID of the container, the URL, the external filename or string containing the HTML that defines the table. If it is an object, the source is a TABLE DOM object, a JSON object, or XMLDocument object.

Possible source values include:

For information on how to define HTML table as a source for your grid, refer to the Defining HTML as an Input Data Format for the Grid section.

For information on how to define JSON table as a source for your grid, see the Defining JSON as an Input Data Format for the Grid section.

For information on how to define XML table as a source for your grid, see the Defining XML as an Input Format for the Grid section.

Here are some examples:

From the table ID (From the Phone Bill Demo):

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

You can also define the grid source as a table object using getElementById():

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

From a JSON external file (From the JSON Account Demo):

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

From a JSON Object (From the Yahoo Demo):

source: oGridSource,
sourceType: 'json',

From an XML File:

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

The sourceType sets the type of the grid data source.

The sourceType option is used with the source option to specify how the source should be processed.

Valid source types are: 'html', 'html/text', 'html/url', 'json', 'json/url', 'xml', and 'xml/url'.

The container specifies the element or ID of the element that contains the grid. The container is required, unless you are using the source option to specify the source of the grid data.

If the callbackHeaderDisplay and the callbackRowDisplay or callbackDataDisplay options are defined, the grid is drawn using the functions that ignore the container option.

The container option can be used instead of the source option.

If the source option is not defined, the first child element of the container is used as the source. If the first child is not a table, the source will not be found and an error message will display.

This is the element or id of the element that contains the grid header.

It is used with the container option to separate the header from the grid when you want grid data to be scrollable vertically with the header always visible.

See the Scrolling Grid Demo.

This is the element or id of the element that contains grid totals.

It is used with the container option to separate the totals from the grid when you want grid data to be scrollable vertically with the totals always visible. See Scrolling Grid Demo.

This is the element or id of the element that contains grid pagination. It is used with the container and rowsPerPage options to separate pagination from the grid. See the Scrolling Grid Demo.

Element or ID of the element that is parent for all grid containers. Used to determine dimensions of the grid when it has several containers. Used only with fitIntoParent when grid has several containers. Default value - parent of the container.

If border div is a parent node for data container, you don't need to specify it in configuration. Otherwise, it must be passed with border config option.

By default its value is null that is in most cases treated as false.

If true - grid will be fitted dynamically into parent of the border .

If element to fit into is the parent node for border, you can just set fitIntoParent to true. Otherwise, you must pass it with fitIntoParent config option.

The theme option specifies the CSS used to present the Grid.

The string argument is the name of the theme:

theme : 'winxp2'

or the absolute or relative path to the theme file

theme : 'zapatec/zpgrid/themes/winxp.css'

The theme name is case-insensitive. Some themes are provided in the themes folder. You can create your own themes after them.

If the theme option is not specified, the default.css file in the themes folder is used.

To speed up grid initialization you can manually include theme CSS file into your page:

<link href="zapatec/zpgrid/themes/winxp.css" rel="stylesheet" />

If link is set explicitly and href attribute value of the link and theme config option value are equal, grid will not attempt to load theme assuming that it is already loaded with the link.

This option defines the path to the themes directory. If the path to the theme is passed as the argument to the theme option, the themePath is not required.

If you use predefined themes, you do not need the themePath.

This option specifies the column value on which the grid is sorted when it is first displayed.

See the Stock Performance Demo for an example.

The argument is a zero-based number of the column to sort by.

If the sortColumn option is not set, the initial order in which the grid rows are displayed remains undefined.

This option determines whether the sortColumn is sorted in descending order when the grid is first displayed.

If set to true, the grid is initially sorted in descending order.

This option is used with the sortColumn option. If sortColumn is not set, sortDesc will be ignored.

This option specifies the default column width. The default column width should be a correct CSS value (for example "auto", "100px", etc). Do not use "auto" when having separate containers for header or totals. By default, if you don't have separate container for the headers or totals - the value is "auto". In case they are stored in separate containers - the default value is "100px".

Use this option to define the default row height. The default row height must be a correct CSS value (for example "auto", "1.2em", etc). Do not use "auto" when having some columns fixed.

This option specifies the number of grid rows to be displayed per grid page.

See the Phone Bill Demo for an example.

When set, the rowsPerPage option triggers the display of the pager under the grid. This provides the user with the ability to move forward and backward through the data set.

If this option is not defined, the full grid is displayed.

This option specifies number of columns starting from the left that stay fixed during horizontal scrolling.

This option allows the user to filter data items out of the grid.

See the JSON Demo for an example.

The filterOut option generates a container of checkboxes that represent unique values in the specified column. These checkboxes can be included in a form. The user can select the checkboxes that match these values to include rows in the displayed grid.

The argument is an array of hash with the following properties:

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

If the callback is used, an array of objects is passed. Each object has value and onclick properties. Value is a unique value in the column and onclick is the string used to call the function to filter the grid.

See the Account Filter in the JSON Demo for an example of filtering using a callback.

Use this option to filter your grid by a text value or regular expression. The argument format is the following:

{
   // RegExp object or regular expression string to match,
   regexp: [object or string, optional],
   // Text fragment to search 
   text: [string, optional],
   // Array of column indexes (first one is 0) to search
   columns: [object, optional] 
}

By default, all the columns will be searched.

For details see Filter Based on Text section.

If this option is true, the grid reloads its data on every paging, sorting, filtering, ranging, and search action. It makes sense to use this option together with callbackSource config option defined in Zapatec.Widget class.

For details how to use these options together - see Phone Bill on Demand Demo

If true, horizontal layout is used in standard output. See Horizontal demo.

This option specifies whether the grid should display the original source values or the converted Zapatec Grid Field Type values.

This option affects only the visual presentation of the cell. It does not change the cell value.

If the boolean is used, true shows the original value and false shows the converted value. The default is false.

If the object is used, it has two attributes:

If a funcShow function is defined, the function is called for each cell in the grid. The function should be defined as:

myFuncShow(objCell)

funcShow function will format each cell for display.

See Show Data AS IS Demo for an example.

Use this option to unhide specific columns. Its argument is an object that has two properties: columns and noRefresh. The first of them is an array of integers or integer that specifies zero-based column numbers to show. The second property is a boolean value that tells if grid is to be refreshed after that. This is useful if you want to show some columns while other remain hidden.

This option enables you to hide specific columns. Its argument is an object that has two properties: columns and noRefresh. The first is an array of integers or integer that specifies zero-based column numbers to hide. The second property is a boolean value that tells if grid is to be refreshed after that. This option is useful if you want to hide some columns while other will remain visible.

Use this option to speed up the load time for extremely large grids.

To enable this feature, you must set the dataPrepared option to true and prepare the data in a JSON file in the following format. When this option is used, the grid does not check the input data before populating the grid.

{
  style: [string, optional] table style attribute,
  headerStyle: [string, optional] header table row style attribute,
  fields:
  [
    {
      i: [number] zero based column number,
      title: [string] column title,
      dataType: [string, optional] column data type (default: "string"),
      columnWidth: [string, optional] column width, e.g. "10px", "10em",
      style: [string, optional] header table cell style attribute,
      hidden: [boolean, optional] if true, column will not be displayed, but
       filtering and searching can still be done on this column,
      nosort: [boolean, optional] if true, grid will not be sorted when this
       header is clicked
    },
    ...
  ],
  rows:
  [
    {
      i: [number] row number,
      cells:
      [
        {
          i: [number] zero based column number,
          r: [number] zero based row number,
          v: [any] cell value to display,
          c: [any, optional] cell value to compare,
          o: [any, optional] original cell value,
          style: [string, optional] table cell style attribute
        },
        ...
      ],
      style: [string, optional] table row style attribute
    },
    ...
  ]
}

The v cell property, which is the displayed cell value, is required.

The c and o properties are optional properties that are used when values used for comparison purposes are not identical to the displayed value. The c property is the value to be used for comparison operations. For example:

v: '<b>value</b>',
c: 'value'

The o property is the original value of the cell. An example is a boolean value such as:

v: 'Yes',
c: 1,
o: 'true'

Without the dataPrepared option, rows and columns are numbered automatically. If dataPrepared is true, the server-side script must provide zero-based row and column numbers.

The totals option provides a way to calculate and display aggregates in grid columns. The value of the option is an array of four-part specifications for the aggregate. The format of the option is:

totals: [
      {
        column: [columns subject to this aggregate],
        callback: callback to apply,
        label: label of the row displaying the aggregate,
        labelColumn: column in which to display the label
      }, . . .
 ]

See also callbackTotalsDisplay and callbackTotalDisplay .

If true, the active rows will be marked with a different color depending on the theme applied. This option is ignored when callback functions are used to display a grid.

If true, the active cells will be marked with a different color depending on the theme selected. Ignored when callback functions are used to display the grid.

By default, a user can select rows in a grid. Set selectRows to false to prevent row selection.

If true, selected rows are marked in color. The color used depends on the theme of the grid. Ignored when callback functions are used to display the grid.

By default, a user can select cells in a grid. Set selectCells to false to prevent cell selection.

If true, selected cells are marked in color. The color used depends on the theme of the grid. Ignored when callback functions are used to display the grid.

If true, the user can use Shift-Click and Ctrl-Click to select multiple rows and multiple cells.

If false, the user can select only one row or cell at a time. See the Phone Bill Example with Multiple Select Demo.

This is a callback to convert a source cell data value. Takes in two arguments: grid instance and cell object. The value returned will be assigned to the cell data.mixedValue and data.compareValue properties. In case of need, cell data property can be modified directly in this function.

This feature is useful when the source data has metrics or notations (such as lbs, oz, MB, GB) and you need to quantify these metrics.

For example, the source data may have a column DataSize, where each cell contains a number and MB or GB. To properly quantify these cells, the notation of 20 MB needs to be converted to a number. This is where the convert option is useful. In this example, the grid may display the original cell value "20 MB" and the callback converts it to an internal cell value: 20 X 1024 X 1000000 = 20480000000.

See Show Data AS IS Demo to see this feature in action.

This callback dynamically changes the style of a cell based on its contents.

For example, imagine defining the callback myStyle. The function signature is as follows:

funcStyle(objCell)

The function returns a string that describes the inline style to be applied to this cell. Or, it returns undefined if there is no style change to apply.

In the Show Data AS IS Demo, a special style for the Price column is dynamically generated. If the Price value is negative, the value is displayed in red. All prices are right aligned.

/*
   Dynamically change the style of a cell based on the contents.
   oCell - cell object
   return undefined if NO change to style
   return the inline style that should be applied to this cell

   This function will set the style of the FLD_PRICE column.
   Any negative price is set to RED.   
   All prices aligned right.
*/   
function myStyle(oGrid, oCell) {
  if (oGrid.getCellId(oCell) != FLD_PRICE) {
    return;
  }
  if (oGrid.getCellValue(oCell) < 0) {
    return 'color: red; text-align: right;'
  }
  return 'text-align: right;'
}

This is the callback that displays the grid headers.

It offers the ability to perform complex data manipulation before presenting the grid. Used together with the callbackRowDisplay or callbackDataDisplay options, this option provides an alternative method of displaying the grid.

If the callbackHeaderDisplay and callbackRowDisplay or callbackDataDisplay options are defined, the grid is drawn using these functions. In this case, the container option is ignored.

See the Compare Rows demo for an example.

Takes in one argument: grid instance. Then it can get any data using appropriate methods of the grid.

This is the callback that displays all the data in the grid at once.

If used, this callback offers the ability to perform complex data manipulation before presenting the grid.

If you define callbackDataDisplay, do not define the callbackRowDisplay option. These two functions are similar, except that callbackDataDisplay displays all the rows at once and callbackRowDisplay displays them one row at a time.

If the callbackHeaderDisplay and callbackDataDisplay options are defined, the grid is drawn using these functions. In this case, the container option is ignored.

Takes in two arguments: grid instance and array of row objects to display.

This is the callback that displays a grid row. It is called once for each row in the grid to be displayed.

If used, this callback offers the ability to perform complex data manipulation before presenting the grid.

If you define callbackRowDisplay, do not define the callbackDataDisplay option. These two functions are similar, except that callbackDataDisplay displays all the rows at once and callbackRowDisplay displays them one row at a time.

If the callbackHeaderDisplay and callbackRowDisplay options are defined, the grid is drawn using these functions. In this case, the container option is ignored.

Takes in two arguments: grid instance and row object to display.

This is your callback function to implement custom pagination for displaying a multi-page grid. See the Phone Bill Example with Custom Pagination Demo for a custom implementation that offers the user a slider to control pagination.

Callback function to display totals. Used together with callbackHeaderDisplay , callbackRowDisplay and callbackDataDisplay options as alternative way to display the grid, but also can be used separately as a replacement for standard totals.

Receives Zapatec.Grid object and array of row objects for totals. If totals option is not set, this option still can be used, but it receives undefined instead of array of rows.

Callback function to display totals row. Called for each totals row. Used together with callbackHeaderDisplay , callbackRowDisplay and callbackDataDisplay options as alternative way to display the grid, but also can be used separately as a replacement for standard totals. Ignored when callbackTotalsDisplay is set.

Receives Zapatec.Grid object and totals row object.

Deprecated.

Use gridRefreshed event instead.

This is the callback function to invoke when a grid row is selected either by a user click or programmatically. Takes in two arguments: grid instance and the selected row object.

This is the callback function to invoke when a grid cell is unselected. Takes in two arguments: grid instance and the unselected cell object.

Callback function to call when grid row is clicked. Receives Zapatec.Grid object and row object as parameters.

Callback function to call when grid row is double-clicked. Receives Zapatec.Grid object and row object as parameters.

This is the callback function to invoke when a grid cell is selected either by a user click or programmatically. Takes in two arguments: grid instance and the selected cell object.

If this option is defined, the callbackRowSelect option is ignored.

This is the callback function to invoke when a grid cell is unselected. Takes in two arguments: grid instance and the unselected cell object.

If this option is defined, the callbackRowUnselect option is ignored.

Callback function to call when grid cell is clicked.

Receives Zapatec.Grid object and cell object.

If this option is defined, above callbackRowOnClick option is ignored.

Callback function to call when grid cell is double clicked.

Receives Zapatec.Grid object and cell object.

If this option is defined, above callbackRowOnDblClick option is ignored.

This callback function is invoked to attach an editor to a grid column, row, or cell in an editable grid. The arguments to the callback are references to the grid object and edited column, row, or cell object to which the editor is to be attached.

The signature for the callback attached to a cell in our demo is:

function edit(objGrid, objCell)

To attach an editor to a row, use the Zapatec.Grid's getRowByCell(objCell) method to access the row. To attach an editor to a column, use the getFieldByCell(objCell) method to access the column.

When you attach an editor to a grid, the grid must be editable - created with the Zapatec.EditableGrid() constructor - and the cell(s) to which the editor is attached must not have been specified as not editable.

Callback function to call when grid cell is turned into read-only state. Receives Zapatec.EditableGrid and cell object parameters.

This option specifies the URL of server-side script that is used for checking and saving the individual cell. See Editable Autosave Cell.html demo.

Callback function that is used to check the server-side script response. It receives following object:

{
response: [object] XMLHttpRequest object
}

If the cell was saved successfully, callback function must return true.

See Editable Autosave Cell.html demo.

Array with external editors callbacks to use instead of standard editing tools based on per column basis.

The passed object has the following format:

[
    {
      column: [number],
      editor: [object],
      callback: [function]
    },
    { 
      column:  [number],
      editor:  [object],
      callback: [function]
    },
    ...
] 

Each parameter is optional. If you don't specify the column parameter - all columns will be edited by this callback/editor and the rest of the array members will be ignored. Callback function receives cell value for editing.

See Attaching a Special Editor section for details and editors.html demo.

Is fired when the grid initialization is completed.

Is fired when grid refresh was started. For example: right after sorting or filtering procedure started.

Is fired when grid refresh has been executed. For example: when sorting or filtering procedure completed.

Is fired before splice or query is started.

Is fired after splice or query is completed.

Is fired before filtering is started.

Is fired when filtering is completed.

Is fired after standard output is used and column was resized manually. Event listener receives two arguments: zero-based visible column number and width increment in pixels. Width increment can be negative.

Used only for editable grid.

Is fired before grid cell is turned into editable state and after callbackCellEdit was called. Event listener receives edited cell object as argument.

Is fired before turning cell into read-only state if it was changed.

Event listener receives the following object:

{
   cell: [object] edited cell,
   previousState: [object] cell before editing
}

Is fired when HTTP success response is received from the server and callbackAutoSaveCell option is not defined, or callback function returns true.

Event listener receives the following object as an argument:

{
   cell: [object] cell object,
   request: [object] XMLHttpRequest object
}

Is fired when HTTP error response is received from the server, or callbackAutoSaveCell option is defined and callback function doesn't return true.

Event listener receives the following object as an argument:

{
  cell: [object] cell object,
  error : [object] error object
}

Is fired when grid gets changed as a result of cell editing. Event listener receives edited cell object as argument.

The Zapatec Grid can automatically define controls for filters.

A control provides a way for a user to filter the data displayed in a grid based on column contents and user-provided criteria.

Typically, a filter is created when the user enters information into the control and clicks the button to apply the filter.

The developer defines the controls for a filter using the filterOut option.

A Zapatec grid supports three types of controls: based on value, based on range or based on text. A selection control appears as a set of checkboxes representing unique values for a column in the grid. A range control can appear as two fields in which the user enters values to specify the minimum and maximum values of the range to display. It can also appear as a slider. See the Zapatec Slider documentation for information about offering the user a Zapatec Slider to define a range of values. Text filter can be a simple text or a regular expression depending on arguments passed to the setFilter method.

filterOut: [
  // Filter Rate Period
  {
    // Use 4-th column (first column number is 0)
    column: 3,
    // Put checkboxes into element with id "filterOutRate"
    container: 'filterOutRate',
    // This will press "Filter" button for you if you changed range of items
    // or minutes and forgot to press it
    onclick: 'filter(this.form)'
  },
  // Filter Minutes
  {
    // Use 6-th column (first column number is 0)
    column: 5,
    // Sort descending
    sortDesc: true,
    // Put checkboxes into element with id "filterOutMinutes"
    container: 'filterOutMinutes',
    // This will press "Filter" button for you if you changed range of items
    // or minutes and forgot to press it
    onclick: 'filter(this.form)'
  }
]

<fieldset>
  Filter Rate Period<div id="filterOutRate"></div>
</fieldset>

<fieldset>
  Filter Minutes<div id="filterOutMinutes"></div>
</fieldset>

/*
 * Called when "Debits" button is clicked. Limits range of Amount to positive
 * numbers.
 */
function limitRangeDebits(form) {
  if (objGrid) {
    objGrid.limitRange({
      column: 4,
      min: 0,
      max: Infinity
    });
  }
}

/*
 * Called when "Credits" button is clicked. Limits range of Amount to negative
 * numbers.
 */
function limitRangeCredits(form) {
  if (objGrid) {
    objGrid.limitRange({
      column: 4,
      min: -Infinity,
      max: 0
    });
  }
}

/*
 * Called when "Debits" button is clicked. Limits range of Amount to/**
 * Range of items slider "onChange" event listener. Called when slider position
 * is changed programmatically.
 */
function onRangeOfDatesChange(iMinValue, iMaxValue) {
  // Display scale
  document.getElementById('rangeOfDates').innerHTML =
   fromTimestamp(iMinValue) + ' - ' + fromTimestamp(iMaxValue);
}

/*
 * Range of items slider "newPosition" event listener. Called when slider is
 * drag-n-dropped.
 */
function onRangeOfDatesDrag(iMinValue, iMaxValue) {
  onRangeOfDatesChange(iMinValue, iMaxValue);
  // Limit range of items
  objGrid.limitRange({
    column: 1,
    min: iMinValue,
    max: iMaxValue
  });
}

/*
 * Range of minutes slider "onChange" event listener. Called when slider
 * position is changed programmatically.
 */
function onRangeOfMinutesChange(iMinValue, iMaxValue) {
  iMinValue = Math.round(iMinValue);
  iMaxValue = Math.round(iMaxValue);
  // Display scale
  document.getElementById('rangeOfMinutes').innerHTML =
   iMinValue + ' - ' + iMaxValue;
}

/*
 * Range of minutes slider "newPosition" event listener. Called when slider is
 * drag-n-dropped.
 */
function onRangeOfMinutesDrag(iMinValue, iMaxValue) {
  onRangeOfMinutesChange(iMinValue, iMaxValue);
  // Limit range of items
  objGrid.limitRange({
    column: 5,
    minValue: iMinValue,
    maxValue: iMaxValue
  });
}

function filter(oForm) {
  if (objGrid) {
    if (oForm.isRegExp.checked) {
      objGrid.setFilter({
        regexp: oForm.textFilter.value
      });
    } else {
      objGrid.setFilter({
        text: oForm.textFilter.value
      });
    }
  }
  return false;
}

To clear all the filterouts, ranges and text filters in the grid, use the Zapatec.Grid.prototype.resetFilters method:

Zapatec.Grid.prototype.resetFilters();

See the Stock Performance Demo to try out the grid sorting capabilities.

The grid column is sorted based on the column types.

You can restrict the capabilities of individual columns by:

For information on how to restrict individual columns using HTML input, see Restricting Individual Columns Using HTML Input section.

For information on how to restrict individual columns using JSON input, see Restricting Individual Columns Using JSON Input section.

For information on how to restrict individual columns using XML input, see Restricting Individual Columns Using XML Input section.

See the Phone Bill Example with Hidden Column Demo for an example of hidden column.

The Zapatec Grid has built-in functionality for AJAX fetching after the page has been displayed. To enable AJAX in the grid, define the source as the relative or absolute URL of a server-side script or static file and sourceType as 'json/url', 'xml/url' or 'html/url'.

There are times when you want to show the source data in its original format (as is) and other times you want the Zapatec Grid to convert your data format.

The conversion feature allows you to convert source data dynamically. This is especially useful for migrating legacy tables to the Zapatec Grid using only the client. It is not necessary to convert the data on the server. You can use the convert functions on the client-side Zapatec Grid to convert and migrate a server-side table to a Zapatec grid.

See the Show Data AS IS Demo.

In this demo, the first column, Disk Size, displays the disk size with the MB or GB designation. The internal value of this cell is converted to a number, a zpGridTypeFloat. The internal value is used for sorting and other grid functions.

The next column, Hours, is similar. The cell is presented in terms of weeks, days, and hours. The internal value is an integer, zpGridTypeInt, which stores the call value in terms of hours.

You can see the original and converted values for every column in the grid by selecting the column and the appropriate checkbox indicating which values to display.

Use the show_asis to change the presentation of a grid cell dynamically.

Here is an sample function that converts a grid cell in the price column (FLD_PRICE) of a grid.

function show_data(objCell)
   {
   var value=objCell.data.mixedValue;

   if (objCell.id==FLD_PRICE)
      return formatCurrency(value)

   return objCell.data.origValue;
   }

There may be cases when the Zapatec grid cannot recognize the raw data format, consequently, will not be able to use the show_asis option to convert it.

In these cases, to convert the data you can override the constructor for the column type of the unconventional data. The Custom Parse Demo illustrates how to do this for the GDP column in its grid.

This demo overrides the standard convertInteger and convertFloat constructors with special-purpose constructors that convert the strings in the original data - "trillion", "billion", and "million" - to their numerical values. This enables the grid to parse raw data in the form "937.6 billion" and display its numeric value, 937600000000.

Both constructors use a custom utility function, str2num, which converts these strings to numbers:

function str2num(strNum, num)
 {
 if (/million/i.test(strNum))
  num *= 1000000
 if (/billion/i.test(strNum))
  num *= 1000000000
 if (/trillion/i.test(strNum))
  num *= 1000000000000
 if (/ MB/.test(strNum))
  num *= 1000000
 if (/ GB/.test(strNum))
  num *= 1000000000

 return parseInt(num)
 }

The custom convertInteger constructor then uses str2num to perform the conversion:

// Store the original constructor
Zapatec.Grid.prototype.origConvertInteger = Zapatec.Grid.prototype.convertInteger;

/* Create custom constructor to convert the words 
   trillion, billion, million into their numerical values
*/
Zapatec.Grid.prototype.convertInteger = function(objCell) {
  objCell = this.origConvertInteger(objCell);
  
  objCell.v = objCell.c = str2num(objCell.o, objCell.v);
  return objCell;
};

The custom convertFloat constructor is similar:

Zapatec.Grid.prototype.origConvertFloat = Zapatec.Grid.prototype.convertFloat;

Zapatec.Grid.prototype.convertFloat = function(objCell) {
  objCell = this.origConvertFloat(objCell);
  objCell.v = objCell.c = str2num(objCell.o, objCell.v);
  return objCell;
};

The funcStyle option allows you to set the style of the grid cell. In the Show Data AS IS Demo , the style for the Price column is dynamically generated. If the Price is negative, the text color is red. All prices are right aligned.

/*
   Dynamically change the style of a cell based on the contents.
   objCell - cell object   
   return undefined if NO change to style
   return the inline style that should be applied to this cell

   This function will set the style of the FLD_PRICE column.
   Any negative price is set to RED.   
   All prices aligned right.
*/   
function myStyle(objCell)
   {      
   if (objCell.id != FLD_PRICE)
      return undefined
   var strStyle;
   if (objCell.data.mixedValue < 0)
      return 'color:red; text-align:right;'

   return "text-align:right;"   
   }

You can migrate legacy tables using the Zapatec Grid. Using client-side only technology, this feature offers next-generation presentation features for traditional data.

You do not have to change any server-side code to do this.

To migrate a table to a Zapatec grid:

See the Show Data AS IS Demo for an example.

If the source table contains HTML tags in a text column, you can direct the grid to ignore the HTML tags in the source column by specifying the zpGridTypeNotags class at the column level. For example, if this tag is applied to a columns:

<th class="zpGridTypeNotags">Symbol</th>

and the source data includes HTML tags:

<td><i>MSFT</i></td>

the <i> </i> tags would be ignored in the grid because this column belongs to zpGridTypeNotags class.

The zpGridTypeNotags class is needed for text data only, as HTML tags are automatically ignored for other data types.

The Zapatec Grid allows you to export grid data to a flat file in CSV (Comma Separated Value) format. You can use different separator than comma as well.

To export the data, call the grid's flatfile() method, which returns a string consisting of the grid data in flat file format. This method takes the following arguments:

For example, to export a flat file to the grid in CSV format:

var objGrid = new Zapatec.Grid(...);
var strFlatfile=objGrid.flatfile(',', '\n', 1)

See the Show Data AS IS Demo for an example.

For information on how to export Zapatec grid to the JSON file, see Exporting a Grid to a JSON File section.

A user can make client-side modifications to a Zapatec Grid.

To modify a grid, call the Zapatec.Grid.splice() method. This method takes one object or several objects in an array with the following properties:

Only one of atKey, atRowId, afterKey and afterRowId properties should be defined. If none of them is defined, new rows will be added to the end of grid.

Several input objects can be passed in an array. This is useful when several changes must be done simultaneously.

If several objects are passed in an array, noRefresh property is ignored for all objects except the last.

See the Splice Demo for an example that implements this feature.

Modifications to the grid affect only the client side of the application. It is the developer's responsibility to commit the updates to the server if that is desired.

See Dynamically Modify an XML Grid section for the instructions on how to modify an XML grid.

You can also modify a grid by inserting rows and updating or deleting rows based on the optional search condition of a query. There are different ways to modify a Zapatec grid using a query:

To use the query features, add the zpgrid-query.js file to your header if it is not already there:

<script src="src/zpgrid-query.js" type="text/javascript"></script>

objGrid.query({
  type: 'insert',
  rows: objRows
});

objGrid.query({
  type: 'update',
  values: {
    cells: [
      null,
      null,
      { data: value1 },
      null,
      { data: value2 }
    ]
  }
  where: {
    leftValue: {
      column: 0
    },
    rightValue: {
      value: iValue,
      type: 'integer'
    },
    operator: '=='
  }
});

objGrid.query({
  type: 'delete',
  where: {
    leftValue: {
      column: 0
    },
    rightValue: {
      value: iValue,
      type: 'integer'
    },
    operator: '=='
  }
});