Developed with love by KnpLabs Hire us for your project!
208

BreadcrumbsBundle

by sampart

A small breadcrumbs bundle for Symfony

WARNING: This project is no longer maintained.
If you are using it with Symfony >= 4.3, you may want to use this fork instead.

Installation

  1. Configure templating for your application if you haven't already. For example:

    # app/config/config.yml (Symfony <=3)
    framework:
        templating:
            engines: ['twig']
    
    # config/packages/framework.yaml (Symfony 4)
    templating:
        engines: ['twig']
    
  2. Install this bundle using Composer:

    composer require whiteoctober/breadcrumbs-bundle
    
  3. Add this bundle to your application's kernel:

    // app/AppKernel.php
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new WhiteOctober\BreadcrumbsBundle\WhiteOctoberBreadcrumbsBundle(),
            // ...
        );
    }
    

    If you're using Symfony 4, this step will be done for you by Symfony Flex.

  4. Configure the bundle in your config:

    # app/config/config.yml
    white_october_breadcrumbs: ~
    

That's it for basic configuration. For more options check the Configuration section.

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, ["%user%" => $user->getName()]);
}

For Symfony 4, don't retrieve the service via get, instead use
dependency injection:

use WhiteOctober\BreadcrumbsBundle\Model\Breadcrumbs;

class YourController extends AbstractController
{
    public function yourAction(Breadcrumbs $breadcrumbs)
    {
      // ...
    }
}

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();
    }
}

If you do not want to generate a URL manually, you can easily add breadcrumb items
passing only the route name with any required parameters, using the addRouteItem()
and prependRouteItem() methods:

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

    // Pass "_demo" route name without any parameters
    $breadcrumbs->addRouteItem("Demo", "_demo");

    // Pass "_demo_hello" route name with route parameters
    $breadcrumbs->addRouteItem("Hello Breadcrumbs", "_demo_hello", [
        'name' => 'Breadcrumbs',
    ]);

    // Add "homepage" route link at the start of the breadcrumbs
    $breadcrumbs->prependRouteItem("Home", "homepage");
}

Configuration

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

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

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

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

NOTE: If you need more than one set of breadcrumbs on the same page you can use namespaces.
By default, breadcrumbs use the default namespace, but you can add more.
To add breadcrumbs to your custom namespace use addNamespaceItem / prependNamespaceItem
or addNamespaceRouteItem / prependNamespaceRouteItem methods respectively, for example:

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

    // Simple example
    $breadcrumbs->prependNamespaceItem("subsection", "Home", $this->get("router")->generate("index"));

    // Example without URL
    $breadcrumbs->addNamespaceItem("subsection", "Some text without link");

    // Example with parameter injected into translation "user.profile"
    $breadcrumbs->addNamespaceItem("subsection", $txt, $url, ["%user%" => $user->getName()]);

    // Example with route name with required parameters
    $breadcrumbs->addNamespaceRouteItem("subsection", $user->getName(), "user_show", ["id" => $user->getId()]);
}

Then to render the subsection breadcrumbs in your templates, specify this namespace in the options:

{{ wo_render_breadcrumbs({namespace: "subsection"}) }}

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', ['slug' => $object->getSlug()]);
});

You can also add a tree path

$breadcrumbs->addObjectTree($object, $text, $url = "", $parent = 'parent', array $translationParameters = [], $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)

NOTE: You can use addNamespaceObjectArray and addNamespaceObjectTree respectively
for work with multiple breadcrumbs on the same page.

Overriding the template

There are two methods for doing this.

  1. You can override the template used by copying the
    Resources/views/microdata.html.twig file out of the bundle and placing it
    into app/Resources/WhiteOctoberBreadcrumbsBundle/views, then customising
    as you see fit. Check the Overriding bundle templates documentation section
    for more information.

  2. Use the viewTemplate configuration parameter:

    {{ wo_render_breadcrumbs({ viewTemplate: "YourOwnBundle::yourBreadcrumbs.html.twig" }) }}
    

    NOTE: If you want to use the JSON-LD format, there's already an existing template
    at WhiteOctoberBreadcrumbsBundle::json-ld.html.twig. Just set this template as the value for
    viewTemplate either in your Twig function call (see Step 2 above) or in your bundle configuration.

(This project was originally at https://github.com/whiteoctober/BreadcrumbsBundle)

Copyright (c) 2011-2012 White October Ltd
http://www.whiteoctober.co.uk/

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
white_october_breadcrumbs:
separator: /
separatorClass: separator
listId: wo-breadcrumbs
listClass: breadcrumb
itemClass:
linkRel:
locale: ~
translation_domain: ~
viewTemplate: WhiteOctoberBreadcrumbsBundle::microdata.html.twig
  • Remove contribution section in readiness for archiving
    By web-flow, 9 days ago
  • Merge pull request #115 from sweoggy/patch-1
    By web-flow, 2 months ago
  • Add info to Composer about replacement package
    By web-flow, 2 months ago
  • Merge pull request #113 from bocharsky-bw/patch-1
    By web-flow, 9 months ago
  • Make warning about end of maintenance more noticeable
    By web-flow, 9 months ago
  • Fix spaceless tag deprecations (#110)
    By sampart, 1 year ago
  • Add link to fork to README
    By sampart, 1 year ago
  • Merge pull request #108 from Daamian/master
    By web-flow, 1 year ago
  • Merge pull request #109 from andreybolonin/patch-2
    By web-flow, 1 year ago
  • add php 7.4snapshot
    By web-flow, 1 year ago
  • Change EngineTemplating to Twig for fix Symfony 4.3 deprecations
    By , 1 year ago
  • Add message about looking for maintainers
    By Sam Partington, 1 year ago
  • Merge pull request #105 from mhujer/travis-tests
    By web-flow, 1 year ago
  • Travis: run existing tests
    By mhujer, 1 year ago
  • Merge pull request #104 from mhujer/fix-travis
    By web-flow, 1 year ago
  • composer.json: loosen version constraints
    By mhujer, 1 year ago
  • Travis: remove EOLd Symfony versions
    By mhujer, 1 year ago
  • Travis: remove PHP: master
    By mhujer, 1 year ago
  • Merge pull request #101 from mhujer/phpstorm-autocompletion-metadata
    By web-flow, 1 year ago
  • add metadata to help PhpStorm Symfony plugin with route/translationKey autocompletion
    By mhujer, 1 year ago
  • Merge pull request #100 from whiteoctober/install-usage-docs-update
    By web-flow, 1 year ago
  • Remove allusion to Symfony 1
    By Sam Partington, 1 year ago
  • Add note about getting the breadcrumbs service in Symfony 4
    By Sam Partington, 1 year ago
  • Add note about Symfony Flex adding the bundle in sf4
    By Sam Partington, 1 year ago
  • Re-order installation docs - configure templating first
    By Sam Partington, 1 year ago
  • Remove some unnecessary documentation detail around composer
    By Sam Partington, 1 year ago
  • Add PHP 7.3 to .travis.yml (#98)
    By Sam Partington, 1 year ago
  • Merge pull request #97 from mhujer/symfony42
    By web-flow, 1 year ago
  • Fix deprecation for symfony/config 4.2
    By mhujer, 1 year ago
  • Merge pull request #96 from chteuchteu/doc-fix
    By web-flow, 2 years ago