README

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

安装

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

composer require slope-it/breadcrumb-bundle

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

{
    "require": {
        "slope-it/breadcrumb-bundle": "*"
    }
}

使用

1. 加载捆绑包

安装后，在您的Kernel类中加载捆绑包

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = [
            // ...
            new SlopeIt\BreadcrumbBundle\SlopeItBreadcrumbBundle(),
        ];
        // ...
    }
    // ...
}

2. 定义面包屑

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

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

<?php

use SlopeIt\BreadcrumbBundle\Service\BreadcrumbBuilder;

class CoolController extends Controller
{
    public function coolStuffAction(BreadcrumbBuilder $builder)
    {
        $builder->addItem('home', 'home_route');
        $builder->addItem('$entity.property', 'entity_route');
        $builder->addItem('cool_stuff');
    
        // ...
    }
}

通过属性：只需在类和/或方法级别使用#[Breadcrumb]属性。它们将被合并（类优先）。

注意：该属性可以接受单个项目（在示例中是在类级别完成）或多个项目（在示例中是在方法级别）。

<?php

use SlopeIt\BreadcrumbBundle\Attribute\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函数

{{ slope_it_breadcrumb() }}

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

Home > Value of entity property > Cool stuff

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

此外，如果您需要知道面包屑是否有项目，可以使用

{{ slope_it_is_breadcrumb_empty() }}

面包屑的生成方式

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

• 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路由的动作中，并且您想要生成包括上述所有步骤的面包屑，您将能够使用以下注解

<?php

use SlopeIt\BreadcrumbBundle\Attribute\Breadcrumb;

#[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 文件中来覆盖。

slope_it_breadcrumb:
    template: YourBundle::breadcrumb.html.twig

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

如何贡献

• 您是否在现有代码中发现了并修复了任何错误？
• 您是否想要贡献一个新功能？
• 您认为文档可以改进吗？

在上述任何情况下，请将此仓库分叉并创建一个拉取请求。我们非常乐意接受贡献！