source: branches/1.1dev/lib/Nav.inc.php @ 646

<?php
/**
 * The Nav:: class provides a system for working with navigation elements.
 * Currently it supports storing page titles and URLs for printing breadcrumbs
 * and titles, as well as setting page features such as hiding the page title on 
 * some pages but not others.
 *
 * @author  Quinn Comendant <quinn@strangecode.com>
 * @version 1.0
 */
class Nav {

    var $pages = array();
    var $default_features = array(
        'title' => true,
        'path' => true,
        'breadcrumbs' => true,
        'chop_breadcrumbs' => 0,
        'chop_breadcrumb_links' => 1,
    );
    var $path_delimiter = ' / ';
    var $features = array();
    var $last_crumb_format = '%s';

    /**
     * Constructor. Set default features to apply to all added pages.
     */
    function Nav($default_features=null)
    {
        if (isset($default_features) && is_array($default_features)) {
            $this->default_features = array_merge($this->default_features, $default_features);
        }
        $this->features = $this->default_features;
    }

/******************************************************************************
 * INPUT
 *****************************************************************************/

    /**
     * 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. Features can be specified for a page, but currently
     * only the features for the current page can be set. Future versions of this
     * class may have the ability to set features for each page specifically.
     *
     * @access  public
     *
     * @param   string  $title      The title of the page.
     * @param   string  $url        The URL to the page. Leave blank (or null) if
     *                              page is to not be linked.
     * @param   array   $features   Set the features of the current page.
     */
    function addPage($title, $url=null, $features=null)
    {
        $this->pages[] = array(
            'title'     => $title,
            'url'       => is_null($url) ? $_SERVER['PHP_SELF'] : $url,
            'features'  => (isset($features) && is_array($features)) ? array_merge($this->default_features, $features) : $this->default_features
        );
    }

    /**
     * Update the title, url, and features for the current page (the last added).
     *
     * @access  public
     *
     * @param   string  $title      The title of the page.
     * @param   string  $url        The URL to the page. Leave blank (or null) if
     *                              page is to not be linked.
     * @param   array   $features   Set the features of the current page.
     */
    function updatePage($title, $url=null, $features=null)
    {
        if (isset($title)) {
            $this->pages[sizeof($this->pages)-1]['title'] = $title;            
        }
        if (isset($url)) {
            $this->pages[sizeof($this->pages)-1]['url'] = $url;            
        }
        if (isset($features) && is_array($features)) {
            $this->pages[sizeof($this->pages)-1]['features'] = array_merge($this->pages[sizeof($this->pages)-1]['features'], $features);            
        }
    }
    
    /**
     * Set the features of the current page. Future versions of this class
     * may have the ability to set features for a specific page. In that case
     * some form of ID will need to be specified for each page.
     *
     * @param  array $feature   Array of feature keys and value to set.
     *
     * @return bool true on success, false on failure
     */
    function setFeature($features=null, $page_id=null)
    {
        if (!isset($page_id)) {
            $page_id = sizeof($this->pages) - 1;
        } else if ($page_id < 0 && is_numeric($page_id)) {
            $page_id = sizeof($this->pages) + intval($page_id);
        }
        
        if (!isset($this->pages[sizeof($this->pages)-1]['features']) || !isset($this->pages[$page_id]['features'])) {
            $app->logMsg(sprintf('Page not available to set feature: page_id = %s', $page_id), LOG_ERR, __FILE__, __LINE__);
            return false;
        }
        
        if (isset($features) && is_array($features)) {
            // Set features for specified page.
            $this->pages[$page_id]['features'] = array_merge($this->pages[$page_id]['features'], $features);
            // Store "current page" features.
            $this->pages[sizeof($this->pages)-1]['features'] = array_merge($this->pages[sizeof($this->pages)-1]['features'], $features);
        }
    }

    /**
     * Unsets all page variables and resets features to the default set.
     *
     * @access  public
     */
    function clearPath()
    {
        $this->pages = array();
        $this->features = $this->default_features;
    }

/******************************************************************************
 * OUTPUT
 *****************************************************************************/
 
