source: trunk/lib/Navigation.inc.php @ 461

<?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/>.
 */

/**
 * Navigation.inc.php
 *
 * The Nav class provides a system for working with navigation elements.
 * It supports storing page titles and URLs for printing breadcrumbs
 * and titles, as well as setting page params such as hiding the page title on
 * some pages but not others, and storing vars like the page title itself.
 *
 * Note: this class was renamed from "Nav" because of the change in API and to be more descriptive.
 *
 * @author  Quinn Comendant <quinn@strangecode.com>
 * @version 2.0
 */
class Navigation {

    // Configuration parameters for this object.
    var $_params = array(
        'head_title' => true,
        'body_title' => true,
        'title' => true,
        'path' => true,
        'breadcrumbs' => true,
        'chop_breadcrumbs' => 0,
        'chop_breadcrumb_links' => 1,
        'path_delimiter' => ' / ',
        'last_crumb_format' => '%s',
    );
    var $pages = array();

    /**
     * Navigation constructor.
     */
    function Navigation($params=null)
    {
        $app =& App::getInstance();

        if (isset($params) && is_array($params)) {
            // Merge new parameters with old overriding only those passed.
            $this->_params = array_merge($this->_params, $params);
        }
    }

    /**
     * Add a page to the internal pages array. Pages must be added sequentially
     * as they are to be printed. The root page must be added first, and the
     * current page added last. Vars can be specified for any page, but only vars
     * from the "current" page will be accessed with Nav::get.
     *
     * @access  public
     * @param   string  $title      The title of the page.
     * @param   string  $url        The URL to the page. Set to null to use PHP_SELF.
     * @param   array   $vars       Additional page variables.
     */
    function add($title, $url=null, $vars=array())
    {
        $page = array(
            'title' => $title,
            'head_title' => $title,
            'body_title' => $title,
            'url' => is_null($url) ? $_SERVER['PHP_SELF'] : $url,
        );
        $this->pages[] = array_merge($page, $vars);
    }

    /**
     * Set (or overwrite existing) parameters by passing an array of new parameters.
     *
     * @access public
     * @param  array    $params     Array of parameters (key => val pairs).
     */
    function setParam($params)
    {
        $app =& App::getInstance();

        if (isset($params) && is_array($params)) {
            // Merge new parameters with old overriding only those passed.
            $this->_params = array_merge($this->_params, $params);
        } else {
            $app->logMsg(sprintf('Parameters are not an array: %s', $params), LOG_ERR, __FILE__, __LINE__);
        }
    }

    /**
     * Return the value of a parameter, if it exists.
     *
     * @access public
     * @param string $param        Which parameter to return.
     * @return mixed               Configured parameter value.
     */
    function getParam($param)
    {
        $app =& App::getInstance();

        if (isset($this->_params[$param])) {
            return $this->_params[$param];
        } else {
            $app->logMsg(sprintf('Parameter is not set: %s', $param), LOG_DEBUG, __FILE__, __LINE__);
            return null;
        }
    }

    /**
     * Unsets all pages.
     *
     * @access  public
     */
    function clear()
    {
        $this->pages = array();
    }

    /**
     * Sets a variable into the current page.
     *
     * @access public
     * @param mixed $key      Which value to set.
     * @param mixed $val      Value to set variable to.
     */
    function set($key, $val)
    {
        // Set params of current page.
        $curr_page =& $this->pages[sizeof($this->pages) - 1];
        $curr_page[$key] = $val;
    }

