Phylo Blog

After some gentle prodding from one of the philosophy job wiki’s users, I revisited a task that I’d set aside some time ago: getting the job wiki to sort job listings according to the date and time of their last update. I’d tried this before without success, but today I figured it out.

The job wiki now sorts by “last updated” by default. You can, of course, sort jobs in other ways by clicking the ’sorted by’ controls at the top of the listings.

The stumbling block had been the spottiness of SIMILE Exhibit’s documentation. Since I couldn’t figure out how Exhibit handled dates for sorting purposes, the best I’d been able to do was to get Exhibit to sort from oldest to most recently updated. That was a bit better than nothing, but not good enough. Today I found the key in the Exhibit source code. I’m posting it here for the benefit of other SIMILE Exhibit developers:

To get Exhibit to sort items by date, you need to format the dates according to the ISO 8601 date formatting standards. For instance, October 24, 2009 14:01 CDT should be formatted as 2009-10-24T14:01:00-05:00. If you’re using PHP 5+ to format your dates, you can use the string c in your date() function. (If you’re using PHP <5, use Y-m-d\TH:i:s. It doesn’t include the timezone offset, but that won’t matter for sorting purposes. Include a separate timestamp for display in your Exhibit if you’re concerned about the timezone offset.) Exhibit will correctly sort items with dates in ISO 8601 format, both ascending and descending.

There’s still one problem, though. By default, Exhibit sorts dates from earliest to latest. If you’re sorting by the timestamp of the last update for each item, you’ll probably want to default to a descending sort order. Fortunately, Exhibit lets you do that.

To control the default sort order for the items in your exhibit, set the <code>ex:directions</code> and <code>ex:possibleDirections</code> properties of your view to ‘ascending’ or ‘descending’. You can even set different defaults for different (possible) orderings. (Exhibit always defaults to ‘ascending’ if it can’t find a sort order for something.)

For instance, our job wiki has the following declaration:

<div ex:role="view"
  ex:orders=".changed_1"
  ex:directions="descending"
  ex:possibleOrders=".changed_1, .field_name_value, .field_rank_value, .field_job_status_value, .province, .tid_2, .tid_1, .tid"
  ex:possibleDirections="descending"
  ex:grouped="false"
  ex:showAll="true">
</div>

This tells Exhibit to sort the items by property “.changed_1″ in “descending” order by default. It also tells Exhibit to allow users to sort by properties .changed_1, .field_name_value, etc. Finally, the ex:possibleDirections property tells Exhibit to sort items in descending order by default whenever it’s sorting by .changed_1; because I wanted all other properties to default to sorting in ascending order, I left them all blank.

One more example: Suppose you’re working with the Nobel prize winner data from Exhibit’s Getting Started Tutorial. You want to configure your Exhibit so that when it first boots up, the Nobelists are sorted by year from most recent to least recent. You also want your users to be able to sort by name, discipline, and year. You want the default order when sorting by name to be A-Z, the default order when sorting by discipline to be Z-A (you like physics best), and year to be most recent to least recent. You would need the following code:

<div ex:role="view"
  ex:orders=".nobel-year"
  ex:directions="descending"
  ex:possibleOrders=".last-name, .discipline, .nobel-year"
  ex:possibleDirections="ascending, descending, descending">
</div>

Happy sorting!