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](http://www.slideshare.net/Thormeier/thormeierbreadcrumbbundle)

开发

要本地执行测试，请执行以下命令

./vendor/bin/phpunit

coverage/文件夹被git忽略，因此可以用来生成覆盖率报告，使用phpunit --coverage-html ./coverage/。

如果您想为此项目做出贡献，请随时打开问题或发起pull请求！