README

Laravel Blade 模板引擎的扩展。

安装

要求

• PHP 版本 >= 5.4

如何安装

通过 Composer 安装

composer require impactwave/razorblade

注册服务提供者

打开包含在 Laravel 中的 config/app.php 文件，你将看到一个 providers 数组。

将以下字符串添加到该数组中

'Impactwave\Razorblade\RazorbladeServiceProvider'

Blade 扩展

除了提供一些新的 Blade 指令（见下文），Razorblade 还向 Blade 添加了 自定义指令。

什么是自定义指令？

创建一个 Blade 语法扩展并不太难，但也不是很容易。你需要处理正则表达式和低级实现细节。实际上，很少有人具备这样的技能和耐心去做，因此扩展很少被使用。

如果你能够轻松地为 Blade 创建自己的语法扩展，并使模板更易于阅读和编写，会怎么样呢？

Razorblade 通过一个简单易用的方式为你提供了实现这一点的工具，称为 自定义指令。

你只需在所选的类上创建一个简单的静态方法，并指定特定的调用签名，然后就可以立即从 Blade 中调用它。
实现方法本身以执行一些有用的操作也是非常简单的。

Razorblade 在 Impactwave\Razorblade\Directives 类上为你提供了一些预定义的自定义指令。有关它们的详细信息，请参阅下面的文档。

简单的自定义指令

最简单的自定义指令允许你调用一个方法，并用其输出替换自定义指令的调用。
该方法可以（可选地）从模板接收一个或多个参数。

语法

@@[class::]method [(args)]

注意： [] 方括号不是语法的一部分，它们表示可选元素。

生成的伪代码

{{ class::method (args) }}

• 括号是可选的；例如：@@a::b 而不是 @@a::b()。
• class 是一个完全限定的类名；例如：my\namespace\myClass 或只是 myClass。
• 如果没有指定 class，则假定是 Impactwave\Razorblade\Directives。

自定义指令实现

实现自定义指令的方法应具有以下签名

static public function directiveName ($arg1, ...) {}

• $arg1, ... 表示一系列可选参数。它可以完全省略。
• 该方法应返回一个字符串。或者，它生成的输出可以通过 echo 或标记块（?> ...markup... <?php）发送到正常的 PHP 输出缓冲区。

编译时代码生成

如果存在 {$method}_compiler 方法，Razorblade 将在编译时调用它以生成包含在模板中的编译代码，而不是在运行时生成调用 $method 的代码。这允许你完全控制生成的代码。

编译器方法的签名必须是

static public function directiveName_compiler ($arg1, ...) {}

块自定义指令

除了（可选地）具有类似于常规函数的参数之外，自定义指令还可以处理一个完整的标记块，就像一些预定义的 Blade 构造（例如，@if (...args) ...markup... @endif 构造）所做的那样。

语法

@@[class::]method [(args)]:
  html markup
@@end[class::]method

注意： [] 方括号不是语法的一部分，它们表示可选元素。

• args 是参数列表，它是可选的。
• 括号是可选的；例如：@@a::b 而不是 @@a::b()。
• class 是一个完全限定的类名；例如：my\namespace\myClass 或只是 myClass。
• 如果没有指定 class，则假定是 Impactwave\Razorblade\Directives。

生成的伪代码

{{ class::method (indentSpace,html,...args) }}

自定义指令实现

实现自定义指令的方法应具有以下签名

static public function directiveName ($indentSpace, $html, $arg1, ...) {}

• $arg1, ... 表示一系列可选参数。它可以完全省略。
• $indentSpace 是一个由空格组成的字符串，对应于源标记块的缩进级别。
• $html 是在自定义指令的开头和结尾标签（@@tag ... @@endtag）之间定义的标记块。
• 该方法应返回一个字符串。或者，它生成的输出可以通过 echo 或标记块（?> ...markup... <?php）发送到正常的 PHP 输出缓冲区。

编译时代码生成

