Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A small breadcrumbs bundle for Symfony2
branch: master

Merge pull request #40 from bocharsky-bw/patch-1

Add syntax highlighting for better readability
latest commit b6c781810f
Rich Sage richsage authored

README.md

Installation

NB There is now no need to use the 2.1 branch when installing; the bundle is compatible with 2.0 upwards. Use the master branch instead.

  1. Add this bundle to your vendor/ dir using the vendors script:

    Add the following lines in your deps file:

    [WhiteOctoberBreadcrumbsBundle]
        git=git://github.com/whiteoctober/BreadcrumbsBundle.git
        target=/bundles/WhiteOctober/BreadcrumbsBundle

    and run the vendors script:

    ./bin/vendors install

    Or add the following to your composer.json:

    "whiteoctober/breadcrumbs-bundle": "dev-master"

    and run:

    php composer.phar install

    The bundle is compatible with Symfony 2.0 upwards.

  2. If you're not using Composer, add the WhiteOctober namespace to your autoloader:

    // app/autoload.php
    $loader->registerNamespaces(array(
        'WhiteOctober' => __DIR__.'/../vendor/bundles',
    ));
  3. Add this bundle to your application's kernel:

    // app/AppKernel.php
    public function registerBundles()
    {
        return array(
            // ...
            new WhiteOctober\BreadcrumbsBundle\WhiteOctoberBreadcrumbsBundle(),
            // ...
        );
    }
  4. Configure the white_october_breadcrumbs service in your config.yml:

    white_october_breadcrumbs: ~

    That's it for basic configuration.

Usage

In your application controller methods:

public function yourAction(User $user)
{
    $breadcrumbs = $this->get("white_october_breadcrumbs");
    // Simple example
    $breadcrumbs->addItem("Home", $this->get("router")->generate("index"));

    // Example without URL
    $breadcrumbs->addItem("Some text without link");

    // Example with parameter injected into translation "user.profile"
    $breadcrumbs->addItem($txt, $url, array("%user%" => $user->getName()));
}

and then in your template:

{{ wo_render_breadcrumbs() }}

The last item in the breadcrumbs collection will automatically be rendered as plain text rather than a <a>...</a> tag.

The addItem() method adds an item to the end of the breadcrumbs collection. You can use the prependItem() method to add an item to the beginning of the breadcrumbs collection. This is handy when used in conjunction with hierarchical data (e.g. Doctrine Nested-Set). This example uses categories in a product catalog:

public function yourAction(Category $category)
{
    $breadcrumbs = $this->get("white_october_breadcrumbs");

    $node = $category;

    while ($node) {
        $breadcrumbs->prependItem($node->getName(), "<category URL>");

        $node = $node->getParent();
    }
}

Configuration

The following parameters can be overriden in your config.yml or similar:

white_october_breadcrumbs:
    separator:          defaults to '/'
    separatorClass:     defaults to 'separator'
    listId:             defaults to 'wo-breadcrumbs'
    listClass:          defaults to 'breadcrumb'
    itemClass:          defaults to ''
    linkRel:            defaults to ''
    locale:             defaults to null, so the default locale is used
    translation_domain: defaults to null, so the default domain is used
    viewTemplate:       defaults to "WhiteOctoberBreadcrumbsBundle::breadcrumbs.html.twig"

These can also be passed as parameters in the view when rendering the breadcrumbs - for example:

{{ wo_render_breadcrumbs({separator: '>', listId: 'breadcrumbs'}) }}

Advanced Usage

You can add a whole array of objects at once

$breadcrumbs->addObjectArray(array $objects, $text, $url, $translationParameters);
objects:            array of objects
text:               name of object property or closure
url:                name of URL property or closure

Example:

$that = $this;
$breadcrumbs->addObjectArray($selectedPath, "name", function($object) use ($that) {
    return $that->generateUrl('_object_index', array('slug' => $object->getSlug()));
});

You can also add a tree path

$breadcrumbs->addObjectTree($object, $text, $url = "", $parent = 'parent', array $translationParameters = array(), $firstPosition = -1)
object:             object to start with
text:               name of object property or closure
url:                name of URL property or closure
parent:             name of parent property or closure
firstPosition:      position to start inserting items (-1 = determine automatically)

Overriding the template

There are two methods of doing this.

  1. You can override the template used by copying the Resources/views/breadcrumbs.html.twig file out of the bundle and placing it into app/Resources/WhiteOctoberBreadcrumbsBundle/views, then customising as you see fit.

  2. Use the viewTemplate configuration parameter:

    {{ wo_render_breadcrumbs({ viewTemplate: "YourOwnBundle::yourBreadcrumbs.html.twig" }) }}
Something went wrong with that request. Please try again.