-
Notifications
You must be signed in to change notification settings - Fork 6
TableGear.js
TableGear.js handles client side functions such as sending AJAX requests and sorting data. It is intentionally more simple than TableGear.php, as more of the customization is handled server-side.
Either jQuery 1.4.2 or MooTools version 1.2.1 or greater. Interaction with a database will require some kind of server-side script. This script can be custom written, but obviously this is what TableGear.php is meant for.
To begin working with TableGear.js, you must first link to it and the jQuery/MooTools source file (make sure it comes first), and create a new instance of TableGear using the id of your table.
Your HTML table should have a thead and a tbody element. Sortable columns should have the class name sortable in their header (the th element).
<table id="myTable">
<thead>
<tr>
<th class="sortable">Header1</th>
<th class="sortable">Header2</th>
</tr>
</thead>
<tbody>
<tr>
<td>Data1</td>
<td>Data2</td>
</tr>
<!-- More rows here -->
</tbody>
</table>
<script type="text/javascript" src="/path/to/jqueryormootools.js"></script>
<script type="text/javascript" src="/path/to/TableGear.js"></script>
<script type="text/javascript">
new TableGear("myTable");
</script>That's it! TableGear is now set up to work with your table.
You can use TableGear to make any HTML table sortable, as in the above example. However, TableGear's real power emerges when you want to be able to edit that data in the database. To do this, you must wrap your table in a form element, and give editable cells the class editable. You can then pass the constructor either the id of the table or the id of the form:
<form action="index.php" method="post">
<table id="myTable">
<thead>
<tr>
<th class="sortable">Header1</th>
<th class="sortable">Header2</th>
</tr>
</thead>
<tbody>
<tr>
<td class="editable">Data1</td>
<td class="editable">Data2</td>
</tr>
<!-- More rows here -->
</tbody>
</table>
</form>If you're using TableGear.php, your data will now be editable! If not, you will have to create a server-side script to handle the AJAX calls.
When working with TableGear.php, the default id for the table is tgTable. Also, although you can specify the action attribute of your form, it will by default be the same page. This is because TableGear automatically handles all submitted data, both AJAX and manual POST, as well!
Although TableGear.js has a few options, a number of them were taken out of the client-side script and moved into TableGear.php when applicable (this allows the options to work for browsers with Javascript disabled). If there is something you need that is missing, have a look there as well. Use both together to enjoy the full power of TableGear.
Options are passed in the TableGear constructor as the second argument.
| Option | Accepts | Default | Description |
|---|---|---|---|
| hideInputs | Boolean true | This option looks for checkboxes with the name edit[] or delete[]. For edit it will hide the cell that holds the box, and for delete, it will simply hide the checkbox. This is for backward compatibility in browsers without Javascript, and is a feature handled automatically by TableGear.php. |
|
| rowStriping | Boolean true | Adds the even and odd classes to the rows so they can be styled. | |
| autoSelect | Boolean true | Automatically selects the text when an input or textarea element is focused. Subtle, but cool feature that can save a lot of time. | |
| shorcutKeys | Boolean true | Turns shortcut keys on or off. | |
| ascCarat | String ▲ | The carat to use for ascending order. HTML can also be used here (such as an img element). | |
| descCarat | String ▼ | The carat to use for descending order. HTML can also be used here (such as an img element). | |
| deletePrompt | String Delete this row? | The text to confirm if a user wants to delete a row in the table. If set to null, the user won't be prompted. | |
| noDataMessage | String - No Data - | The text to use when the table's rows have all been deleted. If you are using TableGear.php, specify this option there instead, as it will be passed to TableGear.js automatically. | |
| taskMaster | Integer -1 | If you are having problems with the server (server latency, etc.), you can set this option to "check on" the AJAX requests, and make sure they're doing their job. If the request has timed out, it will be canceled and a new request will be sent. Must be more than 1000. |
This is the only public method for the Javascript class. It will re-apply any sort methods currently applied to the table. This is especially useful if you plan on adding new rows to your table with Javascript/AJAX.
One of the nicer features of TableGear is the ability to walk through your table with the keyboards. Shortcuts are as follows:
| Key | Function |
|---|---|
| tab | Step to next cell. Hold shift to step to previous cell. |
| enter | Step to next row. Hold shift to step to previous row. |
| up | Step to next row. Same as enter. |
| down | Step to previous row. Same as shift + enter. |
| esc | Reverts the cell to its previous value. The update request will not be sent. |
Sort based on numbers. This is the default, but TableGear will set the data type to alphabetic if it sees non-numeric data in the cells, so you can set this to override. A good example of a time to use this is for a column with prices that includes a dollar sign $. TableGear will ignore any non-numeric data and sort based on the number.
Sort in A-Z order (not case-sensitive). Again, TableGear will detect this type automatically, but you can specify this to override. A possible time to use this is if you have an alphabetically sorted column in which there is no data yet.
Sort based on computer memory sizes. This type will sort 16kb before 15mb, etc.
Sort based on date. This type will sort April 3, 2002 after March 4, 2001, etc. This type is quite clever, and will sort many different date formats, including Asian dates.
Same as date, but assumes English/European style dates in the case of the ambiguous format 1/6/2008 (ie. June 1, 2008).
To sort by these data types, simply add the class to the appropriate header, for example sortable date. If you don't specify a data type, TableGear will assume a numeric type unless there is non-numeric data in the cells, in which case the type will be set to alphabetic.
If you have data totals in the tfoot element of your table, these will change when the data for that column changes. By specifying the class total in the footer's cell (either a td or th element), TableGear will tell the server to send a total when a cell in that column has been edited. If you are using TableGear.php, this will be handled in the background.