-
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: [ {}, ... ], // omit searchitems if you do not want the Flexigrid to have a search bar
....
});
... 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 // true if you want this column initially hidden
Omitting hide is the same as setting it to false. You can offer quite a few less interesting columns in your flexigrid and but have them initially hidden. The user can reveal those additional columns if they are interested. For example, in a flexigrid of customers, you might not want to show the customer's roommate's wife's father's telephone number. But that column would be there, initially hidden, so the user could still access it if necessary.
If you include searchitems in the Flexigrid configuration, then a Search bar will appear at the bottom of the Flexigrid, which the user can unfold and use.
The searchitems option is an Array of objects that specifies the items present in the Search menu. The order of the elements of the searchitems array determines the order they appear in the Search dropdown menu.
display: ..., // the name that appears in the search dropdown menu for the user to pick from
name: ..., // passed to the server as qtype when the user actually does a 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 when you unfold the search bar at the bottom of the Flexigrid.
Each object specifies a display which is a caption the user will see in a dropdown menu, if the user unfolds the Search bar.
If the user does a search, the name of a searchitems object is what is passed to the server as qtype, and what the user types in to search for will be passed as the query parameter.
A simple way to fill out searchitems is to pass some of the same columns you used in colModel. That way each item in the search menu means to search a column. But how qtype and query are interpreted is up to the server. See some examples below for qtype and query.
If you do offer searchitems to the user in your Flexigrid, there is no special requirement to offer every column from colModel. Suppose your Flexigrid is a table of Customer Orders. One of the columns may be the order total, summed from the total of order detail records. Thus it may not be possible, or may not be simple to implement, or may not be desirable to offer a search on the order total column.
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) 'customerName' the column name to search, if using search
query: (string) 'smith' the value to search for if using search
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.
The qtype and query only have a value if the user has unfolded the search bar and entered a search value. This can only happen if you have used searchitems to offer the user a choice of one or more things to search for.
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 you had a Flexigrid displaying Projects. Each row represents one project. One of your searchitems could be titled "Projects Active On Date" (as it's display value), and also have a novel name value like projectActiveOn. This would appear in the dropdown list of search items. When the server receives a qtype of projectActiveOn, it could parse the query value string to be a date, and then do a query WHERE projectBegin <= queryDate AND projectEnd >= queryDate, to return only project rows that were active on that date.
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>
colModel was explained above in Part 1.
showTableToggleBtn should be true to show a fold/unfold button in the upper-right corner of the Flexigrid. If you don't want this control to appear, then set showTableToggleBtn as false.
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.