csNavigationPlugin
==================

The csNavigationPlugin is a simple way to handle navigation in your applications.

csNavigationPlugin works with Symfony 1.2.

At a glance
-----------

 * A navigation object to manage multiple trees. All navigation is located under a single root to represent the sitemap
 * Navigation trees can be segmented by level and iteration (starting root, number of levels drilled down)
 * Automated active handling / expanding of children / route detection
 * Drive your navigation using a navigation.yml file or pull from your database, or both
 * A singleton who manages breadcrumbs. By default, a root item is present (text: Home, uri: @homepage)
 * A component who display the breadcrumbs

License
-------

The csNavigationPlugin is licensed under the GNU Lesser General Public License (LGPL).

Installation
------------

*Install the plugin*:
 
    $ symfony plugin-install http://plugins.symfony-project.com/csNavigationPlugin
    $ symfony cc
 
*Enable the module csNavigation in settings.yml*:
 
    [yml]
    .settings:
      enabled_modules:        [default, csNavigation]
 
*Set up your site navigation in navigation.yml*:

    [yml]
    navigation:
      Home:   
        ~route:              @homepage
        item1: 
        ~route:            @item1
          child1:            @child1
          child2:            home/child2
        item2: 
          ~route:            @item2
          child3:    
            ~route:          @child3
            grandchild1:     
              ~route:       @grandchild1
              ~protected:   on
            google:          http://www.google.com

    Foo:                   #multiple navigation roots is supported
      Bar:    @bar

The csNavigationRoute class supports token routes, internal routes, wildcards (*), and absolute urls.  It also supports 
token routes with variables (:slug), and matches these by looking for the variable in the Request.  If this isn't found,
it calls a camelized method on the menu object (csNavigationMenu::getDefaultSlug() in this case).  More information on
the navigation.yml file is below.

  
*Add the csNavigationFilter class to your filters.yml*:

    [yml]
    csNavigation:
      class: csNavigationFilter      #Added at "insert your own filters here"
  
Navigation Tree Usage
---------------------

Include the navigation helper in your view/layout

    [php]
    <?php use_helper('Navigation') ?>

use the helper function to include your tree (in the layout for instance):

    [php]
    <?php include_navigation(array('id' => 'navigation')) ?>

specify level and/or iteration (default iteration is 2):

    [php]
    <?php include_navigation(array('level' => 1, 'iteration' => 3)) ?>

Breadcrumb Usage
----------------

Include the navigation helper in your view/layout

    [php]
    <?php use_helper('Navigation') ?>


Include the breadcrumbs component (in the layout for instance):

    [php]
    You are here :
    <?php include_breadcrumbs() ?>

If you want to customize the breadcrumb, you can override the generated breadcrumb by 
calling the csBreadcrumbs singleton in your action

    [php]
    //module/actions/actions.class.php
    csBreadcrumbs::getInstance()->addItem('My Item', '@route');  //Renders home > My Item
    csBreadcrumbs::getInstance()->addItem('Another Item');  //Renders home > My Item > Another Item

The last item in the list is never a link, so your breadcrumbs can be easily stacked in your modules

You can also specify the navigation used to generate your breadcrumb by passing the csNavigationMenu 
instance or the name of the menu:

    [php]
    $menu = Doctrine::getTable('csNavigationMenu')->getMenu('Administration');
    $breadcrumb = new csBreadcrumbs($menu)
    // OR:
    $breadcrumb = new csBreadcrumbs('Administration');
    $breadcrumb->getItems();  

The __getItems()__ method returns an array of csNavigationItems generated from current navigation's active state;

The navigation.yml File
-----------------------

Item attributes are prefixed by a tilde (~) and child items are added as displayed above.  possible attributes are

  * _route_:     the item route
  * _locked_:    the item cannot be moved, good to solidify core navigation
  * _protected_: requires user authentication
  * any fields added to the csNavigationItem can also be set in the YAML file

Navigation Settings
-------------------
  
    [yml]
    settings:
      database:
        driven:      off                # imports the above yaml file into the database
        locked:      off                # locks the provided yaml file from editting in the database
        branch:      item2              # the branch attribute locks everything outside the branch indicated     
      expanding:
        default:            on
        level:              2

Change your database driven setting to on, and csNavigationPlugin will automatically 
convert your YAML navigation file to your database.  This allows you to build-all-reload
and reconstruct your navigation on the fly. You can also set the import settings so 
the core navigation cannot be changed by the user, or certain branches cant be changed

Setting and expanding level will determine how your navigation is displayed by default.
You can chose to have no items expanded until they are active, or expand out to a certain level.

To Do
-----
  1. Add tasks to reimport navigation with updated navigation.yml file
  2. Add administration module for the backend
  3. Add "attributes" field for configurable HTML attributes

=== 2009-03-29 | 0.9.1 beta ===
 * Initial Commit.