    /**
     * Get the value of a feature for specified page_id or current page if page_id not specified (future use).
     *
     * @param  string $feature   Name of feature value to retreive.
     * @param  mixed $page_id    Future use: ID of page.
     *
     * @return bool true on success, false on failure
     */
    function getFeature($feature, $page_id=null)
    {
        if (!isset($page_id)) {
            $page_id = sizeof($this->pages) - 1;
        } else if ($page_id < 0 && is_numeric($page_id)) {
            $page_id = sizeof($this->pages) + intval($page_id);
        }
        
        switch ($feature) {
        case 'breadcrumbs' :
            // No breadcrumbs if displayed quantity of crumbs is less than 1.
            return $this->pages[$page_id]['features'][$feature] && ((sizeof($this->pages) - $this->getFeature('chop_breadcrumbs')) > 0);
            break;
        default :
            return $this->pages[$page_id]['features'][$feature];
        }
    }

        
    /**
     * Returns the title of current page.
     *
     * @access  public
     *
     * @return  mixed  Title of page (string) or false if title feature not set.
     */
    function getTitle($page_id=null)
    {
        if (!isset($page_id)) {
            $page_id = sizeof($this->pages) - 1;
        } else if ($page_id < 0 && is_numeric($page_id)) {
            $page_id = sizeof($this->pages) + intval($page_id);
        }
        
        if ($this->getFeature('title', $page_id)) {
            return oTxt($this->pages[$page_id]['title'], true);
        } else {
            return false;
        }
    }

    /**
     * Prints the title of page returned by getTitle().
     *
     * @access  public
     */
    function printTitle($page_id=null)
    {
        echo $this->getTitle($page_id);
    }

    /**
     * Returns the text path from root up to the current page, seperated by the
     * path_delimeter.
     *
     * @access  public
     *
     * @return  mixed   Path (string) or false if path feature is not set.
     */
    function getPath($page_id=null)
    {
        if (!isset($page_id)) {
            $page_id = sizeof($this->pages) - 1;
        } else if ($page_id < 0 && is_numeric($page_id)) {
            $page_id = sizeof($this->pages) + intval($page_id);
        }
        
        if ($this->getFeature('path', $page_id)) {
            $path = '';
            $pathmark = '';
            foreach ($this->pages as $curr_id => $page) {
                $path .= oTxt($pathmark . strip_tags($page['title']), true);
                $pathmark = $this->path_delimiter;
                if ($curr_id === $page_id) {
                    // Reached requested page.
                    return $path;
                }
            }
            return $path;
        } else {
            return false;
        }
    }

    /**
     * Prints the path returned by getPath().
     *
     * @access  public
     */
    function printPath($page_id=null)
    {
        echo $this->getPath($page_id);
    }

    /**
     * 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  mixed   Breadcrumbs (string) or false if breadcrumbs feature not set.
     */
    function getBreadcrumbs($page_id=null)
    {
        if (!isset($page_id)) {
            $page_id = sizeof($this->pages) - 1;
        } else if ($page_id < 0 && is_numeric($page_id)) {
            $page_id = sizeof($this->pages) + intval($page_id);
        }
        
        if ($this->getFeature('breadcrumbs')) {
            $breadcrumbs = '';
            $pathmark = '';
            $crumb_count = sizeof($this->pages);
            foreach ($this->pages as $curr_id => $page) {
                if ($crumb_count <= $this->getFeature('chop_breadcrumbs')) {
                    // Stop gathering crumbs.
                    return $breadcrumbs;
                }
                if ($crumb_count <= 1) {
                    // The last crumb.
                    if (empty($page['url']) || $crumb_count <= $this->getFeature('chop_breadcrumb_links')) {
                        // A crumb with no link.
                        $breadcrumbs .= oTxt($pathmark, true) . sprintf($this->last_crumb_format, oTxt($page['title'], true));
                    } else if ($crumb_count > $this->getFeature('chop_breadcrumb_links')) {
                        // A normal linked crumb.
                        $breadcrumbs .= oTxt($pathmark, true) . '<a href="' . ohref($page['url']) . '">' . sprintf($this->last_crumb_format, oTxt($page['title'], true)) . '</a>';
                    }
                } else {
                    if (empty($page['url'])) {
                        // A crumb with no link.
                        $breadcrumbs .= oTxt($pathmark . $page['title'], true);
                    } else {
                        // A normal linked crumb.
                        $breadcrumbs .= oTxt($pathmark, true) . '<a href="' . ohref($page['url']) . '">' . oTxt($page['title'], true) . '</a>';
                    }
                }
                $pathmark = $this->path_delimiter;
                $crumb_count--;
                
                if ($curr_id === $page_id) {
                    // Reached requested page.
                    return $breadcrumbs;
                }
            }
            return $breadcrumbs;
        } else {
            return false;
        }
    }

    /**
     * Prints the breadcrumbs returned by getBreadcrumbs().
     *
     * @access  public
     */
    function printBreadcrumbs($page_id=null)
    {
        echo $this->getBreadcrumbs($page_id);
    }
    
    /**
     * 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.
     * @param   mixed   $return The value to return if the current page matches the page queried.
     *
     * @return  bool    True on success, false on failure.
     */
    function currentPage($page_uri, $return=true)
    {
        if (preg_match('/^' . preg_quote($page_uri, '/') . '/i', $_SERVER['PHP_SELF'])) {
            return $return;
        }
    }
    
} 
// End of class.

?>