Tables part 4: Sort criteria
Sort criteria are the simplest of the three types of data in the $table object, and most sorts don't need more than the most basic information.
Sort criteria are added to the table an array of fields using the 'sortskey. The key for each field in the array should be the database name of the field to sort on; it doesn't have to be, however. But if it isn't, you should set 'field' => 'actual_field_name'. This works exactly like table aliasing, and is very similar to the same concept in 'fields' but without 'notafield' => true.
Example:
<?php
$table = array(
...
'sorts' => array(
'myfield_a' => array(
... // data about the field
),
'myfield_b' => array(
... // data about the field
),
),
);
?>Sort settings
Throughout Views and this documentation, these are referred to sometimes as 'sorts' and sometimes 'sort criteria'.
The following items may be added to the definition of a sort criteria.
- name (Required)
This is the name displayed for the sort criteria on the admin UI. It is customary to tag your this with something recognizable as your module. For example, Node: ID or Taxonomy: Term. This should always be wrapped in a t().
This contains help text for the sort criteria, which should tell the user how to utilize it. This should be wrapped with t() for translation. This should always appear, even if it just contains a few words describing the field.
This is the 'real' name of the field that is being operated on. This can be useful if you have several instances of a sort criteria that are used entirely differently, and not simply as handlers.
A handler that allows the field to modify the query. If this is used, the default sorting is not used for the field, so you must add your own orderby to the $query object. This is mostly useful for sorting on formulae or combinations of fields that rely on some sort of transformation.
function views_sort_handler($op, &$query, $sortinfo, $sortdata)
Modify the $query object for this particular sort criteria. Ordinarily this handler will call $query->add_orderby().
Parameters
$op This will always be 'sort'. This really is a leftover from the very earliest version of Views that used a lot fewer handlers, when the author thought that more handlers would use the same function. It has no value at this time and will likely disappear in Views 2.0.
&$query The query object to modify.
$sortdata The information on the field from the database. See below for more information.
$sortinfo The array from the $tables data for this particular sort criteria It will contain the information from this very list.
Return value
None
A handler to validate from the UI to ensure the data makes sense.
function views_sort_validator($sortdata, $view, $form)
Validate that settings on a sort are within the boundaries of reason. This is rarely needed.
Parameters
$sortdata The information on the sort criteria from the database. Note that this is the unmodified version; it may be mostly blank if the view does not exist, but the 'id' from this will be necessary to find the part of the form to validate.
$view The array from the $tables data for this particular field. It will contain the information from this very list.
$form The full form array to validate. TODO: tell how to find the information in the $form array to actually validate.
Return value
None. If the data is not valid, use form_error($form[...], 'message') to fail the validation process.
Setting this field will require an additional form item to appear for this sort criteria in the UI. If this is set to 'string' or 'integer' a simple textfield will appear, but this may also be complete formAPI array (such as for choosing an option from an array). See more on options below.
Like with fields, some handlers might need extra data, and they can set arbitrary names here. With sort criteria, this is much, much less common, however.
Most sort criteria have only a 'name' and a 'help'; the very obvious is done invisibly. For example:
<?php
'title' => array(
'name' => t('Node: Title'),
'help' => t('Sort by the node title, alphabetically'),
),
?>A very few items have a more complex sort criteria:
<?php
'created' => array(
'name' => t('Node: Created Time'),
'handler' => 'views_handler_sort_date',
'option' => views_handler_sort_date_options(),
'help' => t('Sort by the submission date of the node.'),
),
?>See views_node.inc in the modules directory for more information about how the above sort works.
Sort data
The $sortdata array is passed to sort handlers. It is loaded from the database, and represents a single sort criteria on a view.
- vid Database
- Loaded from the database, this field simply matches the record to the view it belongs to. Should not be used.
- tablename Database
- The table this field belongs to.
- field Database
- The name of the field, from the key of the array -- this may be a pseudo-field, not necessarily the real name of the field.
- sortorder Database
- This will either be ASC for Ascending or DESC for Descending..
- options Database
- A stored representation of the options. If the option was set to string/integer it will simply be the value; if set to a forms api array it will be whatever value that returned. Complex forms API arrays may return serialized data here, but this is rare.
- position Database
- The order of the field, starting from 0.
- id
- A 'unique' representation of the field so Views can find it. This is usually in the form of 'table.field'.
Common handlers
function views_handler_sort_date_options()- This function may be applied to the 'option' field of any sort that stores a date in standard Drupal format; it allows 'granular' sorts which make it easier to sort by month and then title, for example. Apply it as a function, not a handler. I.e,
'option' => views_handler_sort_date_options(), function views_handler_sort_date($op, &$query, $sortinfo, $sort)- This is the actual handler used by the above date options.
Possible bug
I have run into an issue where sometimes a sorts entry would not register unless I specified a "field" key, even if it shouldn't be necessary to do so. If you run into a similar issue, try giving a guaranteed-unique name to the sort entry and then specify the "field" key. It worked for me. :-)
--
Larry Garfield
http://www.garfieldtech.com/blog
http://www.palantir.net