csNavigationPlugin - 1.0.0

csNavigationPlugin: Manage multiple menu trees, active state navigation

You are currently browsing
the website for symfony 1

Visit the Symfony2 website

« Back to the Plugins Home


Forgot your password?
Create an account



advanced search
Information Readme Releases Changelog Contribute
Show source


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


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


Install the plugin:

$ symfony plugin-install http://plugins.symfony-project.com/csNavigationPlugin
$ symfony cc

Enable the module csNavigation in settings.yml:

  enabled_modules:        [default, csNavigation]

Set up your site navigation in navigation.yml:

    ~route:              @homepage
    ~route:            @item1
      child1:            @child1
      child2:            home/child2
      ~route:            @item2
        ~route:          @child3
          ~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:

  class: csNavigationFilter      #Added at "insert your own filters here"

Navigation Tree Usage

Include the navigation helper in your view/layout

<?php use_helper('Navigation') ?>

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

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

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

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

Breadcrumb Usage

Include the navigation helper in your view/layout

<?php use_helper('Navigation') ?>

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

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

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:

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

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

    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     
    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.