README

简介

此 Symfony 扩展包通过路由配置和 Twig 模板渲染实现了面包屑导航的集成。本扩展包深受已停用的 https://github.com/xi-project/xi-bundle-breadcrumbs 启发。

安装

步骤 1: Composer require

$ php composer.phar require "thormeier/breadcrumb-bundle"

步骤 2: 在内核中启用扩展包

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Thormeier\BreadcrumbBundle\ThormeierBreadcrumbBundle(),
        // ...
    );
}

配置

在 config.yml 中启用扩展包

# config.yml
thormeier_breadcrumb: ~

模板默认为一个非常基本的模板，提供一个包含 <li> 和 <a> 的 <ul>，每个面包屑对应一个。

用法

基本用法

通过路由的 defaults 中的 label 和 parent_route 字段创建面包屑树。基本树示例

# 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

将生成以下面包屑树

acme_demo_home
    |- acme_demo_contact
    `- acme_demo_catalogue
       `- acme_demo_catalogue_categories

如果当前路由是 acme_demo_catalogue，面包屑将显示如下

Home > Our Catalogue

由于面包屑配置发生在路由配置上，所以通常与如何进行路由配置无关。这意味着通过注解等方式配置面包屑是完全可能的

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

配置也可以在 XML 和 PHP 中完成。

动态路由

如果您有动态路由或需要在面包屑中使用的动态翻译，可以像这样定义

# routing.yml

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

(此示例使用直接在路由中带有占位符的字符串。您也可以在翻译文件中定义标签文本，并仅使用翻译键作为标签。模板将处理翻译和替换。)

注意标签中的双 % 用于转义参数。这是因为 routing.yml 被解析为 Symfony 容器的一部分，并且识别如 %name% 这样的容器参数，并尝试注入它们。双 % 转义它，模板处理剩余部分。

然后您可以直接在 Breadcrumb 对象上设置参数，例如

<?php
// MyController

// ...

public function productDetailAction()
{
    $product = ...;

    // ...

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

请注意，必须定义在路由上才能设置面包屑的参数。

动态面包屑

如果您有一个动态路由树，例如可以无限深入的分类页面树，您可以动态添加未在路由上定义的面包屑。例如像这样

<?php

use Thormeier\BreadcrumbBundle\Model\Breadcrumb;

// ...

// Route of the product, we want the categories before this
$productCrumb = $breadcrumbProvder->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()
}

请注意，这些面包屑不会存储在缓存中。

在 twig 中显示

按以下方式调用 twig 扩展

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

{{ breadcrumbs() }}

{# ... #}

使用 bootstrap 模板

此扩展包还提供了一个默认实现，用于 Bootstrap。可以按以下方式使用

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

替换默认模板

如果您想使用自定义模板，请将以下内容添加到您的 config.yml 中

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

您的自定义面包屑模板接收一个名为 breadcrumbs 的变量，它是一个表示面包屑的集合，按从树中最高到最低的顺序排列。

单个 breadcrumb 有 route、routeParameters、label 和 labelParameters 字段。 route 和 routeParameters 用于在 twig 中生成路径，即 path(breadcrumb.route, breadcrumb.routeParameters)，而 label 和 labelParameters 用于生成面包屑文本，即 {{ (breadcrumb.label)|trans(breadcrumb.labelParameters) }}

您的自定义模板可能看起来像这样

{# myBreadcrumbs.html.twig #}

<div>
    {% for breadcrumb in breadcrumbs %}
        <a href="{{ path(breadcrumb.route, breadcrumb.routeParameters) }}">
            {{ breadcrumb.label|replace({"%%": "%"})|trans(breadcrumb.labelParameters) }}
        </a>
    {% endfor %}
</div>

在模板内部将 %% 替换为单个 %。请参阅 "动态路由" 了解为什么需要这样做。

请查看 Resources/views/breadcrumbs.html.twig 和 Resources/views/breadcrumbs_bootstrap.html.twig 以了解默认实现。

自定义实现

模型类及其集合可以被自己的实现所替代，这些实现需要实现 Thormeier\BreadcrumbBundle\Model\BreadcrumbInterface 和 Thormeier\BreadcrumbBundle\Model\BreadcrumbCollectionInterface。

# config.yml
thormeier_breadcrumb:
    model_class: Acme\Breadcrumbs\Model\MyModel
    collection_class: Acme\Breadcrumbs\Model\MyCollection

可以通过设置参数 provider_service_id 来替换提供者服务ID。

# config.yml
thormeier_breadcrumb:
    provider_service_id: acme.breadcrumbs.my_provider

缓存

此插件使用路由缓存来在 cache:warmup 上存储每个路由的面包屑列表。它们随后会在需要时转换为 BreadcrumbCollection。

幻灯片

有关此插件及其一些概念的详细解释，您可以在slideshare上找到演示文稿：http://www.slideshare.net/Thormeier/thormeierbreadcrumbbundle

thormeier / breadcrumb-bundle

维护者

详细信息