README

警告：此包已被重命名并迁移到 https://github.com/slope-it/breadcrumb-bundle

此包提供了一种在您的 Symfony 应用程序中创建“动态”面包屑的方法。

安装

Composer 是唯一支持的安装方法。运行以下命令从 Packagist 安装最新版本

composer require asprega/breadcrumb-bundle

或者，如果您愿意，您可以在 composer.json 中指定任何版本

{
    "require": {
        "asprega/breadcrumb-bundle": "*"
    }
}

注意： 在此包达到 1.0.0 版本之前，我无法保证严格遵守语义化版本控制。

用法

1. 加载包

安装完成后，在您的 Kernel 类中加载此包

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new AndreaSprega\Bundle\BreadcrumbBundle\AndreaSpregaBreadcrumbBundle(),
        );
        // ...
    }
    // ...
}

2. 定义面包屑

创建面包屑有两种方式：通过代码（1）或通过注解（2）。

通过代码：您可以在控制器中检索面包屑构建器并添加面包屑项

public function coolStuffAction()
{
    // ...

    $builder = $this->get('asprega.breadcrumb.builder');
    $builder->addItem('home', 'home_route');
    $builder->addItem('$entity.property', 'entity_route');
    $builder->addItem('cool_stuff');

    // ...
}

通过注解：只需在类和/或方法级别使用 @Breadcrumb 注解。它们将被合并（类优先）。

注意： 注解可以接受单个项目（在上面的示例中是在类级别）或多个项目（在方法级别）。

<?php

use AndreaSprega\Bundle\BreadcrumbBundle\Annotation\Breadcrumb;

/**
 * @Breadcrumb({"label" = "home", "route" = "home_route", "params" = {"p" = "val"}, "translationDomain" = "domain" })
 */
class CoolController extends Controller
{
    /**
     * @Breadcrumb({
     *   { "label" = "$entity.property", "route" = "entity_route" },
     *   { "label" = "cool_stuff" }
     * })
     */
    public function coolStuffAction()
    {
        // ...
    }

3. 渲染面包屑

最后一步是在模板中需要打印面包屑的地方使用以下 Twig 函数

asprega_breadcrumb()

无论您使用什么方式创建面包屑，结果都会像这样

Home > Value of entity property > Cool stuff

其中前两项是锚点，最后一项是纯文本。

面包屑是如何生成的

在内部，这是面包屑生成中涉及到的业务逻辑，对于每个面包屑项

label 将是打印的文本。它可以是
- 一个“静态”字符串（翻译器会尝试使用它作为翻译键来翻译它）
- 一个特殊字符串，以 $ 开头。在这种情况下，面包屑标签将从传递给模板的变量中提取。可以使用属性路径，例如：$variable.property.path
route 将用于生成项锚点的 URL（如果提供）。如果没有提供，则该项不可点击。
params 将用于生成与提供的路由相关的 URL。它是一个关联数组，其中每个值可以是
- 一个 "静态" 字符串
- 一个使用格式 $variable.property.path 的 "特殊" 字符串。处理方式与 "标签" 中完全相同。这对于从视图变量动态检索 URL 参数（例如实体 ID）非常有用。
translationDomain 将用于翻译 label 属性中提供的键。如果为 null，则使用默认翻译域。如果您在 label 中放置了非可翻译字符串并且不想将其用作翻译键，请提供 false。

注意： 您不需要传递所有路由所需的路由参数，只要这些路由参数已经存在于当前请求的 URL 中即可。换句话说，如果您的面包屑层次结构 somehow 与您的 URL 结构 "匹配"。

示例：假设您有以下路由，包括参数和生成的 URL

parent_list   |                                       | /parents
parent_view   | { parent_id: 12345 }                  | /parents/12345
children_list | { parent_id: 12345 }                  | /parents/12345/children
child_view    | { parent_id: 12345, child_id: 67890 } | /parents/12345/children/67890
child_edit    | { parent_id: 12345, child_id: 67890 } | /parents/12345/children/67890/edit

如果您正在 children_edit 路由的动作中，并想生成包括所有以上步骤的面包屑，您可以使用以下注解

/**
 * @Breadcrumb({
 *   { "label" = "parents", "route" = "parent_list" },
 *   { "label" = "$parent.name", "route" = "parent_view" },
 *   { "label" = "children", "route" = "children_list" },
 *   { "label" = "$child.name", "route" = "child_view" },
 *   { "label" = "edit" }
 * })
 */
public function childrenEditAction($parentID, $childrenID)
{
    // ...
}

请注意，您不需要提供路由参数（因为当前请求已经包含所有这些参数）。如果您通过代码构建它，它将以相同的方式工作。

覆盖面包屑模板

可以通过将以下行添加到您的应用程序的 config.yml 中来覆盖用于渲染面包屑的包默认模板

asprega_breadcrumb:
    template: YourBundle::breadcrumb.html.twig

如果您打算这样做，建议您将 Resources/views/breadcrumb.html.twig 复制到您的包中并自定义它。然而，在您的模板中，您只需遍历 items 变量以渲染自定义面包屑。

如何贡献

您在现有代码中找到并修复了任何错误吗？
您想要贡献一个新的酷功能吗？
您认为文档不够好，并且您认为可以改进它吗？

在任何这些情况下，请分叉此存储库并创建一个拉取请求。我将非常高兴接受贡献！

维护者

@andreasprega

asprega / breadcrumb-bundle

维护者

详细信息