README

安装

在您的 composer.json 中添加 composer 包 marspress/front-end-route，最低要求为 dev-main，或者运行 composer require marspress/front-end-route

使用方法

您首先需要创建一个路由集。您可以将其视为一种文章类型，该集中的路由就像该类型的文章。

路由集

new \MarsPress\FrontEndRoute\Route_Set() 接受 5 个参数，1 个必需和 4 个可选。

查询变量（必需）（字符串）
- 一个唯一的查询变量，将注册到 WP 和 WP_Query 对象的可用的查询变量中。
- 查询变量应仅包含小写字母、连字符和下划线。
- 如果您的查询变量已在 WordPress 中注册，则您的路由集将不会在 WordPress 中完全初始化，并且将在 wp-admin 屏幕上向管理员显示通知。
- 资源：https://codex.wordpress.org/WordPress_Query_Vars
别名（可选）（字符串）
- 您的路由集的别名，不带前导或尾随斜杠。例如 route/set
- 这可以被视为文章类型别名。
- 默认为 查询变量。
- 重要提示：您可以将别名设置为空字符串，这将生成集内所有路由而没有父级别名。如果别名是空字符串，则路由集的存档将被强制设置为 false。
  - 警告：使用此方法将导致路由别名覆盖 WordPress 中的任何顶级页面和文章。还建议不要在没有父级别名的多个路由集。
是否有存档（可选）（布尔值）
- 是否应该为路由集生成存档路由。
- 例如，如果为 true，则具有别名 route/set 的路由集将在 /route/set/ 处有存档路由。
- 默认为 false。
主体类（可选）（字符串）
- 将添加到渲染的 body 标签中的 CSS 类。
- 默认为 查询变量。
模板（可选）（字符串）
- 用于路由集的 PHP 模板文件。
- 这必须是服务器上文件的绝对路径。例如 /app/wp-content/themes/twentytwentyone-child/templates/route_set.php
- 通常您应使用 WordPress 方法获取基本路径并将它们附加到它们上
  - get_stylesheet_directory()，用于子主题；
  - get_template_directory()，用于父主题；
  - plugin_dir_path(__FILE__)，用于插件。
- 或者，您也可以使用 PHP 常量 __DIR__。
- 默认情况下，如果存在，将使用主题模板，否则将使用父主题 index.php。

可用方法

$routeSet->is_route();
- 如果当前路由是集的一部分，将返回路由别名；
- 否则返回 false。
$routeSet->get_query_variable();
- 将返回路由集的查询变量。

路由

new \MarsPress\FrontEndRoute\Route() 接受 3 个参数，2 个必需和 1 个可选。

别名（必需）（字符串）
- 路由集的唯一别名。
- 如果别名已在路由集中存在，则路由将不会初始化到集中，并且将在 wp-admin 屏幕上向管理员显示通知。
标题（必需）（字符串）
- 路由的标题。
- 这将渲染到 html 标题标签中。
模板（可选）（字符串）
- 为路由加载的PHP模板文件。
- 有关详细信息，请参阅路由集模板参数。

创建路由集并向其中添加路由

给定路由集

$routeSet = new \MarsPress\FrontEndRoute\Route_Set(
    'test_route',
    'route/set',
    'test-route-page',
);

$routeSet->add_routes(
    new \MarsPress\FrontEndRoute\Route( 'this-is-a-route', 'This is a route' ),
    new \MarsPress\FrontEndRoute\Route( 'this-is-another-route', 'This is another route' ),
);

以上将创建两个路由： /route/set/this-is-a-route 和 /route/set/this-is-another-route

add_routes 方法可以接受任意数量的参数，只要它们是 Route 实例。

模板加载

默认模板加载方式为WordPress的，如果失败，则回退到父主题的index.php文件。

默认WordPress主题作用域

资源：https://developer.wordpress.org/themes/template-files-section/page-template-files/

PHP文件应位于父主题或子主题的根目录中。

要使用WordPress的模板作用域，使用的前缀是 marspress-route-，后跟路由集的查询变量，然后是路由的别名。

marspress-route-test_route.php将为所有在test_route路由集中的路由加载；
marspress-route-test_route-this-is-a-route.php只为test_route路由集中的this-is-a-route路由加载；
如果服务器上不存在上述任何一个文件，则将加载父主题的index.php。

重要：如果路由集有存档，则查询变量值为archive，因此您应该使用marspress-route-test_route-archive.php作为存档模板。

路由集模板参数

路由集类构造函数可以接受一个可选的模板参数。这将为此集中的所有路由加载指定的模板。这不受上述列出的主题模板的存在与否的影响。

如果您在插件内部使用此依赖项并需要从插件目录加载模板，则非常有用。例如，您的模板参数可能如下所示：__DIR__ . '/templates/route_set.php'

如果模板文件在服务器上不存在，则不会加载，并且将在wp-admin屏幕上向管理员显示通知。

路由模板参数

路由类构造函数可以接受一个可选的模板参数。这将为此路由加载指定的模板。这将覆盖所有其他模板加载功能。

如果您想为单个路由加载特定模板，这非常有用。如果您想对路由和路由集进行更结构化和可扩展的模板加载，请参阅高级模板加载方法学部分。

如果模板文件在服务器上不存在，则不会加载，并且将在wp-admin屏幕上向管理员显示通知。

高级模板加载方法学

虽然您可以使用WordPress模板作用域（如marspress-route-test_route-this-is-a-route.php）加载特定路由的模板，但我们建议您使用路由集的作用域marspress-route-test_route.php，并在该模板内部处理路由模板的加载。

给定路由集

$routeSet = new \MarsPress\FrontEndRoute\Route_Set(
    'test_route',
    'route/set',
    'test-route-page',
);

将PHP文件添加到子主题的根目录，文件名命名为marspress-route-test_route.php

您的PHP文件应该包含以下内容

<?php
get_header();

if( $route = $routeSet->is_route() ){

    echo '<h1>This is a query var template</h1>';
    echo "<h2>The route is {$route}</h2>";

    $templatePart = get_stylesheet_directory() . "/template-parts/{$routeSet->get_query_variable()}/{$route}.php";
    if( file_exists( $templatePart ) ){

        require_once( $templatePart );

    }else{
    
        $defaultTemplatePart = get_stylesheet_directory() . "/template-parts/{$routeSet->get_query_variable()}/default.php";
        if( file_exists( $defaultTemplatePart ) ){
        
            require_once( $defaultTemplatePart );
        
        }
        
    }

}

get_footer();

使用上述代码，您可以在有组织的目录中管理路由模板。根据上述示例，您的路由模板应放入template-parts/test_route/<route-slug>.php，如果给定目录中没有路由的模板，它将尝试加载默认模板：template-parts/test_route/default.php。

如果您的路由集需要包含不同的HTML结构，并且路由需要继承路由集的结构时，此方法非常有用。

marspress / front-end-route

维护者

详细信息