Skip to content

Latest commit

 

History

History
305 lines (220 loc) · 7.32 KB

annotation_configuration.md

File metadata and controls

305 lines (220 loc) · 7.32 KB
Raw

Configuration

Add breadcumbs to the trail with annotations in your controller, invokable controller or any other callable. You can add breadcrumbs using annotations, attributes or PHP.

Since version 1.7 annotations are deprecated and using PHP attributes is preferred. Annotations and will be removed in 2.0. After the below basic example all documentation will use attributes.

Basic example

Annotations

use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb;

/**
 * @Breadcrumb("Level 1")
 * @Breadcrumb("Level 2")
 */
class MyController extends Controller
{
    /**
     * @Breadcrumb("Level 3")
     * @Breadcrumb("Level 4")
     */
    public function myAction()
    {
        /* Awesome code here */
    }
}

PHP 8 Attributes

use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb;

#[Breadcrumb(title: 'Level 1')]
#[Breadcrumb(title: 'Level 2')]
class MyController extends Controller
{
    #[Route('/my', name: 'my_action')]
    #[Breadcrumb(title: 'Level 3')]
    #[Breadcrumb(title: 'Level 4')]
    public function myAction(): Response
    {
        /* Awesome code here */
    }
}

Will render the following breadcrumb trail:

Level 1 > Level 2 > Level 3 > Level 4

Reference

The following parameters are available:

A full version of the Attribute looks like:

#[Breadcrumb(
    title: 'string',
    routeName: 'string',
    routeParameters: 'array',
    routeAbsolute: 'bool',
    position: 'int',
    template: 'string',
    attributes: 'array'
#)]

Title

Basic example

See here.

Title using @ParamConverter

The @ParamConverter of the SensioFrameworkExtraBundle convert request parameters like 'id' to objects then injected as controller method arguments:

It is possible to display values of these objects in the breadcrumb.

use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb;

#[Route("/book/{id}")
#[Breadcrumb("Books")]
#[Breadcrumb("{book}")]
public function myAction(Book $book)
{
    /* Awesome code here */
}

Will render the following breadcrumb trail :

Books > "result of __toString method of $book's Object"

use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb;

#[Route("/book/{id}")
#[Breadcrumb("Books")]
#[Breadcrumb("{book.title}")]
public function myAction(Book $book)
{
    /* Awesome code here */
}

Will render the following breadcrumb trail :

Books > result of getTitle method of $book's Object

Note: The bundle tries to call the methods : getTitle, hasTitle or isTitle.

use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb;

#[Route("/book/{id}")
#[Breadcrumb("Books")]
#[Breadcrumb("{book.title:argument1}")]
public function myAction(Book $book)
{
    /* Awesome code here */
}

Will render the following breadcrumb trail :

Books > result of getTitle('argument1') method of $book's Object

use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb;

#[Route("/book/{id}")
#[Breadcrumb("Books")]
#[Breadcrumb("{book.title:argument1,argument2}")]
public function myAction(Book $book)
{
    /* Awesome code here */
}

Will render the following breadcrumb trail :

Books > result of getTitle('argument1', ' argument2') method of $book's Object

Route name

Assume that you have defined the following route :

use Symfony\Component\Routing\Annotation\Route;

#[Route('/var/{var}', name: 'my_route')]

Basic example

use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb;

#[Breadcrumb("Level 1", routeName: 'my_route')]
#[Breadcrumb("Level 2")]

Will render the following breadcrumb trail :

Level 1 > Level 2

Route parameters

When your the current request context is that you are the my_action_route with url http://example.com/var/foo/var1/bar.

use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb;
use Symfony\Component\Routing\Annotation\Route;

#[Route("/var/{var}/var1/{var1}", name: 'my_action_route')]
#[Breadcrumb("Level 1", routeName: 'my_route', routeParameters: ['var' => '1'])]
#[Breadcrumb("Level 2", routeName: 'my_route', routeParameters: ['var' => 'foo'])]
#[Breadcrumb("Level 3", routeName: 'my_route', routeParameters: ['var'])]
#[Breadcrumb("Level 4", routeName: 'my_route', routeParameters: ['var' => '{var1}'])]
#[Breadcrumb("Level 5")]

Will render the following breadcrumb trail :

Level 1 > Level 2 > Level 3 > Level 4 > Level 5

Complex parameters

Assume your controllers are designed like a REST API and you have a ManyToOne relationship on Book -> Author :

use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb;
use Symfony\Component\Routing\Annotation\Route;

#[Route("/books/{book}", name: 'book', requirements: ['book' => "\d+"])]  // example: /book/53
#[Breadcrumb({book.author.name}, routeName: 'author', routeParameters: ['author' => {book.author.id}])]  // example: /author/15
#[Breadcrumb({book.title}, routeName: 'book', routeParameters: ['book' => {book.id}])]
public function indexAction(Request $request, Book $book): array {
    return [
        'id'     => $book->getId(),
        'title'  => $book->getTitle(),
        'author' => $book->getAuthor()->getName(),
    ];
}

Will render the following breadcrumb trail :

Author Name > Book title

Route absolute

Passing routeAbsolute will inform the router to render the routes as absolute, based on the current router request context.

use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb;

#[Breadcrumb("Level 1", routeName: 'my_route', routeParameters: ['var1' => 1, 'var2' => 2], routeAbsolute: true)]

Position

use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb;

#[Breadcrumb("Level 1")]
#[Breadcrumb("Level 2", position: 1)]
#[Breadcrumb("Level 3")]
#[Breadcrumb("Level 4", position: -1)]

Will render the following breadcrumb trail :

Level 2 > Level 1 > Level 4 > Level 3

Note: position=0 will put the breacrumb to the end of the trail.

HTML Attributes

The attributes parameter can be provided to show attributes in the rendered html.

use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb;

#[Breadcrumb("Level 1", attributes: ["class" => "yellow", "title" => "Hello world !"])]
#[Breadcrumb("Level 2")]

Will render the following breadcrumb trail :

<ul id="breadcrumbtrail">
    <li class="home">Home</li>
    <li class="yellow" title="Hello world !">
        <span>Level 1</span>
    </li>
    <li class="current">
        <span>Level 2</span>
    </li>
</ul>

Extra

Reset the trail

Adding a ResetBreadcrumbTrail attribute will remove all existing breadcrumbs from the trail.

Resetting might come in handy in case the controller class unwantedly defines breadcrumbs already.

use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb;
use APY\BreadcrumbTrailBundle\Annotation\ResetBreadcrumbTrail;

#[Breadcrumb("Level 1")]
#[ResetBreadcrumbTrail()]
#[Breadcrumb("Level 2")]
#[Breadcrumb("Level 3")]

Will render the following breadcrumb trail :

Level 2 > Level 3