NAME

Widget.SortableTable - A widget to make a table sortable

SYNOPSIS

DESCRIPTION

Instruments a table so that each of its headers is a clickable link that resorts the table based on that column.

METHODS

TYPES AND SORTING

By default, Widget.SortTable tries to figure out the type of a column based on its text contents. It currently recognizes four types of data, numeric (integer or floating point), currency (a number preceded by "$" or the Euro symbol), dates in YYYY-MM-DD format, and text.

Text is sorted case-insensitively. Dates are sorted in descending order by default.

It detects the type by looking at the second cell in the column (which may change depending on previous sorts). If this is blank for a column, it will assume that the type is text. If you have blank cells in a column and the data is not text, you should always specify its type when constructing the Widget.SortTable object.

Empty cells are sorted as being less than non-empty cells for all types.

HOW THE WIDGET ALTERS THE TABLE

When the widget object is first instantiated, it makes a number of changes to the DOM for the table. It assumes that the first row contains column headers. For each cell, it takes the contents of the cell, whatever they may be, and wraps them in a new <a> tag. The href for this tag is "#". The tag has an "onClick" event set which calls sortOnColumn() with the appropriate column number. Its class name is "w-st-resort-column". It also has an "onClick" attribute set to "return false;" so that clicking it does not cause the browser to scroll the page.

The widget will call sortOnColumn() as soon as it can in order to establish an initial sort order for the table.

When the table is sorted, the widget will make a number of changes to the class names for table elements. The changes are as follows:

Any class names you assign in your HTML will be left untouched by the widget.

Current Sort Indicators

This widget does not add any DOM elements to show which column is the current sort-by column. Instead, you can take advantage of the CSS class names it uses to get the same effect.

For example, let's start with this HTML for a column header cell:

  <th>Name
      <img class="none" src="none.png" />
      <img class="asc"  src="asc.png" />
      <img class="desc" src="desc.png" />
  </th>

Then in your CSS you can define the following style rules:

 img.asc, img.desc {
     display: none;
 }

 th.w-st-current-sorted-column img.none {
     display: none;
 }

 th.w-st-asc-column-header   img.asc  {
     display: inline;
 }

 th.w-st-desc-column-header  img.desc  {
     display: inline;
 }

With these rules, the appropriate image will be displayed simply based on the class name changes that the widget makes.

AUTHOR

Dave Rolsky, <autarch@urth.org>.

COPYRIGHT

Copyright (c) 2006 Dave Rolsky. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as the Perl programming language (your choice of GPL or the Perl Artistic license).