包简介

Handlebars templates for XP web frontends

README 文档

README

Handlebars template engine implementation to be used in conjunction with XP web frontends.

Example

Wiring happens inside your web application:

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'))
      )
    ];
  }
}

Templates

The templates live in src/main/handlebars, their names corresponding to lowercased version of the handlers' names (Home::class => home.handlebars).

Templates support YAML front matter, which can be used to set defaults for template globals. Example:

---
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>

Fragments

Instead of rendering an entire template, we can render special inline partials we call fragments. They are declared as follows:

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

...and are rendered by selecting them via fragment() in our handler:

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]);
  }
}

Accessing the URI /listing will render only the <ul>...</ul> instead of the entire document. These fragments can be used in conjunction with frameworks like htmx, see this gist for an example.

Helpers

On top of the built-in functionality in Handlebars, this library includes the following essential helpers:

encode: Performs URL-encoding
json: Performs JSON encoding, pretty-printing when given format=true.
equals: Tests arguments for equality
contains: Tests whether a string or array contains a certain value
size: Returns string length or array size
min: Returns smallest element
max: Returns largest element
any: Test whether any of the given arguments is truthy
none: Test whether none of the given arguments is truthy
all: Test whether all of the given arguments is truthy

Date handling

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'])]);

The date helper accepts anything the util.Date class accepts as constructor argument, or a util.Date instance itself. To format the date, the format argument can be used with anything the util.Date::toString() method accepts. Here are some examples:

{{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"}}

Logging

The log helper will echo the arguments passed to it:

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

When using the development webserver, this shows the debug page:

In production environments, logs will end up on the server's standard output:

Standalone

To use the template engine by itself, simply instantiate and call its render() method:

use web\frontend\Handlebars;

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

This will render the home.handlebars file and return the result as a string.

xp-forge/handlebars-templates 适用场景与选型建议

xp-forge/handlebars-templates 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 14.46k 次下载、GitHub Stars 达 1，最近一次更新时间为 2021 年 02 月 13 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「module」「xp」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 xp-forge/handlebars-templates 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 xp-forge/handlebars-templates 我们能提供哪些服务？

定制开发 / 二次开发

基于 xp-forge/handlebars-templates 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 xp-forge/handlebars-templates 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

dynamic/bootstrap-select 3

bootstrap select field module implementing http://silviomoreto.github.io/bootstrap-select/

daxslab/yii2-website-module 5

Yii2 module to manage website content. Kind of a CMS...

codeurx/modular 0

Codeurx Modular is simply a package for Laravel to help you create and manage modules.

attogram/attogram-user 1

User Module for the Attogram Framework

attogram/attogram-info 0

Info Module for the Attogram Framework

attogram/attogram-contactform 0

Contact Form Module for the Attogram Framework

xp-forge/handlebars-templates

包简介

关键字：