README

Handlebars 模板引擎实现，用于与 XP 网络前端一起使用。

示例

连接在您的网络应用内部发生

use web\frontend\{Frontend, AssetsFrom, HandlersIn, Handlebars};
use web\Application;

class App extends Application {

  /** Returns routing for this web application */
  public function routes() {
    return [
      '/static' => new AssetsFrom($this->environment->path('src/main/webapp')),
      '/'       => new Frontend(
        new HandlersIn('com.example.app.web'),
        new Handlebars($this->environment->path('src/main/handlebars'))
      )
    ];
  }
}

模板

模板位于 src/main/handlebars，它们的名称对应于处理程序名称的小写版本（Home::class => home.handlebars）。

模板支持 YAML 前置内容，可用于设置模板全局变量的默认值。示例

---
nav:
  /: Home
  /about: About
  /login: Login
---
<!DOCTYPE html>
<html lang="en">
  <head>...</head>
  <body>
    <nav>
      {{#each nav}}
        <a href="{{@key}}">{{.}}</a>
      {{/each}}
    </nav>
  </body>
</html>

片段

我们可以在不渲染整个模板的情况下渲染特殊的内联部分，我们称之为片段。它们如下声明

<!DOCTYPE html>
<html lang="en">
  <head>...</head>
  <body>
    {{#*fragment "listing"}}
      <ul>
        {{#each items}}
          <li>{{.}}</li>
        {{/each}}
      </ul>
    {{/fragment}}
  </body>
</html>

...并且通过在我们的处理程序中选择它们通过 fragment() 来渲染

use web\frontend\{Handler, Get};

#[Handler]
class Index {
  private $list= ['One', 'Two', 'Three'];

  #[Get]
  public function index() {
    return View::named('index')->with(['list' => $this->list]);
  }

  #[Get('/listing')]
  public function partial() {
    return View::named('index')->fragment('listing')->with(['list' => $this->list]);
  }
}

访问 URI /listing 将仅渲染 <ul>...</ul> 而不是整个文档。这些片段可以与像 htmx 这样的框架一起使用，请参阅这个 gist 中的示例。

辅助函数

除了 Handlebars 内置功能之外，此库还包括以下基本辅助函数

encode: 执行 URL 编码
equals: 测试参数是否相等
contains: 测试字符串或数组是否包含特定值
size: 返回字符串长度或数组大小
min: 返回最小元素
max: 返回最大元素
any: 测试给定的任何参数是否为真值
none: 测试给定的任何参数是否不为真值
all: 测试给定的所有参数是否为真值

日期处理

use util\TimeZone;
use web\frontend\Handlebars;
use web\frontend\helpers\Dates;

new Handlebars($templates, [new Dates()]);

// Pass timezone or NULL to use local timezone
new Handlebars($templates, [new Dates(new TimeZone('Europe/Berlin'))]);
new Handlebars($templates, [new Dates(null)]);

// Pass default and named date format
new Handlebars($templates, [new Dates(null, [null => 'd.m.Y'])]);
new Handlebars($templates, [new Dates(null, ['us:short' => 'Y-m-d'])]);

date 辅助函数接受 util.Date 类接受作为构造函数参数的任何内容，或一个 util.Date 实例本身。要格式化日期，可以使用接受 util.Date::toString() 方法接受的任何内容使用 format 参数。以下是一些示例

{{date "2021-02-13"}}
{{date "13.02.2021 17:56:00"}}
{{date 1613209181}}
{{date 1613209181279 timestamp="ms"}}
{{date created}}
{{date created format="d.m.Y"}}
{{date created format="us:short"}}
{{date created timezone="America/New_York"}}

日志记录

log 辅助函数将回显传递给它的参数

{{log user}}
{{log "User profile:" user}}

当使用开发网络服务器时，这会显示调试页面

在生产环境中，日志将显示在服务器的标准输出上

独立使用

要独立使用模板引擎，只需实例化并调用其 render() 方法

use web\frontend\Handlebars;

$engine= new Handlebars('.');
echo $engine->render('home', []);

这将渲染 home.handlebars 文件并返回结果字符串。

xp-forge / handlebars-templates

维护者

详细信息

README

示例

模板

片段

辅助函数

日期处理

日志记录

独立使用