-
Notifications
You must be signed in to change notification settings - Fork 537
Home
NOTE: I've cobbled up this documentation based on my own observations, because the project authors have yet to provide any. Thus, there may be mistakes, misinterpretations and omissions. --ppar
To convert an existing HTML <table> element to a Flexigrid table, call
jQuery('#my_table').flexigrid({
option1: value,
option2: value,
....
});
... where '#my_table' is a jQuery selector specifying the table to convert. The
element is replaced with the Flexigrid UI. See "Configuration Options" below for a list of available options.To insert a Flexigrid table in the document, call
jQuery('#my_container').flexigrid({
url: (URL to fetch data from)
dataType: 'json'|'xml',
method: 'POST'|'GET',
colModel: [ {}, ... ],
searchitems: [ {}, ... ],
....
});
... where '#my_container' is a jQuery selector specifying where the table should appear. See "Configuration Options" below for a list of available options.
The colModel option is an Array of objects that specifies the columns present in the table. Each object describes one column and should contain the following attributes:
display: ...,
name: ...,
width: ...,
sortable: false,
align: 'left'|'center'|'right',
hide: false
The searchitems option is an Array of objects that specifies the columns present in the Search menu. The order of the elements of the searchitems array determines the order they appear in the Search dropdown menu. Each object is a subset of the same information that appears in 'colModel'.
display: ..., // the name that appears in the dropdown menu, probably should be the same as in colModel
name: ..., // should exactly match some colModel name that this search item will search
isdefault: true // only one column should have this set to true, other columns can omit it
The searchitems element which has isdefault set to true will be the search item that is initially selected if you unfold the search bar at the bottom of the Flexigrid.
When loading rows from an external data source, Flexigrid will pass the following HTTP (GET / POST) parameters:
page: (int) Page number being requested
rp: (int) Number of rows requested (rows per page)
sortname: (string) <name of column to sort the data by>
sortorder: (string) 'asc'|'desc' (?)
qtype: (string) 'name' the column name to search, if using search
query: (string) 'smith' the value to search for if using search
The qtype and query only have meaning if the user has unfolded the search bar and entered a search value.
Note: a server acting as an external data source can apply an expanded notion of what the sortname / sortorder pair actually means. For example, suppose there are two columns First Name and Last Name. If the user picked to sort by First Name, by clicking the column head for First Name, the server could interpret that to actually mean to sort by First Name + Last Name. Or if the user clicked the Last Name column head as the sort order, the server could interpret that as sort by Last Name + First Name. Some server implementations might construct a SQL query to a database and would use the sortname and sortorder together to construct an appropriate ORDER BY clause.
Note the interpretation of qtype / query is up to the server when using external data. The server could apply an expanded notion of search. For example, if there were a pair of columns Customer ID, Customer Name, then when the user searches either column, the server could return rows that match in EITHER column. The server could interpret the the search to be case insensitive. So if the user searched for "jones", the server could consider the following rows to be a match: A row with User ID "MJones23", a row with User Name "Jane Smith-Jones". The server could implement the search as a prefix search, or an infix search. Eg, either querying upper(substr(colName,1,5))=="JONES", or querying colName LIKE "Jones". Some server implementations might construct a SQL query to a database and would use the qtype and query together to construct an appropriate WHERE clause.
Suppose qtype were a date column. The server could then parse the query value in a variety of different ways to determine what date to match to. (Example, it could accept any of: '23-sep-97', '3/17/28', '2014-06-02') A date (or any other value) might not even have to match a single column. Suppose one of your searchitems was titled "Date within Period" (as it's display value), and also had a novel name value like dateWithinPeriod. This would appear in the dropdown list of search items. When the server receives a qtype of dateWithinPeriod, it could parse the query value string to be a date, and then do a query WHERE periodBegin <= queryDate AND periodEnd >= queryDate.
Flexigrid expects a JSON data source to return a JSON object in a format like below.
Properties that should be present in the 'cell' objects depend on the colModel option passed in Flexigrid initialization (see above).
{
"page": 1,
"total": 239,
"rows": [
{
"id": "ZW",
"cell": {
"name": "Zimbabwe",
"iso": "ZW",
"printable_name": "Zimbabwe",
"iso3": "ZWE",
"numcode": "716"
}
},
{
"id": "ZM",
"cell":{
"name": "Zambia",
"iso": "ZM",
"printable_name": "Zambia",
"iso3": "ZMB",
"numcode": "894"
}
},
{
"id": "YE",
"cell":{
"name": "Yemen",
"iso":"YE",
"printable_name": "Yemen",
"iso3": "YEM",
"numcode":"887"
}
}
]
}
....
<rows>
<page>2</page>
<total>239</total>
<row id='AZ'>
<cell><![CDATA[AZ]]></cell>
<cell><![CDATA[Azerbaijan]]></cell>
<cell><![CDATA[Azerbaijan]]></cell>
<cell><![CDATA[AZE]]></cell>
<cell><![CDATA[31]]></cell>
</row>
<row id='BA'>
<cell><![CDATA[BA]]></cell>
<cell><![CDATA[Bosnia and Herzegovina]]></cell>
<cell><![CDATA[Bosnia and Herzegovina]]></cell>
<cell><![CDATA[BIH]]></cell>
<cell><![CDATA[70]]></cell>
</row>
....
</rows>
These are the configuration options, their default values and descriptions as found in flexigrid.js. Based on the example code on http://flexigrid.info/, it appears this list is not exhaustive. The code is reformatted for readability.
height: 200, // default height
width: 'auto', // auto width
striped: true, // apply odd even stripes
novstripe: false,
minwidth: 30, // min width of columns
minheight: 80, // min height of columns
resizable: true, // allow table resizing
url: false, // URL if using data from AJAX
method: 'POST', // data sending method
dataType: 'xml', // type of data for AJAX, either xml or json
errormsg: 'Connection Error',
usepager: false,
nowrap: true,
page: 1, // current page
total: 1, // total pages
useRp: true, // use the results per page select box
rp: 15, // results per page
rpOptions: [10, 15, 20, 30, 50], // allowed per-page values
title: false,
idProperty: 'id',
pagestat: 'Displaying {from} to {to} of {total} items',
pagetext: 'Page',
outof: 'of',
findtext: 'Find',
params: [], // allow optional parameters to be passed around
procmsg: 'Processing, please wait ...',
query: '',
qtype: '',
nomsg: 'No items',
minColToggle: 1, // minimum allowed column to be hidden
showToggleBtn: true, // show or hide column toggle popup
hideOnSubmit: true,
autoload: true,
blockOpacity: 0.5,
preProcess: false,
addTitleToCell: false, // add a title attr to cells with truncated contents
dblClickResize: false, // auto resize column by double clicking
singleSelect: true, // false to multi-select of several rows by ctrl-click
onDragCol: false,
onToggleCol: false,
onChangeSort: false,
onDoubleClick: false,
onSuccess: false,
onError: false,
onSubmit: false, // using a custom populate function
Additional configuration options that flexigrid seems to understand
colModel: {},
showTableToggleBtn: true|false: to show/hide a fold/unfold button in the upper-right corner
sortname: (string) <initial name of column to sort the data by>
sortorder: (string) 'asc'|'desc' <initial sort order>
sortname is the initial name of a column to sort by. The Flexigrid will initially highlight this column as the sort order. The name of this column will be passed in the query parameters if using an external data source (see above: Query Parameters for External Data Sources). The server should return rows sorted by this column name.
sortorder is the initial value to pass to sort order in the query parameters if using an external data source.