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

<?php
/**
 * The Strangecode Codebase - a general application development framework for PHP
 * For details visit the project site: <http://trac.strangecode.com/codebase/>
 * Copyright 2001-2012 Strangecode, LLC
 *
 * This file is part of The Strangecode Codebase.
 *
 * The Strangecode Codebase is free software: you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as published by the
 * Free Software Foundation, either version 3 of the License, or (at your option)
 * any later version.
 *
 * The Strangecode Codebase is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License along with
 * The Strangecode Codebase. If not, see <http://www.gnu.org/licenses/>.
 */

/**
 * SortOrder.inc.php
 *
 * SortOrder can determine 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
{

    protected $_columns;
    public $sort_by;
    public $order;
    public $asc_widget;
    public $desc_widget;
    public $default_sort;
    public $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.
     */
    public function __construct($default_sort = '', $default_order = '')
    {
        $app =& App::getInstance();

        // Setup the HTML for printing ASC/DESC paths.
        // This should be converted to CSS someday.
        $images_path = $app->getParam('images_path') ? $app->getParam('images_path') : '/admin/_widgets';
        $this->asc_widget = sprintf('<img src="%s/sort_ascending.gif" alt="%s" width="11" height="7" border="0" />', $images_path, _("Ascending"));
        $this->desc_widget = sprintf('<img src="%s/sort_descending.gif" alt="%s" width="11" height="7" border="0" />', $images_path, _("Descending"));

        // Setup prefs object.
        $this->prefs = new Prefs($_SERVER['PHP_SELF']);
        $this->prefs->setParam(array('persistent' => false));

        // Setup defaults.
        $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.
     */
    public 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.
     */
    public 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 instantiation).
        $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)
     */
    public function set($sort=null, $order=null, $save_value=true)
    {
        // Set new sort value.
        if (isset($sort)) {
            $this->sort_by = $sort;
            if ($save_value) {
                $this->prefs->set('sort_by', $this->sort_by);
            }
        }

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

    /**
     * Get the current sort and order values.
     *
     * @return array    Array with keys: sort and order. These can be fed back into the SortOrder::set() method or defaults.
     */
    public function get()
    {
        return array(
            'sort' => $this->prefs->get('sort_by'),
            'order' => $this->prefs->get('sort_order'),
        );
    }

    /**
     * Returns the SQL code to sort by set column and set order.
     */
    public 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 ', $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.
     * Column must be defined first using setColumn().
     *
     * @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)
     */
    public function printSortHeader($col, $col_name, $default_order='ASC')
    {
        $app =& App::getInstance();

        if (isset($this->_columns[$col])) {
            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"); ?>" class="sc-sort sc-desc"><?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"); ?>" class="sc-sort sc-asc"><?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); ?>" class="sc-sort"><?php echo $col_name; ?></a><?php
            }
        } else {
            echo $col_name;
        }
    }

}