prestaBreadcrumbPlugin plugin
The prestaBreadcrumbPlugin plugin helps you to build breadcrumbs in your application.
This plugin allow you to easily define and display complete breadcrumb in an application.
You can define your breadcrumbs statically (in configuration files) ou dynamically (in actions).
Installation
Install the plugin:
./symfony plugin:install prestaBreadcrumbPlugin
./symfony cc
Enable the module and the helper prestaBreadcrumb in your applications config/settings.yml:
all:
.settings:
# Helpers included in all templates by default
standard_helpers: [Partial, Cache, Form, prestaBreadcrumb]
# Activated modules from plugins or from the symfony core
enabled_modules: [default, prestaBreadcrumb]
Configuration
A default configuration is given in the plugin conf directory (/plugins/prestaBreadcrumbPlugin/conf/app.yml)
You can redefine all values in your application config/app.yml
# /apps/%APP_NAME%/config/app.yml
#all:
# # prestaBreadcrumbPlugin configuration
# prestaBreadcrumb:
# class: prestaBreadcrumb # The name of the class used for rendering the breadcrumb
# catalogI18n: messages # The name of the catalog to use to translate
# home: 'Home' # The text for the link to the homepage, always included at begin of the render
# home_uri: '@homepage' # The uri of the homepage for the first link
# separator: ' > ' # The separator printed between each link
# template: '%s' # The template use to render the breadcrumb (%s will be replaced bye the breadcrumb)
# useMicrodata: true # Enable microdata format in the breadcrumb rendering
# # Specific configuration for the last item
# last:
# is_link: false # Display the last item as a link
# #html_class: # HTML class of the last item container
# #html_id: # HTML Id of the last item container
Usage
Define crumbs
There is several methods to define breadcrumbs :
Actions
public function executeMyAction()
{
prestaBreadcrumb::getInstance()->addItem('Article', '@article');
}
Or you can activate the translation by adding true
public function executeMyAction()
{
prestaBreadcrumb::getInstance()->addItem('Article', '@article', true);
}
Configuration
Defined crumbs in your module config/breadcrumb.yml
article:
text: 'Article'
uri: '@article'
The texts of YML files are automatically translated if the i18n config is activated
TODO : complete this section
If the crumbs are defined both in your actions and config/breadcrumb.yml, the configuration
in your action will be used primarily.
Define your own class to personalize the breadcrumb render
# /apps/%APP_NAME%/config/app.yml
all:
# prestaBreadcrumbPlugin configuration
prestaBreadcrumb:
class: myPrestaBreadcrumb
WARNING : Your class must extends to prestaBreadcrumb
Rendering the Breadcrumb
To output the breadcrumb, simply include the component.
include_component('prestaBreadcrumb', 'show');
You can also used the helper, like that.
$breadcrumbs = array(
array('text' => 'News', 'uri' => '@news'),
array('text' => 'Article', 'uri' => '@article'),
// ...
);
display_prestabreadcrumb($breadcrumbs);
Or
$breadcrumb = prestaBreadcrumb::getInstance()
->addItem('News', '@news')
->addItem('Article', '@article')
;
display_prestabreadcrumb($breadcrumb);
Or, you can just call the render method.
echo prestaBreadcrumb::getInstance()->render();
Use view cache
If you want to activate view cache and if you have render your breadcrumb outside of the cache limit (for example, the breadcrumb is rendered in the layout, and the cache config dont cache layout), you have to give a cache key when you call the component.
The following configuration will cache the breadcrumb for each url. So, each time user will ask for a cached page, the breadcrumb will be extract from the cache
Create a "apps/%appname%/modules/prestaBreadcrumb/config/cache.yml" config file who contain :
_show:
enabled: on
all:
with_layout: false # Default value
lifetime: 86400 # Default value
Change the way you call the components to pass a cache key unique for each page :
include_component('prestaBreadcrumb', 'show', array('sf_cache_key' => sfContext::getInstance()->getRouting()->getCurrentRouteName()))
WARNING : We are aware that this technique does not save multiple breadcrumb values for an url. However, we believe that the breadcrumb should be as individual as a url, and we therefore see no point in providing this case.
If you feel the need to use it this way, feel free to offer us a patch.
Changelog
2011-08-19 | 1.0.3
- [bugfix][D9257] prestaBreadcrumb does no longer break functionnal testing execution.
- [D8220] The microdata format management has been added and enabled by default. May be disabled. (Care of this point for upgrade as the generated HTML is not the same)
- You can now define your own class for rendering the breadcrumb.
2010-08-12 | 1.0.2
- Add cache on render component to avoid breadcrumb strange behavior on cached actions
2010-06-14 | 1.0.1
- BUGFIX : The plugin no longer uses the non-existent class puPHP
2010-04-26 | 1.0.0
- bugfix : default breadcrumb elements separator now correctly render spaces (non breakable spaces)
- the prestaBreadcrumb::clearItems() dont delete the root item anymore
- update README file to explain how to use the plugin with view cache use
- Add specific operating for last item rendering. By default, this last link is no more a link
- Add specific HTML configurtion for the last item. Can now add a class or an id for the last link
Christophe DOLIVET 
Mikaël RANDY 
Julien Fusco 