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:
.settings:
enabled_modules: [default, csNavigation]
Set up your site navigation in navigation.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:
csNavigation:
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
//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:
$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
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
- Add tasks to reimport navigation with updated navigation.yml file
- Add administration module for the backend
- Add "attributes" field for configurable HTML attributes
=== 2009-03-29 | 0.9.1 beta ===
* Initial Commit.
Brent Shaffer 