zpgrid-core.js

zapatec suite 最新版 20070204,非常棒的ajax widgets 工具包

/**
 * @fileoverview Zapatec Grid core. Provides base grid features: sorting,
 * filtering, ranges, search, adding and removing rows, pagination, selection,
 * JSON input format, output using callback functions. Can be used alone if data
 * types and standard output functions are not needed.
 *
 * <pre>
 * Copyright (c) 2004-2007 by Zapatec, Inc.
 * http://www.zapatec.com
 * 1700 MLK Way, Berkeley, California,
 * 94709, U.S.A.
 * All rights reserved.
 * </pre>
 */

/* $Id: zpgrid-core.js 7649 2007-08-03 14:15:03Z alex $ */

// Emulate window.event in Mozilla for certain events
Zapatec.Utils.emulateWindowEvent(['mousedown', 'mouseup', 'click', 'dblclick']);

/**
 * Grid core.
 *
 * <pre>
 * <strong>Input data formats:</strong>
 *
 * <strong>JSON:</strong>
 *
 * {
 *   style: [string, optional] table style attribute,
 *   headerStyle: [string, optional] header table row style attribute,
 *   fields:
 *   [
 *     {
 *       i: [number] zero-based column number, <b>dataPrepared</b> specific,
 *       title: [string, optional] column title,
 *       dataType: [string, optional] defines which standard or custom data type
 *        to use for cell conversion (if not specified, no conversion is done),
 *       columnWidth: [string, optional] column width, e.g. "10px", "10em",
 *       style: [string, optional] header table cell style attribute,
 *       span: [number, optional] how many columns to span,
 *       spanTitle: [string, optional] span title,
 *       spanStyle: [string, optional] span 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,
 *       sortByColumn: [number, optional] zero-based number of column to use for
 *        sorting,
 *       hiddenValues: [object, optional] array of hidden values - rows
 *        conaining these values in the column will not be displayed,
 *       minValue: [any, optional] rows containing values in the column lesser
 *        than this value will not be displayed,
 *       maxValue:  [any, optional] rows containing values in the column greater
 *        than this value will not be displayed,
 *       regexpFilter: [string, optional] rows where column value don't match
 *        this regular expression will not be displayed,
 *       textFilter: [string, optional] rows which don't contain this pattern
 *        in the column value will not be displayed,
 *       columnRange: [object, optional] see {@link Zapatec.Grid#getColumnRange}
 *     },
 *     ...
 *   ],
 *   primaryKey: [number, optional] number of column to use as primary key,
 *   rows:
 *   [
 *     {
 *       i: [number] zero-based row number, <b>dataPrepared</b> specific,
 *       cells:
 *       [
 *         {
 *           i: [number] zero-based column number, <b>dataPrepared</b> specific,
 *           r: [number] zero-based row number, <b>dataPrepared</b> specific,
 *           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,
 *           colspan: [number, optional] number of columns this cell spans,
 *           rowspan: [number, optional] number of rows this cell spans
 *         },
 *         ...
 *       ],
 *       style: [string, optional] table row style attribute
 *     },
 *     ...
 *   ],
 *   totalRows: [number, optional] <b>dataOnDemand</b> specific,
 *   displayedRows: [number, optional] <b>dataOnDemand</b> specific,
 *   currentPage: [number, optional] <b>dataOnDemand</b> specific
 * }
 *
 * "i" and "r" properties are required when <b>dataPrepared</b> config option is
 * true. When <b>dataPrepared</b> is false, they are overwritten by automatic
 * column and row numbers.
 *
 * "c" and "o" properties may be useful when column "dataType" is not set. Also
 * they are required when <b>dataPrepared</b> config option is true and their
 * values differ from the value of "v" property of the cell. Anyway, they
 * shouldn't be set if their values are equal to the value of "v" property of
 * the cell.
 *
 * "totalRows" property is used to pass total number of rows in the grid when
 * <b>dataOnDemand</b> config option is used.
 *
 * "displayedRows" property is used to pass number of displayed rows when
 * <b>dataOnDemand</b> config option is used and filter is applied. If filter
 * is not applied and there are no hidden rows, should be equal to totalRows.
 *
 * "currentPage" property is used to pass zero-based current page number when
 * <b>dataOnDemand</b> config option is used.
 *
 * "totalRows", "displayedRows" and "currentPage" properties are required when
 * <b>dataOnDemand</b> config option is true. When <b>dataOnDemand</b> is false,
 * they are ignored.
 *
 * "dataType" property requires zpgrid-convert.js module that is included by
 * default.
 *
 * "hiddenValues", "minValue", "maxValue", "regexpFilter", "regexpFilter",
 * "columnRange" properies are useful when <b>dataOnDemand</b> config option is
 * true. See phone_ondemand.html demo.
 *
 * <strong>HTML:</strong>
 * (requires zpgrid-html.js that is included by default)
 *
 * <xmp>
 * <table style="border: 1px solid #000">
 *   <tbody>
 *     <tr style="background-color: #00f">
 *       <td width="56" class="zpGridTypeDate" style="font-weight: bold"
 *        span="2" spantitle="Date & Time" spanstyle="text-align: center">
 *         Date
 *       </td>
 *       <td width="56" class="zpGridTypeTime" style="font-weight: bold">
 *         Time
 *       </td>
 *       <td>
 *         Title
 *       </td>
 *       <td>
 *         Comments
 *       </td>
 *       ...
 *     </tr>
 *     <tr style="background-color: #ccc">
 *       <td style="background-color: #f00">01/01/2001</td>
 *       <td style="background-color: #f00">09:30AM</td>
 *       <td colspan="2" rowspan="2">Meeting</td>
 *       ...
 *     </tr>
 *     <tr style="background-color: #ccc">
 *       <td style="background-color: #f00">01/01/2001</td>
 *       <td style="background-color: #f00">10:30AM</td>
 *       ...
 *     </tr>
 *     ...
 *   </tbody>
 * </table>
 * </xmp>
 *
 * First row in the source table defines grid columns.
 *
 * To set column data type other than "string", add one of standard or custom
 * data type class names to the "class" attribute of the corresponding cell
 * in the first row.
 * Difference from JSON input format: If data type is not specified, conversion
 * will be done according to the "string" data type.
 *
 * Column width can be set through "width" attribute of the corresponding cell
 * in the first row.
 *
 * Special "zpGridTypeHidden" class makes column hidden and it will not be
 * displayed, but filtering and searching can still be done on this column.
 * This field type can be used alone or in conjunction with other field type,
 * e.g. class="zpGridTypeInt zpGridTypeHidden".
 *
 * Special "zpGridTypeNosort" class makes column header not clickable. Grid will
 * not be sorted when this header is clicked. This field type can be used alone
 * or in conjunction with other field type,
 * e.g. class="zpGridTypeInt zpGridTypeNosort".
 *
 * Special "zpGridTypeNotags" class makes grid skip all tags in the column, and
 * only uses the text. This will facilitate migrating from an existing table
 * to the grid. This field type can be used alone or in conjunction with other
 * field type, e.g. class="zpGridTypeInt zpGridTypeNotags".
 *
 * Special "zpGridTypeSortByN" class makes column use anoter column for sorting.
 * Where N is zero-based column number to use for sorting. This field type can
 * be used alone or in conjunction with other field type, e.g.
 * class="zpGridTypeInt zpGridTypeSortBy2".
 *
 * Special "zpGridTypePrimaryKey" class makes column a primary key for the grid.
 * This field type can be used alone or in conjunction with other field type,
 * e.g. class="zpGridTypeInt zpGridTypePrimaryKey".
 *
 * Attributes "style", "width", "span", "spantitle", "spanstyle", "colspan" are
 * optional.
 *
 * "span" how many columns to span.
 *
 * "spantitle" span title.
 *
 * "spanstyle" span table cell style attribute.
 *
 * Other attributes mean the same as for regular HTML table.
 *
 * <strong>XML:</strong>
 * (requires zpgrid-xml.js that is NOT included by default)
 *
 * <xmp>
 * <?xml version="1.0"?>
 * <grid>
 *   <table style="border: solid black 1px" headerstyle="background: #ccc"
 *    primarykey="0" totalrows="123" displayedrows="89" currentpage="3">
 *     <fields>
 *       <field width="10px" hidden="true" nosort="true" sortbycolumn="2"
 *        style="color: #00f" span="2" spantitle="Span Title"
 *        spanstyle="text-align: center">
 *         <title>Title</title>
 *         <datatype>string</datatype>
 *         <hiddenvalues>
 *           <hiddenval>Hidden value</hiddenval>
 *           ...
 *         </hiddenvalues>
 *         <minlimit>Min displayed value (useful for Slider)</minlimit>
 *         <maxlimit>Max displayed value (useful for Slider)</maxlimit>
 *         <regexpfilter>Regexp filter</regexpfilter>
 *         <textfilter>Text filter</textfilter>
 *         <columnrange>
 *           <minvalue>Min value</minvalue>
 *           <maxvalue>Max value</maxvalue>
 *           <uniquevalues>
 *             <uniqueval>Unique value</uniqueval>
 *             ...
 *           </uniquevalues>
 *         </columnrange>
 *       </field>
 *       ...
 *     </fields>
 *     <rows>
 *       <row style="background: #eee">
 *         <cell style="color: #f00" colspan="2" rowspan="2">Value</cell>
 *         ...
 *       </row>
 *       ...
 *     </rows>
 *   </table>
 * </grid>
 * </xmp>
 *
 * Where "style", "headerstyle", "primarykey", "totalrows", "displayedrows",
 * "currentpage", "width", "hidden", "nosort", "sortbycolumn", "span",
 * "spantitle", "spanstyle", "colspan" attributes are optional.
 *
 * "style" is style attribute of table, row or cell.
 *
 * "headerstyle" is header table row style attribute.
 *
 * "primarykey" defines column number to use as primary key. If not specified,
 * no primary key is created.
 *
 * "totalrows" is total number of rows when <b>dataOnDemand</b> config option is
 * true.
 *
 * "displayedrows" is number of rows displayed when <b>dataOnDemand</b> config
 * option is true.
 *
 * "currentpage" is zero-based current page number when <b>dataOnDemand</b>
 * config option is true.
 *
 * "width" is column width.
 *
 * "hidden=true" attribute makes column hidden and it will not be displayed, but
 * filtering and searching can still be done on this column.
 *
 * "nosort=true" attribute makes column header not clickable. Grid will not be
 * sorted when this header is clicked.
 *
 * "sortbycolumn=N" attribute makes column use anoter column for sorting.
 * Where N is zero-based column number to use for sorting.
 *
 * "span" how many columns to span.
 *
 * "spantitle" span title.
 *
 * "spanstyle" span table cell style attribute.
 *
 * "datatype" tag is optional. Defines which standard or custom data type to use
 * for cell conversion. If not specified, no conversion is done.
 *
 * "hiddenvalues", "minlimit", "maxlimit", "regexpfilter", "textfilter",
 * "columnrange" tags are optional. They are useful when <b>dataOnDemand</b>
 * config option is true. See phone_ondemand_xml.html demo.
 *
 * "colspan" number of columns this cell spans. Works the same as in HTML table.
 *
 * "rowspan" number of rows this cell spans. Works the same as in HTML table.
 *
 * <strong>Possible data types:</strong>
 *
 * -----------------------------------------------------------------------------
 * Name for JSON    |Class name for HTML        |Input data      |Format of
 * and XML formats  |format                     |format          |displayed data
 * -----------------|---------------------------|----------------|--------------
 * string           |zpGridTypeString           |string          |same as input
 * -----------------|---------------------------|----------------|
 * istring          |zpGridTypeStringInsensitive|case insensitive|
 *                  |                           |string          |
 * -----------------|---------------------------|----------------|
 * int              |zpGridTypeInt              |number or       |
 *                  |                           |Infinity        |
 * -----------------|---------------------------|----------------|
 * intGerman        |zpGridTypeIntGerman        |number in       |
 *                  |                           |German format or|
 *                  |                           |Infinity        |
 * -----------------|---------------------------|----------------|
 * float            |zpGridTypeFloat            |number or       |
 *                  |                           |Infinity        |
 * -----------------|---------------------------|----------------|
 * floatGerman      |zpGridTypeFloatGerman      |number in       |
 *                  |                           |German format or|
 *                  |                           |Infinity        |
 * -----------------|---------------------------|----------------|
 * date             |zpGridTypeDate             |string accepted |
 *                  |                           |by builtin      |
 *                  |                           |javascript Date |
 *                  |                           |object          |
 * -----------------|---------------------------|----------------|
 * time             |zpGridTypeTime             |HH:MM:SS        |
 *                  |                           |HH:MM:SS AM/PM  |
 *                  |                           |HH:MM           |
 *                  |                           |HH:MM AM/PM     |
 *                  |                           |HHMMSS          |
 *                  |                           |HHMMSS AM/PM    |
 *                  |                           |HHMM            |
 *                  |                           |HHMM AM/PM      |
 * -----------------|---------------------------|----------------|--------------
 * timestamp        |zpGridTypeTimestampLocale  |integer (number |Date in locale
 *                  |                           |of seconds since|format
 * -----------------|---------------------------|01/01/1970      |--------------
 * timestampMMDDYYYY|zpGridTypeTimestampMMDDYYYY|00:00 GMT)      |MM/DD/YYYY
 * -----------------|---------------------------|                |--------------
 * timestampDDMMYYYY|zpGridTypeTimestampDDMMYYYY|                |DD/MM/YYYY
 * -----------------|---------------------------|                |--------------
 * timestampYYYYMMDD|zpGridTypeTimestampYYYYMMDD|                |YYYY/MM/DD
 * -----------------|---------------------------|----------------|--------------
 * boolean          |zpGridTypeBoolean          |case insensitive|No/Yes
 *                  |                           |0 or 1          |or custom
 * -----------------|---------------------------|f or t          |--------------
 * booleanTF        |zpGridTypeBooleanTF        |false or true   |False/True
 *                  |                           |n or y          |or custom
 *                  |                           |no or yes       |
 * -----------------------------------------------------------------------------
 *
 * <strong>In addition to config options defined in base Zapatec.Widget class
 * provides following config options:</strong>
 *
 * <b>show_asis</b> [boolean] Show data as is.
 * The original data the is imported to the grid needs to be translated to it's field type.
 * In many cases this translation changes the original data.  
 * This option gives control back to the user to define how to display the grid cell
 * Possible values:
 * boolean
 *    true  - Show ALL cells as is