## Usage

### Basic

A breadcrumb tree is created by the fields `label` and `parent_route` in the `defaults` of a route. Basic tree example:

# routing.yml

acme_demo_home:
path: /
options:
breadcrumb:
label: Home

acme_demo_contact:
path: /contact
options:
breadcrumb:
label: Contact
parent_route: acme_demo_home

acme_demo_catalogue:
path: /catalogue
options:
breadcrumb:
label: 'Our Catalogue'
parent_route: acme_demo_home

acme_demo_catalogue_categories:
path: /catalogue/categories
options:
breadcrumb:
label: 'All categories'
parent_route: acme_demo_catalogue

Would result in a breadcrumb tree like:

acme_demo_home
|- acme_demo_contact
`- acme_demo_catalogue
`- acme_demo_catalogue_categories

If the current route is `acme_demo_catalogue`, the breadcrumbs would for instance show the following:

Home > Our Catalogue

Since the configuration of the breadcrumbs happens on routing config, it's generally agnostic from _how_ the routing
configuration happens. This means that configuring breadcrumbs for instance via annotations is perfectly possible:

/**
* ...
* @Route(
* "/contact",
* name="acme_demo_contact",
* options={
* "breadcrumb" = {
* "label" = "Contact",
* "parent_route" = "acme_demo_home"
* }
* })
* ...
*/

The configuration can also be done in XML and PHP.

### Dynamic routes

If you happen to have dynamic routes or dynamic translations that you need in your breadcrumbs, they
can be defined like so:

# routing.yml

acme_demo_product_detail:
path: /products/{id}
options:
breadcrumb:
label: 'Produkt: %%name%%'
parent_route: acme_demo_catalogue

(This example uses a string with a placeholder in the routing directly. You can also define the label text in a
translation file and only use the translation key as the label. The template will handle the translation and
replacing.)

**Notice the double `%` to escape the parameter in the label. This needs to be done, because `routing.yml`
is being parsed by the Symfony container and recognizes constructs, such as `%name%` as a container parameter
and tries to inject those. The double-`%` escapes it, the template is handling the rest.**

You can then set parameters for both directly on the `Breadcrumb` object, for instance:

get('thormeier_breadcrumb.breadcrumb_provider')
->getBreadcrumbByRoute('acme_demo_product_detail')
->setRouteParams(array(
'id' => $product->getId(),
))
->setLabelParams(array(
'name' => $product->getName(),
));

// ...
}

Please note that the breadcrumb must be defined on the route in order to set parameters.

### Dynamic breadcrumbs

If you happen to have a dynamic routing tree, for instance a tree of category pages that can go infinitely deep,
you can add breadcrumbs that are not defined on a route on the fly. For instance like this:

getBreadcrumbByRoute('acme_demo_product_detail');
$collection = $breadcrumbProvider->getBreadcrumbs();

foreach ($product->getCategories() as $category) {
$newCrumb = new Breadcrumb(
'Category: %name%', // Label
'acme_demo_category', // Route
['id' => $category->getId()], // Route params
['name' => $category->getName()] // Label params
);

// Adds $newCrumb right in front of $productCrumb
$collection->addBreadcrumbBeforeCrumb($newCrumb, $productCrumb);

// Or: ->addBreadcrumb(), ->addBreadcrumbAtPosition(), ->addBreadcrumbAfterCrumb(), ->addBreadcrumbToStart()
}

These breadcrumbs are not stored in the cache though.

### Displaying in twig

Call the twig extension as following:

{# someTemplate.html.twig #}
{# ... #}

{{ breadcrumbs() }}

{# ... #}

### Using the bootstrap template

The bundle also provides a default implementation for [Bootstrap](https://getbootstrap.com/docs/4.3/components/breadcrumb/). It can be used as follows:

# config.yml
thormeier_breadcrumb:
template: @ThormeierBreadcrumb/breadcrumbs_bootstrap.html.twig

### Replacing the default template

If you want to use a custom template, add the following to your config.yml

# config.yml
thormeier_breadcrumb:
template: 'my twig template path'

Your custom breadcrumb template receives a variable called `breadcrumbs` that is a collection that represents your
breadcrumbs, ordered by highest in the tree to lowest.

A single `breadcrumb` has the fields `route`, `routeParameters`, `label` and `labelParameters`. `route` and `routeParameters`
are used to generate a path in twig, i.e. `path(breadcrumb.route, breadcrumb.routeParameters)`, whereas `label` and
`labelParameters` are used to generate the text for the breadcrumb, i.e.
`{{ (breadcrumb.label)|trans(breadcrumb.labelParameters) }}`

Your custom template might look something like this:

{# myBreadcrumbs.html.twig #}