如果存在 {$method}_compiler 方法，Razorblade 将在编译时调用它以生成包含在模板中的编译代码，而不是在运行时生成调用 $method 的代码。这允许你完全控制生成的代码。

编译器方法的签名必须是

static public function directiveName_compiler ($indentSpace, $html, $arg1, ...) {}

布尔属性生成

生成布尔HTML属性的更简洁、更易读的语法。

如果参数为真，则输出无值的属性；否则，完全抑制属性，包括任何前导空白。

语法

attribute="@boolAttr (expression)"

输出

示例： <option selected> 如果为 true，或者 <option> 如果为 false。

生成的伪代码

<?php echo $expression ? '$precedentSpace$attrName' : '' ?>

• 括号是可选的；例如：@attr a::b 而不是 @attr a::b()

预定义自定义指令

@@field

生成一个兼容Bootstrap的表单字段，具有自动数据绑定和错误显示

生成的字段具有几个显著简化您标记的功能，使它更短、更易读，并节省您输入重复的模板标记和Blade指令的时间。

表单字段将

• 自动显示视图模型中的当前值。
• 自动有一个相关的标签，如果自定义指令调用中指定了标签。
  标签绑定到字段，使其具有可访问性，并且当用户点击标签时，字段变为焦点。

在提交表单时遇到验证错误的情况下，自定义指令生成一个表单字段，该字段

• 显示提交的值；
• 将字段名称的提及替换为相应的字段标签；
• 将相关字段名称的提及替换为相应的字段标签（例如，对于“确认密码”字段）；
• 如果字段值无效
  • 将字段的CSS类设置为错误类，以便将字段标记为无效；
  • 显示验证错误消息；

您还可以指定应用于生成的标记中多个元素的具体ID和CSS类。

自定义指令应包装一个任意的表单字段，您应使用纯HTML指定。

不要 在表单字段的标签上指定 name 或 value 属性。它们将由自定义指令根据其参数填充。

Blade语法

@@field (name, label, options)
  <input type="any-type-you-want" any-attr-you-want> or
  <textarea></textarea> or
  <select></select>
@@endfield

PHP调用语法

Directives::field ('', '<input type="text">', 'name', 'Your name', ['id'=>'idField'])

• name：字段名称。对于数组字段（例如：多选下拉列表），将 [] 追加到字段名称。

• label：如果省略，则不会生成标签。如果为空，则输出空标签。

• options：一个数组，可以指定

@@token

生成CSRF令牌

输出一个包含CSRF令牌的隐藏表单字段，供Laravel的CSRF中间件使用。

语法

@@token

@@includePublic

包含公共文件

与Blade的@include不同，后者包含来自view目录的模板，此指令包含位于公共Web目录内的文件。
这类似于Apache服务器端包含。它在开发用户界面原型时非常有用。该文件可以是静态HTML页面，也可以是动态PHP文件，但不能是模板。

语法

@@includePublic ('relative/path/to/file.html')

@@includeStatic

包含静态（或客户端）模板

将位于views目录内的模板直接插入到当前Blade模板中，不进行任何进一步处理（即模板将按读取的原始形式插入，不进行任何动态执行）。

语法

@@includeStatic (path)

• path：模板的文件路径，相对于views目录。

@@clientSideTemplate

嵌入客户端模板

此自定义指令对于在生成的页面上嵌入客户端模板非常有用。您可以这样操作

语法

@@clientSideTemplate (id, path, type = 'text/template')

• id：javascript模板ID。
• path：模板的文件路径，相对于views目录。
• type [可选]：生成的script标签的类型属性。默认为'text/template'。

生成的伪代码

<script id="myTemplate" type="text/template">
  ...template markup...
</script>

在这个例子中，客户端模板将放置在views/client-side目录中，紧邻其他服务器端模板。

此类模板嵌入的优势在于，页面加载时模板已预先可用，因此无需进一步进行XHR请求来加载客户端模板。

@@validationErrors

显示表单验证错误

