README

一组用于Roots\Sage 9.x beta主题的扩展、提供者和Blade修订。

Blade指令：循环、查询、侧边栏、FontAwesome等指令。
菜单提供者：通过配置文件注册导航菜单和标记。
侧边栏提供者：通过配置文件注册侧边栏和小部件标记。
评论表单提供者：通过配置文件注册评论表单标记。
Schema提供者 通过@schema指令快速添加schema.org标记。
支持门面/别名 提供一个“静态”接口到绑定到Sage容器的类。
Blade修复 修复Blade @inject指令和5.5的Blade::if()方法。

要求

此包专门为Roots\Sage 9.0.0-beta.4及以上版本构建。不用说，您的开发服务器需要具有Php 7.0或更高版本。

安装

您可以通过composer安装此包

composer require webstractions/sage-xpress

Sage Xpress设置

将以下代码添加到app/setup.php文件中的after_theme_setup操作。重要的是您在Sage的BladeProvider单例之后进行此添加。

add_action('after_setup_theme', function (){

  ...

  /**
    * Add Blade to Sage container
    */
  sage()->singleton('sage.blade', function (Container $app) {
      $cachePath = config('view.compiled');
      if (!file_exists($cachePath)) {
          wp_mkdir_p($cachePath);
      }
      (new BladeProvider($app))->register();
      return new Blade($app['view']);
  });

  // Copy this part into app\setup.php after_theme_setup action.
  // Make sure it follows the Sage singleton for the Blade Provider.
  (new \SageXpress\SageXpress(sage()))->bootstrap();

});

重要由于此包引入了新的Blade指令，您应该清除您的缓存的/编译的Blade文件。这些文件位于wp-content\uploads\cache。

配置文件

目前，您需要将示例配置文件复制粘贴到您的主题config目录中。您可以在vendor\webstractions\sage-xpress\config目录中找到它们。

配置文件是SageXpress的主要组件，它驱动提供者（下面详细介绍）。

app.php 注册主题环境、提供者、 composers 和别名。
blade-directives.php 用于您的自定义Blade指令。
comments.php 评论表单配置。其他相关评论任务。
menu.php 注册导航菜单和配置。
sidebar.php 注册侧边栏和配置。

概述

除了需要在setup.php文件中添加的一行代码和配置文件之外，您无需执行其他操作。配置文件会自动与Sage容器注册，无需修改functions.php。

此外，您的setup.php文件实际上应该更精简。无需在控制器或blade文件中使用widgets_init、register_nav_menus和奇特的wp_nav_menu调用。提供者会根据您的配置自动注册，并提供Blade指令来输出它们。

门面和别名

您现在可以通过config\app.php配置文件注册别名。目前，有标准的Laravel Facades用于Blade、Config、Event、File和View。SageXpress提供者的Facades正在变动中，目前支持评论、菜单和侧边栏。

使用门面，您可以使用以下方式引用绑定的提供者，而无需混乱的实例化和方法调用。

而不是

sage('blade')->compiler()->directive('name', function ($expression) {
        // Handle the directive.
    });

您可以

Blade::directive('name', function ($expression) {
        // Handle the directive.
    });

门面有一些优点。而不是列出门面的利弊以及它们是如何工作的，请参考Laravel Facade文档。

SageXpress提供者

SageXpress提供者类似于Laravel Service Providers，但它们包含用于config()和render()的额外方法。您可以将它们视为可配置的组件，这些组件可以在Blade视图中渲染。

提供者通过 config\app.php 配置文件在 SageXpress 启动过程中自动加载。然后，这些提供者将被绑定到 Sage 容器中，您可以在主题类和控制器中使用或引用它们。

提供者处理以 WordPress 为中心的注册、过滤器等方法。可以使用 render() 方法创建自定义 Blade 指令。

Blade 指令提供者

提供了一些方便的 Blade 指令，主要针对 WordPress 使用，但也提供了其他有用的功能。

存在大量指令，需要自己的Blade 指令文档。

例如，@loop 指令可以很好地清理您的模板。

@loop

   {{-- Code inside of the loop --}}

@endloop

该指令将输出以下 PHP 代码。

if (have_posts()) :
  while(have_posts()) :
    the_post();

    // Code inside of the loop

  endwhile;
endif;

菜单提供者

在 config\menu.php 中配置您的菜单。MenuProvider 将处理与 WordPress 的注册。

<?php

return [

    'register' => [
        'primary'    => __('Primary Navigation', 'sage'),
    ],

    'default' => [],

    'primary' => [
        'theme_location'    => 'primary',
        'container_class'   => 'collapse navbar-collapse',
        'container_id'      => 'primary-menu',
        'menu_class'        => 'navbar-nav ml-auto',
        'depth'             => 2,
        'fallback_cb'       => '\App\Lib\WP_Bootstrap_Navwalker::fallback',
        'walker'            => new \App\Lib\WP_Bootstrap_Navwalker(),
    ],
];

