MidgardQueryBuilder method add_order

Usage:
Note for Midgard 1.7 users without MidCOM

MidgardQueryBuilder class name is deprecated since Midgard 1.8. Use midgard_query_builder class name. Deprecated name will be removed in Midgard 2.0

Description:

bool add_order(string property, [string order])

Minimum version: Midgard 1.7.1

add_order is a method for the Query Builder for sorting the result list in desired way.

The method takes two arguments:

property is the name of a property in the MgdSchema type being queried
order is optional, and is either ASC for ascending, or DESC for descending order. If it is omitted ASC will be used.

This method returns TRUE when order was succesfully added to query generated by Query Builder, FALSE otherwise.

Midgard 1.8: Advanced ordering may be used for metadata objects or for referenced link types.

Failure to add an ordering will not invalidate the QueryBuilder instance, the invalid ordering will just be ignored. It's up to the caller to judge if failure is critical for executed query or not.

Usage:

<?php
$qb = new MidgardQueryBuilder("midgard_article");

// These two lines are equivalent (so specifying both in real-life
// wouldn't make sense of course :))
$qb->add_order('name');
$qb->add_order('name', 'ASC');

// This would list the last-created article first.
$qb->add_order('created', 'DESC');
?>

Note for Midgard 1.7 users without MidCOM

Due to a Zend-related bug in the PHP Binding, Midgard 1.7 crashes when you call $qb->add_order(false);. Unfortunalety, this cannot be easily circumvented, for dynamic assignments like $qb->add_order($some_var); you should therefore take some care to check against empty values first.

MidCOM 2.5 CVS users (as of 2006-02-22) do not have to worry about this, as the MidCOM level QB Wrapper midcom_core_querybuilder implicitly checks against this case when adding an ordering constraint.