    /**
     * Returns a specified value from the current page.
     *
     * @access public
     * @param mixed $key      Which value to return.
     * @param mixed $default  Value to return if key not found in user_data.
     * @return mixed          Value stored in session.
     */
    function get($key, $default='')
    {
        $curr_page =& $this->pages[sizeof($this->pages) - 1];

        switch ($key) {
        case 'title' :
            if ($this->getParam('title') && isset($curr_page['title'])) {
                return $curr_page['title'];
            }
            break;

        case 'head_title' :
            if ($this->getParam('head_title') && $this->getParam('title') && isset($curr_page['head_title'])) {
                return $curr_page['head_title'];
            }
            break;

        case 'body_title' :
            if ($this->getParam('body_title') && $this->getParam('title') && isset($curr_page['body_title'])) {
                return $curr_page['body_title'];
            }
            break;

        case 'path' :
            if ($this->getParam('path')) {
                return $this->getPath();
            }
            break;

        case 'breadcrumbs' :
            if ($this->getParam('breadcrumbs')) {
                return $this->getBreadcrumbs();
            }
            break;

        default :
            return isset($curr_page[$key]) ? $curr_page[$key] : $default;
            break;
        }

        return $default;
    }

    /**
     * Returns the text path from root up to the current page, separated by the
     * path_delimiter.
     *
     * @access  public
     * @param   string   $key   Which value to use in the path (usually head_title or body_title or just title).
     * @return  mixed           Path (string) or false if path param is not set.
     */
    function getPath($key='title')
    {
        if ($this->getParam('path')) {
            $path = '';
            $pathmark = '';
            foreach ($this->pages as $page) {
                $path .= oTxt($pathmark . strip_tags($page[$key]), true);
                $pathmark = $this->getParam('path_delimiter');
            }
            return $path;
        } else {
            return false;
        }
    }

    /**
     * Returns the breadcrumbs from the root page to the current page.
     * Breadcrumbs are the text path with pages titles linked to that page.
     *
     * @access  public
     * @return  string   Breadcrumbs or empty string if breadcrumbs param not set.
     */
    function getBreadcrumbs()
    {
        $app =& App::getInstance();

        if ($this->getParam('breadcrumbs')) {
            $breadcrumbs = array();
            $pathmark = '';
            $crumb_count = sizeof($this->pages);
            foreach ($this->pages as $page) {
                if ($crumb_count <= $this->getParam('chop_breadcrumbs')) {
                    // Stop gathering crumbs.
                    break;
                }
                if ($crumb_count <= 1) {
                    // The last crumb.
                    if ('' == trim($page['url']) || $crumb_count <= $this->getParam('chop_breadcrumb_links')) {
                        // A crumb with no link.
                        $breadcrumbs[] =  sprintf($this->getParam('last_crumb_format'), oTxt($page['title'], true));
                    } else if ($crumb_count > $this->getParam('chop_breadcrumb_links')) {
                        // A normal linked crumb.
                        $breadcrumbs[] =  '<a href="' . $app->oHREF($page['url']) . '">' . sprintf($this->getParam('last_crumb_format'), oTxt($page['title'], true)) . '</a>';
                    }
                } else {
                    if ('' == trim($page['url'])) {
                        // A crumb with no link.
                        $breadcrumbs[] = oTxt($pathmark . $page['title'], true);
                    } else {
                        // A normal linked crumb.
                        $breadcrumbs[] = '<a href="' . $app->oHREF($page['url']) . '">' . oTxt($page['title'], true) . '</a>';
                    }
                }
                $pathmark = $this->getParam('path_delimiter');
                $crumb_count--;
            }
            return join(oTxt($pathmark, true), $breadcrumbs);
        } else {
            return '';
        }
    }

    /**
     * Returns a string if the queried page is the current page. One use is to print
     * CSS tags if the current page matches a link, such as:
     * $nav->currentPage('mypage.php', ' id="current"');
     *
     * @access  public
     *
     * @param   mixed   $page   The URI of the page to query, with PREG express markup, if needed.
     * @param   mixed   $return The value to return if the current page matches the page queried.
     *
     * @return  mixed   The value set for $return, TRUE by default.
     */
    function currentPage($test_uri, $true_return=true, $false_return=false, $include_query=true)
    {
        $actual_uri = $include_query ? $_SERVER['REQUEST_URI'] : strtok($_SERVER['REQUEST_URI'], '?');
        if (preg_match('/^' . preg_quote(urldecode($test_uri), '/') . '$/i', $actual_uri)) {
            return $true_return;
        }
        return $false_return;
    }

}
// End of class.

?>