source: trunk/lib/SortOrder.inc.php @ 262

<?php
/**
 * SortOrder.inc.php
 * Code by Strangecode :: www.strangecode.com :: This document contains copyrighted information
 *
 * SortOrder can determing how to sort results of a database query for display
 * on a listing. It can print column headers that will be links to
 * automatically change the sort and order.
 *
 * @requires    This class requires Prefs.inc.php
 *
 * @author  Quinn Comendant <quinn@strangecode.com>
 * @version 1.6.2
 */
require_once dirname(__FILE__) . '/Prefs.inc.php';

class SortOrder {

    var $_columns;
    var $sort_by;
    var $order;
    var $asc_widget = '<img src="/admin/_widgets/sort_ascending.gif" alt="[ASC]" width="11" height="7" border="0" />';
    var $desc_widget = '<img src="/admin/_widgets/sort_descending.gif" alt="[DESC]" width="11" height="7" border="0" />';
    var $default_sort;
    var $default_order;

    /**
     * Constructor. Finds the current sort by and order.
     *
     * @param string $default_sort   If not found elsewhere, this will be the
     *                               current sort by.
     * @param string $default_order  If not found elsewhere, this will be the
     *                               current order.
     */
    function SortOrder($default_sort = '', $default_order = '')
    {
        $this->prefs = new Prefs($_SERVER['PHP_SELF']);
        $this->prefs->setParam(array('persistent' => false));

        $this->setDefault($default_sort, $default_order);

        $this->default_sort = $default_sort;
        $this->default_order = $default_order;        
    }

    /**
     * Build an array of valid sort SQL for each DB column. This SQL is reference
     * by the name and 'asc' or 'desc'.
     *
     * @param string $name      Reference name for the column this SQL sorts on.
     * @param string $asc_sql   The sort SQL if $this->order is ascending.
     * @param string $desc_sql  The sort SQL if $this->order is descending.
     */
    function setColumn($name, $asc_sql, $desc_sql)
    {
        $this->_columns[$name] = array(
            'asc'  => $asc_sql,
            'desc' => $desc_sql
        );
    }

    /**
     * Set sort and order values. This is how you set new sort values after
     * already declaring a SortOrder object, but expect values to come from
     * getFormData.
     *
     * @param string $default_sort   If not found elsewhere, this will be the
     *                               current sort by.
     * @param string $default_order  If not found elsewhere, this will be the
     *                               current order.
     */
    function setDefault($default_sort = '', $default_order = '')
    {
        // Which column to sort by?
        // (1) By GET or POST specification, if available.
        // (2) By saved preference, if available.
        // (3) By default (provided at class instantiation).
        $new_sort_by = getFormData('sort');
        if (!empty($new_sort_by)) {
            $this->sort_by = $new_sort_by;
            $this->prefs->set('sort_by', $this->sort_by);
        } else if ($this->prefs->exists('sort_by')) {
            $this->sort_by = $this->prefs->get('sort_by');
        } else {
            $this->sort_by = $default_sort;
        }

        // Which sort order to use?
        // (1) By GET or POST specification, if available.
        // (2) By saved preference, if available.
        // (3) By default (provided at class instanciation).
        $new_order = getFormData('order');
        if (!empty($new_order)) {
            $this->order = $new_order;
            $this->prefs->set('sort_order', $this->order);
        } else if ($this->prefs->exists('sort_order')) {
            $this->order = $this->prefs->get('sort_order');
        } else {
            $this->order = $default_order;
        }
    }


    /**
     * Forcibly set sort and order values. This is how you set new sort values after
     * already declaring a SortOrder object. This will ignore getFormData values.
     *
     * @param string $sort           The sort by name.
     * @param string $order          The order direction (ASC,
     *                               for example, for an alphabetical sort)
     */
    function set($sort = null, $order = null)
    {
        // Set new sort value.
        if (isset($sort)) {
            $this->sort_by = $sort;
            $this->prefs->set('sort_by', $this->sort_by);
        }

        // Set new order value.
        if (isset($order)) {
            $this->order = $order;
            $this->prefs->set('sort_order', $this->order);
        }
    }


    /**
     * Returns the SQL code to sort by set column and set order.
     */
    function getSortOrderSQL()
    {
        $app =& App::getInstance();
        $db =& DB::getInstance();

        if (!isset($this->_columns[mb_strtolower($this->sort_by)])) {
            $this->sort_by = $this->default_sort;
            $this->order = $this->default_order;
        }
        if (!isset($this->_columns[mb_strtolower($this->sort_by)][mb_strtolower($this->order)])) {
            $this->order = 'ASC';
        }

        if (!empty($this->_columns[mb_strtolower($this->sort_by)][mb_strtolower($this->order)])) {
            return sprintf(' ORDER BY %s ', $db->escapeString($this->_columns[mb_strtolower($this->sort_by)][mb_strtolower($this->order)]));
        } else {
            $app->logMsg(sprintf('Could not find SQL to sort by %s %s.', $this->sort_by, $this->order), LOG_WARNING, __FILE__, __LINE__);
            return '';
        }
    }


    /**
     * Prints a link for a column header with URL sort determining logic.
     *
     * @param string $col            The database column to sort by.
     * @param string $col_name       The human-readable title of the column.
     * @param string $default_order  The default order for this column (ASC,
     *                               for example, for an alphabetical sort)
     */
    function printSortHeader($col, $col_name, $default_order='ASC')
    {
        $app =& App::getInstance();

        if ($this->sort_by == $col) {
            if (mb_strtolower($this->order) == 'desc') {
                ?><a href="<?php echo $app->oHREF($_SERVER['PHP_SELF'] . '?sort=' . $col . '&order=ASC'); ?>" title="<?php echo _("Change to ascending sort order"); ?>"><?php echo $this->desc_widget; ?></a><?php echo $col_name; ?><?php
            } else {
                ?><a href="<?php echo $app->oHREF($_SERVER['PHP_SELF'] . '?sort=' . $col . '&order=DESC'); ?>" title="<?php echo _("Change to descending sort order"); ?>"><?php echo $this->asc_widget; ?></a><?php echo $col_name; ?><?php
            }
        } else {
            ?><a href="<?php echo $app->oHREF($_SERVER['PHP_SELF'] . '?sort=' . $col . '&order=' . $default_order); ?>" title="<?php echo sprintf(_("Sort by %s"), $col_name); ?>"><?php echo $col_name; ?></a><?php
        }
    }

}

?>