= sfBreadcrumbs plugin =

== Overview ==

This plugin adds the ability to create Breadcrumbs(AKA: Navigation Path) in any template.

== Installation ==

To install sfHelperExample:

{{{
symfony plugin-install local|global symfony/sfBreadcrumbsPlugin
}}}

== Usage ==

'''Step One:''' Create a file named '''breadcrumbs.you''' and place it in '''your_app/config''' directory and follow the next examples.
Suppose you're working on a website where the main navigation menu consists of the following items:
  * Home
  * Categories
    * Show All
    * Add New
  * Products
    * Show All
    * Add New
And as you might have guessed, Home, Categories, and Products are just virtual sections in the website grouping some actions together,
for example, the Show All and Add New actions for categories or products. Since all these actions are probably placed in the same module
it's hard to display the Breadcrumbs to the user based on just the action and module names, and this is where this plugin comes in handy.
Consider the following breadcrumbs.yml example, and don't be intimidated, I'll explain each node in the file.

In the below example, mymodule is a name of a module available in an application for example called myapp. mymodule consists of several actions:

 * categoriesAction
 * showCategoriesAction
 * addNewCategoryAction
 * productsAction
 * showProductsAction
 * addNewProductAction

As you can see, some of these actions are related to a certain entity(ex: '''Category'''), and I want to group categoriesAction, showCategories, and addNewCategory in a menu(i.e. section) called '''Categories'''. All I've to do is write the following in '''breadcrumbs.yml''' under tags.

{{{
all:
  mymodule:
    name: My Module
    sections:
      categories:
        name: Categories
        actions:
          categories:
            name: Categories
          newCategory:
            name: New Category
          
          showCategories:
            name: Show Available Categories
      
      products:
        name: Products
        actions:    
          products:
            name: Product
          newProduct:
            name: New Product
          
          showProducts:
            name: Show Available Products
}}}

In the above example, '''mymodule''' is the actual name of the module, '''My Module''', is the name displayed in the '''Breadcrumbs''' presented to the user. The same goes for '''section''', and '''action'''.

'''Step Two:''' Next, create if a file name '''config_handlers.yml''' and place it in '''your_app/config''' directory and paste the following in that file

'''For symfony 1.0.x'''
{{{
config/breadcrumbs.yml:
  class:    sfBreadcrumbsConfigHandler
}}}

'''For symfony 1.1.x'''
{{{
config/breadcrumbs.yml:
  class:    sfBreadcrumbsConfigHandler
  file: %SF_PLUGINS_DIR%/sfBreadcrumbsPlugin/lib/sfBreadcrumbsConfigHandler.php
}}}

'''Step Three:''' place the following code in '''your_app/config/config.php''' file. Note in symfony 1.1 the config.php file is replaced by app_nameConfiguarion.class.php

'''For symfony 1.0.x'''
{{{
include_once( sfConfigCache::getInstance()->checkConfig( sfConfig::get('sf_apps_dir_name').'/config/breadcrumbs.yml' ) );
}}}

'''For symfony 1.1.x'''
{{{
public function configure()
{
	require_once($this->getConfigCache()->checkConfig(sfConfig::get('sf_app_config_dir').'/breadcrumbs.yml'));
}
}}}

'''Step Four:''' Finally in order to display the '''breadcrumbs''' text in the website, open for example the '''layout.php''' located in the '''templates''' folder under your application, and add the following
anywhhere, enjoy.

{{{
<?php echo sfBreadcrumbs::getInstance()->getBreadcrumbText() ?>
}}}

== To-Do ==
 * Add parameters to the Breadcrumbs text
 * Write complete API and User documentation

== License ==

For the full copyright and license information, please view the LICENSE
file that was distributed with this source code.