Sortable Table ColdFusion Custom Tag with jQuery UI
The first thing you need is to download both jQuery JavaScript and the ui.sortabletable.js from the jQueryUI scripts. You can place those files anywhere as the path to the scripts is configurable, just make sure they are all in the same location. You also need the themes which go in the same directory under /themes/. Currently I use the "Flora" theme as that seemed to be the only one that worked. In the future, I hope to make this aspect configurable. I also tried to get the widget shown in the examples to work, but it wouldn't with the tablesorter.js version available with the provided 1.0 download. After much frustration, I figured out that their examples are using a different version where the zebra effect functions properly, which I have included in the download. Hopefully that will be rectified soon.
Using the Tag
To use the tag, you nest the columns tag within the sortabletables tag. The main tag has one required parameter, the query you want to display (query). Optionally you can tell the tag to include the jquery script (includeJQueryScript), the tablesorter.js script (includeUIScript) or the CSS theme (includeCSSTheme). If you do any of these, you will need to provide the other optional argument for the path to the jQuery scripts (jsPath). It is important to note that the tag is smart enough to know when it has already included the scripts and will not do so on any subsequent requests. This is done through setting some caller variables, including one for a tableid; the tableid will allow you to include multiple sortable tables on a page without them conflicting with each other.
Once you have established the table settings, you can include any columns using the cf_sortablecolumn tag. This tag has seven parameters, all of which are optional (though, if you left them all out, it serves no purpose):
column: this is the name of the query column that you would like displayed. Columns are displayed in the order your specify.
title: this is the header text for the column which, if not provided, defaults to the query column name.
format: this allows you to specify how the column is displayed using ColdFusion formatting functions such as dateFormat(), dollarFormat(), etc. It supports any built-in or custom UDF. It is important to note however that the date sorting appears to default to standard string formatting unless you give it both date and time in the format "dateFormat(dateAdded,'mmm dd, yyyy ') & timeFormat(dateAdded,'h:mm tt')". I will look into how this can be customized.
sort: this will set a column to auto-sort when the table initially loads. When provided, allowable values are "asc" or "desc". Columns are sorted in the order they appear, which means that if firstName is first and set to "asc" and lastName is second and set to "asc", then it will sort by firstName and then lastName.
disable: this will disable sorting on that column. It is false by default - meaning that sort is enabled by default.
pre: this is any HTML that will be included in each table cell for this column before the query value. The pre parameter allows you to provide multiple query column values that will be replaced at runtime using the format {column_name}, allowing you to do things like include query parameters in a URL query string. You can also include just the pre without any column value as in the example below.
post: this is any HTML that will appear after the included column value. It does not currently support the included column values as in the pre parameter.
Example
The code below outputs the following example. Notice that it auto sorts on the clickCount and that the dateAdded has been formatted as specified. Also notice that the last column is disabled and actually does not include any query column value. It does however provide two query column values within the pre tag that are replaced at runtime.
<cf_sortabletable jsPath="jquery/" query="#getProjects#"> <cf_sortablecolumn column="title" title="Project Name" /> <cf_sortablecolumn column="clickCount" title="Clicks" sort="desc" /> <cf_sortablecolumn column="dateAdded" title="Date Added" format="dateFormat(dateAdded,'mmm dd, yyyy ') & timeFormat(dateAdded,'h:mm tt')" /> <cf_sortablecolumn disable="true" pre="<a href='#CGI.SCRIPT_NAME#?id={resourceid}&clicks={clickCount}'>edit</a>" /> </cf_sortabletable>
Conclusion
I am pretty happy with the way this tag has turned out and with its improvements over my original tag. Hopefully some of you find this tag useful (I don;t think too many people used the old one...or at least I never heard about it). I may look into working other jQueryUI elements into other tags in the future. If you find bugs or would like to request enhancements, please comment here or email me. Also, if you find this helpful, you could always visit my wish list :).