您可以从 setup.php 文件中安全地删除任何已配置的菜单。

// Delete this function. MenuProvider has it handled.
register_nav_menus([
	'primary' => __('Primary Navigation', 'sage'),
]);

在 Blade 文件中使用 @menu 指令来渲染菜单。

@menu('primary')

或者，您可以在 app\controllers\app.php 中创建一个静态渲染函数

public static function renderMenu($name='')
{
    return sage('menu')->render($name);
}

然后在 Blade 文件中调用该函数。

@php( \App::renderMenu('primary') )

侧边栏提供者

在 config\sidebar.php 中配置您的侧边栏。SidebarProvider 将处理与 WordPress 的注册。

<?php

return [

    /**
     * Ids of sidebars you want to register.
     */
    "register" => [
        'sidebar-primary',
    ],

    /**
     * Default config options for all sidebars
     */
    "default" => [
        'after_widget'  => "</section>",
        'before_title'  => '<h3 class="widget-title">',
        'after_title'   => '</h3>'
    ],

    /**
     * Sidebar configuration.
     */
    'sidebar-primary' => [
        'name'          => __('Primary', 'sage'),
        'id'            => 'sidebar-primary',
        'before_widget' => '<section class="widget %1$s %2$s">',
    ],
];

您可以从 setup.php 文件中安全地删除任何已配置的侧边栏。

// Delete this function. The SidebarProvider has it handled.
/**
 * Register sidebars
 */
add_action('widgets_init', function () {
    $config = [
        'before_widget' => '<section class="widget %1$s %2$s">',
        'after_widget'  => '</section>',
        'before_title'  => '<h3>',
        'after_title'   => '</h3>'
    ];
    register_sidebar([
        'name'          => __('Primary', 'sage'),
        'id'            => 'sidebar-primary'
    ] + $config);

});

在 Blade 文件中使用 @sidebar 指令来渲染菜单。

@sidebar('sidebar-primary')

或者，您仍然可以使用 WordPress 函数来显示侧边栏。

@php( \dynamic_sidebar('sidebar-primary') )

评论表单提供者

在 config\comments.php 中配置您的评论表单，并使用 @commentform 指令在 Blade 模板中显示。

以下显示了一个针对 Bootstrap 4 Beta 标记的示例配置。

<?php

return [
    'comment_form' => [
        // Change the title of send button
        'label_submit' => __( 'Send', 'textdomain' ),
        // Change the title of the reply section
        'title_reply' => __( 'Write a Reply or Comment', 'textdomain' ),
        // Remove "Text or HTML to be displayed after the set of comment fields".
        'comment_notes_after' => '',
        'comment_field' => '
          <div class="form-group">
            <label for="comment">' . _x( 'Comment', 'sage' ) . '</label>
            <br />
            <textarea id="comment" name="comment" class="form-control" aria-required="true"></textarea>
          </div>',
        'fields' => [
          'author' => '
            <div class="form-group row">
              <label for="author" class="col-2 col-form-label">' . _x( 'Name', 'sage' ) . '</label>
              <div class="col-10">
                <input type="text" class="form-control" id="author" name="author" maxlength="245" required>
                <div class="invalid-feedback">
                    Please provide a valid name.
                </div>
              </div>
            </div>',
          'email' => '
            <div class="form-group row">
              <label for="email" class="col-2 col-form-label">' . _x( 'Email', 'sage' ) . '</label>
              <div class="col-10">
                <input type="email" class="form-control" id="email" name="email" maxlength="245" aria-required="true" required="required">
              </div>
              <div class="invalid-feedback">
                  Please provide a valid email.
              </div>
            </div>',
          'url' => '
            <div class="form-group row">
              <label for="url" class="col-2 col-form-label">' . _x( 'Url', 'sage' ) . '</label>
              <div class="col-10">
                <input class="form-control" type="url" value="" id="url">
              </div>
            </div>',
        ],
    ],
];

模式提供者

与 Blade 指令一样，有许多 schema.org 属性，并有自己的文档。每个属性都有两个过滤器，可以用来进一步扩展它们。有关完整详情，请参阅模式提供者文档。

使用 @schema 指令可以使标记变得简单。

{{--  Author  --}}
<span @schema( 'entry-author' )>
  @php( the_author_posts_link() )
</span>

将生成以下 PHP 代码。

<span class="entry-author" itemprop="author" itemscope="itemscope" itemtype="http://schema.org/Person">
    <?php ( the_author_posts_link() ); ?>
</span>

文档

致谢

Roots/Sage 论坛线程 Blade 资源和 Log1x 对启发 Blade 组件的贡献。
Appstract 的 Laravel Blade 指令用于配置和服务提供者逻辑。
Justin Tadlock 从旧版本的 Hybrid Core 中的 hybrid_attr() 函数。

许可

MIT 许可证 (MIT)。请参阅许可文件了解更多信息。

webstractions / sage-xpress

维护者

详情