source: branches/1.1dev/docs/Nav.inc.php documentation.txt

Navigation class. The following is just getting all the ideas I've had for this. Please append with your own ideas.

include 'Nav.inc.php';
$nav = new Nav();


GOALS
----------------------------------------------------------------
To create an abstract interface for generating dynamic navigational elements, from knowing only the current location and a complete site heirarchy. It will have simple data input, data storage, and data output--it will not query a database, include files, or have ANY external requirements other than that basic data that can be given it. The designer/template integrator will use the output functions to generate nav elements. They will not need to worry about where the page info comes from. The programmer that configures the application with the nav class will make sure the data is input correctly. It will satify the use of the url_parser.inc.php file. It will do all that I was doing with $nav->addPage('title', '/url/url/url.php'); 

                  +------------+ ---> Page <title>
Site map & |      | abstract   | ---> Page header
current    | ---> | data and   | ---> Breadcrumbs
location   |      | functions  | ---> Sublinks
                  +------------+ ---> Previous page
                  
                  
                  
$heir = array(
    array(
        'title' => 'Home',
        'url'   => '/',
        'features' => array('breadcrumbs'=>true, 'title'=>true, 'links'=>true),
    ),
    array(
        'title' => '10 MarÑTh‰tre ÒspecialÓ',
        'url'   => '/edition.php?edition_id=1',
        'features' => array('breadcrumbs'=>true, 'title'=>true, 'links'=>true),
    ),
    array(
        'title' => 'Sunshine and drugs',
        'url'   => '/gallery.php?gallery_id=9',
        'features' => array('breadcrumbs'=>true, 'title'=>true, 'links'=>true),
    ),
    array(
        'title' => 'DSCN1053.JPG',
        'url'   => '/gallery.php?image_mode=detail&image_number=1&gallery_id=9',
        'features' => array('breadcrumbs'=>true, 'title'=>true, 'links'=>true),
    ),
);


OUTPUT
----------------------------------------------------------------
Now, what is useful to generate? This is what you can help brainstorm.

- current page identifier: Not yet sure what constitues a "page identifier". 
- page title: Riparian
- page path: Sacramento River / Glossary Terms / riparian
- breadcrumbs: same as title, but linked and maybe first item called 'home'.
- sublinks: list of pages under current page
- heirarchy links: list of pages under any page. (to get, for ex, all secondary nav links for the current path, to print in some special way.)
- previous page: we can store ALL pages a user browses, and return to any of these.
- entire site heirarcy, linked: for the 'sitemap' page.

In all of these cases, the data is returned in one of two ways:
1. Raw data, usually an array or multidimentional array. Then formatting can be executed specific to a site.
2. Or each function can print the data in a generic fashion marked up in stylesheets.

Here are the functions I propose for data output:

$nav->getPageID()
$nav->getTitle()
$nav->getPath()
$nav->getBreadcrumbs()
$nav->getLinks()
$nav->getHistory()
$nav->getHeirarchy()

$nav->printTitle()
$nav->printTitlePath()
$nav->printBreadcrumbs()
$nav->printLinks()
$nav->printHistory()
$nav->printHeirarchy()

Each function, if given no argument, will return/print data relevent to the current page. Otherwise each can be given $page_id, some kind of identifier for the current page (not sure what this is yet).



INPUT
----------------------------------------------------------------
Maybe it can be put in "automatic mode" where you feed it the site map in a multidimentional array, and it figures out the current page from the URL.

This is ideal if it can be done. Otherwise, in 'manual' mode, for more speciallized sites, the nav input can be generated dynamically, or manually for each page. The first two functions should be all that is necessary for automatic mode, but if you don't have the entire site heirarchy, the other functions must be used.

$nav->setHeirarchy()
$nav->setPageID()
$nav->setPath()
$nav->addCrumb()
$nav->setFeature()
$nav->hasFeature()
$nav->setLinks()


_________________________________________________________
$nav->setHeirarchy()

    To store the overall site architecture. Give it a multidimentional array like:
    $heir = array(
        'title' => 'Home',
        'url'   => '/index.php',
        'features' => array('breadcrumbs'=>true, 'title'=>true, 'links'=>true),
        array(
            'title' => 'Products',
            'url'   => '/products/',
            'features' => array('breadcrumbs'=>true, 'title'=>true, 'links'=>true),
            array(
                'title' => 'Plastic Bags',
                'url'   => '/products/plastic_bags.php'
                'features' => array('breadcrumbs'=>true, 'title'=>true, 'links'=>true),
            ),
            array(
                'title' => 'Paper Bags',
                'url'   => '/products/paper_bags.php'
                'features' => array('breadcrumbs'=>true, 'title'=>true, 'links'=>true),
            ),
            array(
                'title' => 'Vomit Bags',
                'url'   => '/products/vomit_bags.php'
                'features' => array('breadcrumbs'=>true, 'title'=>true, 'links'=>true),
            )
        ),
    );
    $nav->setHeirarchy($heir);

_________________________________________________________
$nav->setPageID()

    If it can't figure out the current page from the url, use this value to set the current page (or override that detected by the url?) Still haven't figured out what constitues a "page identifier". 

    $nav->setPage('case_studies');

_________________________________________________________
$nav->setPath()

    Store the path to the current page. Give it an array like:
    
    $path = array(
        'Home' => '/',
        'Catalog' => '/catalog/',
        'Tools' => '/catalog/tools/',
        'Hammer' => '/catalog/tools/hammer.php',
    )
    $nav->setPath($path);



_________________________________________________________
$nav->addCrumb()

    Add another level to a path begun with setPath(). Use like:
    $nav->addCrumb('Title', 'page_id');
    
    And if a page is at the end of the breadcrumbs it doens't need a url:
    $nav->addCrumb('Add Comment');

_________________________________________________________
$nav->setFeature()

    $nav->setFeature(array('breadcrumbs'=>true, 'title'=>false), 'page_id');

_________________________________________________________
$nav->hasFeature()

    $nav->hasFeature('breadcrumbs');


_________________________________________________________
$nav->setLinks()

    Store the sub links for the current page.
    
    $products = array(
        'Hammers' => '/hammers.php',
        'Screwdrivers' => '/screwdrivers.php',
        'Saws' => '/saws.php',
    )
    $nav->setLinks($products);



-Q