README

路由器

这是一个用于在条目查询中使用URL段作为过滤条件的Craft CMS插件。

内容

• 为什么
  • 演示
• 使用方法
  • 示例
  • 参数
  • 过滤器
• 安装
• 要求
• 变更日志
• 许可证

为什么

Craft使得声明动态路由（正则表达式）并将其重定向到模板进行处理的任务变得简单直接。然而，模板本身仍然是哑处理器。它们可以以命名参数的形式传递一些上下文，但它们必须承担构建渲染页面所需数据集的重任。

对于只有一个或两个变量的页面，例如博客的年存档和月存档（例如，blog/2015/01），这可能不是问题。模板将获取从craft.entries中检索的帖子列表，并根据是否设置了year和month变量来缩小范围。

但如果博客还添加了一个分类页面（例如，blog/camping）？而且如果分类页面支持它们自己的年度和月度存档页面（例如，blog/camping/2014）呢？我们可能会通过创建多个存档模板的副本来重复代码以获取帖子，或者将处理分类、年和月过滤器的逻辑添加到单个模板中，从而增加其整体复杂性。

Router插件试图通过承担基于URL参数过滤条目的工作来解决此问题。它添加了一个新的模板变量entries，可以配置为对于URLblog/2015/01包含2015年1月发布的博客文章，或者对于URLblog/camping/2014显示2014年在“Camping”分类下发布的博客文章。

演示

我们为Straight Up Craft录制了一个关于此插件的视频（36分钟）。它讨论了Router试图解决的问题，并包括了一个关于如何在Craft Blog Starter项目上使用此插件的逐步教程和演示。

使用方法

为了创建基于URL自动构建条目查询的路由规则，您需要在您的配置文件夹中创建一个router.php文件，与现有的routes.php文件相邻。

示例

<?php
/* config/router.php */

return [
    'rules' => [
        
        // URI pattern with named subpatterns
        '<section:blog>' => [
            'segments' => [
                '<year:\d{4}>',
                '<category:{slug}>',
                'in:<location:{slug}>',
            ],
            
            // array of filters that are activated when
            // the key matches a subpattern variable declared in
            // the route's regular expression
            'criteria' => [
                
                // Restrict entries to the selected section
                'section' => [
                    'type' => 'section',
                ],
                
                // Filter entries by year
                'year' => [
                    'type' => 'year',
                    'field' => 'postDate',
                ],
                
                // Filter entries by related category
                // from the category group with the handle 'travel-styles'
                'category' => [
                    'type' => 'category',
                    'group' => 'travel-styles',
                ],
                
                // Filter entries by related entry
                // from the section with the handle 'locations'
                'location' => [
                    'type' => 'entry',
                    'section' => 'locations',
                ],
            ],
            
            // template file
            'template' => 'blog/_archive',
        ],
        
    ],
];

参数

每个规则都期望以下参数

segments [数组]

默认值: []
一组可选的URL段规则。示例

'segments' => [
    '<year:\d{4}>',
    '<category:{slug}>',  // eg. budget, luxury, cruise, urban
    'in:<location:{slug}>',  // eg. asia, europe, australia
]
/*
  This will match the following URL suffixes
  …/2019
  …/2019/budget
  …/2019/budget/in:asia
  …/2019/in:asia
  …/budget
  …/budget/in:asia
  …/in:asia

  Order is relevant, so it will *not* match the following URLs
  …/budget/2019
  …/in:asia/budget
  …/2019/in:asia/budget
*/

combineSegments [布尔值]

默认值: true
启用/禁用对组合段URL的支持。当禁用时，每个URL只允许匹配一个段。示例

'combineSegments' => false
/*
  This will match only the following URL suffixes
  …/2019
  …/budget
  …/in:asia

  It will *not* match the following URLs
  …/2019/budget
  …/2019/budget/in:asia
  …/2019/in:asia
  …/budget/in:asia
*/

criteria [数组]

默认值: []
一组用于条目查询的过滤器。示例

'criteria' => [
    'year' => [ 'type' => 'year', 'field' => 'postDate' ],
    'category' => [ 'type' => 'category', 'group' => 'tripCategories' ],
    'location' => [ 'type' => 'entry', 'section' => 'locations' ],
]

template [字符串]

默认值: ''
用于渲染请求的模板路径。示例

'template' => 'blog/_archive'

当路由中存在相应的触发键（名为参数）时，将激活过滤器。根据过滤器的类型，将一组条件（标准）添加到条目查询对象中。这会对每个激活的过滤器重复进行，并将结果条目查询作为entries变量传递给模板。

过滤器类型

插件目前支持以下不同类型的过滤器

分类

为具有给定slug的分类添加relatedTo条件，以及其任何子分类。可以通过指定可选参数group中的分类组handle来限制分类的搜索范围。可以使用可选参数field指定关系的字段。如果不想将子分类包括在relatedTo条件中，可以将过滤器的includeDescendants设置为false。

分类列表

与category过滤器类似，但支持逗号分隔的slug列表，而不是单个slug。

条目

为具有给定slug的条目添加relatedTo条件，以及其任何子条目。可以通过指定可选参数section中的Section handle来限制条目的搜索范围。可以使用可选参数field指定关系的字段。如果不想将子条目包括在relatedTo条件中，可以将过滤器的includeDescendants设置为false。

条目列表

与entry过滤器类似，但支持逗号分隔的slug列表，而不是单个slug。

字段

为通过handle（必需参数）指定的字段添加字段条件。

月份

在可选参数field（默认为postDate）上添加一个数字月份条件。

搜索

添加search条件。可以使用可选参数value覆盖条件值。

分区

如果指定的分区 handle有效，则添加section条件。可以使用可选参数value覆盖分区handle值。

标签

为具有给定slug的标签添加relatedTo条件。可以通过指定可选参数group中的标签组handle来限制标签的搜索范围。可以使用可选参数field指定关系的字段。

标签列表

与tag过滤器类似，但支持逗号分隔的slug列表，而不是单个slug。

类型

如果指定的条目类型 handle有效，则添加type条件。可以使用可选参数value覆盖EntryType handle值。注意：在Craft 5中，命名的URL参数被设置为EntryType对象，在Craft 3和4中为EntryType数组。

统一资源标识符

为给定URI及其所有子项添加相关条件。可以通过在可选参数section中指定部分处理程序来限制搜索范围。可以使用可选参数field指定关系的字段。如果不希望将子项包括在relatedTo条件中，将过滤器的includeDescendants设置为false。

uris

类似于uri过滤器，但支持逗号分隔的URI列表，而不是单个URI。

year

在可选参数field（默认为postDate）上添加给定年份的日期范围条件。

安装

您可以从插件商店或使用Composer安装此插件。

从插件商店

转到项目控制面板中的插件商店，搜索“Router”，然后在模态窗口中点击“安装”按钮。

使用Composer

打开终端并运行以下命令

# go to the project directory
cd /path/to/project

# tell composer to use the plugin
composer require miranj/craft-router

# tell Craft to install the plugin
./craft plugin/install router

要求

此插件需要Craft CMS 3、4或5。Craft 2版本可在v0分支中找到。

由Miranj提供