README

简介

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

安装

步骤 1: Composer require

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

步骤 2: 在 kernel 中启用扩展包

<?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。

幻灯片

有关捆绑包及其概念的解释，可以在幻灯片分享网站上找到幻灯片：http://www.slideshare.net/Thormeier/thormeierbreadcrumbbundle

phillamarmotte / breadcrumb-bundle

维护者

详细信息