生成一个兼容Bootstrap的警告框，显示警告标题和文本，然后显示由最后表单验证产生的所有错误消息。

语法

@@validationErrors (type = 'info')

• type：错误类型：error|info|success|warning。默认为info。

要求

您必须定义以下本地化键

@@flashMessage

显示闪存消息

显示上一次请求设置的闪存消息。

语法

@@flashMessage

闪存消息存储在Session的message键中，格式为：'type|message|title'。

• type：错误类型：error|info|success|warning。默认为warning。
• message：消息内容。
• type：可选的标题。

@@toastrMessage

显示Toastr消息

使用Toastr JavaScript插件显示弹出式闪存消息。

语法

@@toastrMessage

有关更多信息，请参阅@@flashMessage。

@@php

内联嵌入PHP代码

允许在不使用<?php ?>标签的情况下，在Blade模板中包含PHP代码块。

如果您想在Blade模板中嵌入PHP代码并使用Razorblade块自定义指令，则此功能是必需的。

警告：如果您在Blade模板中使用<?php ?>标签，则自定义指令将不会编译，因为内联PHP代码块将模板编译分割成多个片段，这会干扰编译逻辑。

语法

@@php:
  $v = "my PHP code";
  // etc...
@@endphp

Form实用工具类

Impactwave\Razorblade\Form类提供了一些静态实用方法，这些方法最好与预定义的Razorblade自定义指令一起使用。

Form::flash

允许发送在下一个请求中查看的闪存消息。它支持4种消息类型，并允许设置可选的标题。

提示：使用@@flashMessage或@@toastrMessage自定义指令来显示消息。

语法

flash ($message, $title = '', $type = Form::ALERT_INFO)

• string $message：要显示的消息。
• string $title：警告框的可选标题。
• string $type：警告类型：error|info|success|warning。您还可以使用Form::ALERT_xxx常量之一。

Form::fieldIs

检查字段的当前提交值是否与给定的值匹配。

如果字段的值是数组（字段名后缀为[]），则将参考值与所有数组值进行匹配（例如，在多个单选按钮为同一字段的情况下，或对于多选下拉列表）。

语法

Form::fieldIs ($field, $value)

• string $field：字段名。
• string $value：要匹配的字段值。

Form::fieldWas

检查字段的上一个提交值是否与给定的值匹配。

如果字段的值是数组（字段名后缀为[]），则将参考值与所有数组值进行匹配（例如，在多个单选按钮为同一字段的情况下，或对于多选下拉列表）。

语法

Form::fieldWas ($field, $value)

• string $field：字段名。
• string $value：要匹配的字段值。

Form::setModel

设置在表单首次提交之前初始显示在表单上的数据。

与@@field自定义指令和Form::validate()一起使用。

语法

Form::setModel ($model)

• array $model：表单数据，作为字段名到字段值的映射。

Form::validate

表单数据验证的快捷方法。

如果验证表单输入失败，则会

• 闪烁错误消息；
• 生成到相同URL的重定向；
• 将验证错误消息和提交的表单值保存在会话中，以便在下一个请求中重新显示。

提示：结合使用@@field自定义指令，可以轻松创建具有验证功能的表单。

用法

在处理POST请求的控制器方法中放置validate调用。

$err = Util::validate([
  'password'  => 'required|min:8',
  'password2' => 'required|same:password',
  etc...
]);
if ($err) return $err;
// continue handling the form

• array $rules：字段名到验证规则的映射。
• array $messages：[可选]自定义错误消息。请参阅Laravel文档中的Validator类。
• array $customAttributes：[可选]自定义属性。请参阅Laravel文档中的Validator类。
• 返回：false|\Illuminate\Http\RedirectResponse - 如果表单验证成功则返回false，否则返回重定向响应。

要求

您必须定义以下本地化键

许可证

MIT许可证。请参阅随附的LICENSE文件。

版权所有 © 2016 Cláudio Silva 和 Impactwave, Lda