prestaBreadcrumbPlugin - 1.0.3

Give an easy way to construct breadcrumbs

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source

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