sfBreadcrumbPlugin - 1.0.0

Provides breadcrumb functionality for the symfony framework

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

sfBreadcrumbPlugin

The sfBreadcrumbPlugin dynamically tracks users locations via a breadcrumb.yml files placed in your modules config directory. It leverages symfony's config handlers and filters functionality to provide a seamless symfony integration and facilitate extension or overriding at the application level.

Installation

  • Install the plugin

    $ symfony plugin:install sfBreadcrumbPlugin
    
  • Enable the breadcrumb filter in APP_NAME/config/filters.yml or you will encounter an exception as it is defined and cascaded into the filters chain in the plugins config directory.

    # insert your own filters here
    breadcrumb: ~
  • If you want to extend sfBreadcrumbFilter you can create your own object and override the initialization in your applications filters.yml

    breadcrumb:
      class: myBreadcrumbFilter
  • Clear the cache

    $ symfony cache:clear
    

Configuration

The sfBreadcrumbPlugin is configured via your applications config/app.yml and gets default values from the app.yml packaged with the plugin. The following configuration parameters are available:

  • breadcrumb_class: Provides the option to override/extend the sfBreadcrumb object

  • record_locations_num: The number of locations to register in the users session.

  • display_locations_num: The number of locations to render.

  • register_post_request: Set to 'on' to allow registering POST request to be registered. Currently, the link will still be a GET url of the route however urls that create the POST request can be created if the need arises.

  • breadcrumb_separator: This value will be printed before each link except the first one.

  • breadcrumb_template: During the render() process, each generated link is passed to sprintf so you can define a custom template. Something like '<li>%s</li>' sounds like a good override.

Here are the default settings located in sfBreadcrumbPlugin/config/app.yml

all:
  sfBreadcrumbPlugin:
    breadcrumb_class: sfBreadcrumb
    record_locations_num:  5
    display_locations_num: 5
    register_post_request: off
    breadcrumb_separator: ' :: '
    breadcrumb_template: '%s'

Defining Crumbs

Registering a crumb is as easy as placing a breadcrumb.yml file in your modules config directory. The top value 'index' is the action name of the module and link is the value that will display as the link.

index:
  link: Home

You can also set an image as the link in your breadcrumb.yml:

index:
  link: <?php echo image_tag('/path/to/my/image.gif'); ?>

Rendering The Breadcrumb

To output the breadcrumb simply call the render method from your template. Typically, the layout file is the ideal place to do this.

sfBreadcrumb::render();

Extending sfBreadcrumb

By changing the breadcrumb_class option in your applications app.yml you are able to completely override or extend the sfBreadcrumbPlugin. The following modifications are required to complete this extension:

In APP_NAME/config/app.yml:

all:
  sfBreadcrumbPlugin:
    breadcrumb_class: myBreadcrumb

Create the myBreadcrumb object in a location symfony can find it such as your projects lib folder

class myBreadcrumb extends sfBreadcrumb
{
  public static function getInstance()
  {
    if(!self::$instance instanceof myBreadcrumb)
    {
      self::$instance = new myBreadcrumb();
    }
 
    return self::$instance;
  }
 
  public static function render()
  {
    // ...
  }
}