webiny/htpl

基于 HTML 标签的 PHP 模板引擎。

维护者

详细信息

github.com/Webiny/Htpl

主页

源代码

问题

安装: 20

依赖关系: 0

建议者: 0

安全性: 0

星星: 11

关注者: 5

分支: 4

v0.1.0 2015-06-11 12:56 UTC

Requires

  • php: >=5.5.9

Requires (Dev)

MIT 8ee9c378fc6092ea29e4fd38547e8628d3280748

  • Sven Al Hamad <sven.woop@webiny.com>
  • Pavel Denisjuk <pavel.woop@webiny.com>

template engine

This package is not auto-updated.

Last update: 2024-09-14 17:00:54 UTC

README

HTPL 是一个使用 HTML5 标签的 PHP 模板引擎。以下是一个简单的示例：

<ul>
    <w-loop items="entries" var="v" key="k">
        <w-if cond="k=='name' || k=='id'">
            <li><strong>{k}:</strong> {v}</li>
        </w-if>
    </w-loop>
</ul>

我们编写这个模板引擎是因为我们需要一个轻量级且易于扩展的引擎，特别是针对文件存储。例如，我们希望能够从云存储中检索源模板，并将编译后的模板写入 memcache 以提高执行速度。另一个原因是，我们希望提供一个对设计师来说非常容易学习和使用的东西。

主要功能

  1. 安全，所有值在输出前都会自动转义
  2. 支持布局继承
  3. 易于扩展，无需编写任何词法分析器
  4. 非常快（在某些情况下优于 Smarty、Twig 和 Blade）
  5. 简单直观的语法

基础

该引擎使用 TemplateProvider 的实例来检索源模板，并使用 Cache 实例来存储编译后的模板以提高执行速度。

$provider = new \Webiny\Htpl\TemplateProviders\FilesystemProvider([__DIR__ . '/template']);
$cache = new \Webiny\Htpl\Cache\FilesystemCache(__DIR__ . '/temp/compiled');

$htpl = new \Webiny\Htpl\Htpl($provider, $cache);

$htpl->display('template.htpl');

有几个内置的模板提供者和缓存提供者。如果您想自己构建，只需创建一个类并实现 \Webiny\Htpl\TemplateProviders\TemplateProviderInterface（模板提供者）或 \Webiny\Htpl\Cache\CacheInterface（缓存）即可。

更多信息

变量和修饰符

使用 {varName} 语法打印变量值。您还可以将不同的修饰符附加到变量上，例如

{someVar|lower|replace({"john":"doe", "bird":"fish:})}

上面的代码取 someVar 的值，将其转换为小写，并将单词 john 替换为 doe，将单词 bird 替换为 fish。

如你所见，修饰符非常容易应用，并且可以串联在一起。

修饰符

以下修饰符是内置的

数字

字符串

数组

日期/时间

其他

另请参阅 构建自定义修饰符。

Abs

绝对值

someNum = -4;

{someNum|abs} // 4

Round

四舍五入数字。

someNum = 3.555;

{someNum|round} // 4
{someNum|round(2)} // 4.00
{someNum|round(2)} // 3.56
{someNum|round(2, "down")} // 3.549

四舍五入修饰符将 precision 点作为第一个参数，将 mode 作为第二个参数。可用的 mode 值为：up 或 down，它们定义修饰符应该向上舍入还是向下舍入。

数字格式

格式化给定的数字。

num = 3500.1

{num|numberFormat(2)} // 3,500.10
{num|numberFormat(3, ",", ".")} // 3.500,100

修饰符接受三个参数：decimals、decimal point 和 thousands separator。

Capitalize

将字符串转换为大写。

str = "some string"

{str|capitalize} // Some String

Lower

将字符串转换为小写。

str = "SOME STRING"

{str|lower} // some string

Upper

将字符串转换为大写。

str = "some string"

{str|upper} // SOME STRING

First upper

首字母大写。

str = "some string"

{str|firstUpper} // Some string

Format

通过替换占位符与给定的值来格式化字符串。

var = "My name is %s"

{var|format({"John Snow"})} // My name is John Snow

修饰符接受一个字符串数组，这些字符串应按与占位符在输入字符串中出现的顺序替换。

Length

返回字符串长度或数组中的元素数量。

arr = ["one", "two", "three"]

{arr|length} // 3

str = "some string"

{str|length} // 11

Nl2br

将换行符转换为HTML的br标签。

str = "Some\nString"

{str|nl2br} // Some<br />\nString

Raw

取消变量输出的转义。

var = "<div><p>string</p></div>"

{var} // &lt;div&gt;&lt;p&gt;string&lt;/p&gt;&lt;/div&gt;
{var|raw} // <div><p>string</p></div>

Replace

在给定字符串中进行查找和替换。

var = "John loves Khaleesi"

{var|replace({"Khaleesi":"Tyrion"})} // John loves Tyrion

修改器接受一个定义要替换内容的键值对数组的参数。

Strip tags

从字符串中删除HTML标签。

var = "Some <div>HTML</div> string"

{var|stripTags} // Some HTML string
{var|stripTags("<div>")} // Some <div>HTML</div> string

修改器接受一个逗号分隔的允许标签列表，这些标签不应被替换。

Trim

从字符串的开始、结束或两边去除给定字符。

str = "|Some string|"

{str|trim("|")} // Some string
{str|trim("|", "left")} // Some string|
{str|trim("|", "right")} // |Some string

修改器接受要修剪的字符作为第一个参数，以及修剪方向作为第二个参数。

First

返回数组中的第一个值。

arr = ["one", "two", "three"]

{arr|first} // one

Last

返回数组中的最后一个值。

arr = ["one", "two", "three"]

{arr|last} // three

Join

使用给定的粘合剂将数组片段连接起来。

arr = ["one", "two", "three"]

{arr|join(",")} // one,two,three

修改器接受粘合剂作为参数。

Keys

返回数组键。

arr = ["keyOne"=>"one", "keyTwo"=>"two", "keyThree"=>"three"]

{arr|keys} // ["keyOne", "keyTwo", "keyThree"]

Values

返回数组值。

arr = ["keyOne"=>"one", "keyTwo"=>"two", "keyThree"=>"three"]

{arr|values} // ["one", "two", "three"]

Json encode

对给定的数组进行JSON编码。

arr = ["one", "two", "three"]

{arr|jsonEncode} // {"one", "two", "three"}

Date

显示日期。

date = "2015-01-01 14:25"

{date|date("F j, Y, g:i a")} // January 1, 2015, 2:25 pm

date修改器使用PHP日期函数，这意味着你可以传递任何PHP日期格式，它将解析它。

Time ago

这是一个用于以time ago格式显示日期/时间的辅助修改器。

date = "2015-01-01 14:25"

{date|timeAgo} // 4 months ago

默认值

如果变量为空，则返回默认值。

var未定义。

{var|default("some value")} // some value

自定义修改器

要添加自定义修改器，创建一个实现\Webiny\Htpl\Modifiers\ModifierPackInterface的类，并将类的实例分配给Htpl实例。

$myModifierPack = new MockModifierPack();
$htpl->registerModifierPack($myModifierPack);

值得查看内置的CorePack以了解实现方式。

函数

模板引擎仅提供少量核心函数，这些函数足以满足约95%的需求。对于剩余的5%，HTPL提供了一个简单的方法来集成任何自定义函数。

让我们看看支持哪些内容。

如果，否则，否则如果

if函数及其兄弟函数else和elseif提供了一种根据逻辑条件是否满足来执行/显示模板特定部分的方法。

<w-if cond="someVar=='someString'">
    <li>the value of someVar equals to someString</li>
<w-elseif cond="someVar>100" />
    <li>someVar is larger than 100</li>
<w-else/>
    <li>something else - in case both upper conditions are false</li>
</w-if>

包含模板

可以使用w-include标签包含外部模板。

<ul>
    <w-include file="myLists.htpl"/>
</ul>

如果file属性的值没有.htpl扩展名，它将作为变量读取，并且引擎将尝试从变量中检索模板名称并包含它。注意：只能包含.htpl文件。不能在.htpl文件中包含任何PHP代码。

<ul>
    <w-include file="someVariable"/>
</ul>

循环

循环参数接受items属性，它是你希望遍历的对象，以及var属性，它标记循环中的当前对象值。还可以传递一个可选的key属性，它包含对象的键值。

<w-loop items="entries" var="v" key="k">
    <li><strong>{k}:</strong> {v}</li>
</w-loop>

文字

w-literal标签标记的内容不应被解析。当你想在JavaScript代码中使用花括号{}时，这很有用，这样模板引擎就不会引发错误。

<w-literal>
    <script>
        var object = {"name":"john"};
    </script>
</w-literal>

压缩

这是一个有用的函数，它将所有标记的JavaScript或CSS文件压缩并连接成一个文件，并删除注释和换行符，使文件更快地下载。

一个示例模板如下

<w-minify>
    <script src="assets/js/skel.js"></script>
    <script src="assets/js/jquery.js"></script>
    <script src="assets/js/init.js"></script>
</w-minify>

<w-minify>
    <link rel="stylesheet" href="assets/css/style.css"/>
    <link rel="stylesheet" href="assets/css/navigation.css"/>
    <link rel="stylesheet" href="assets/css/modals.css"/>
</minify>

将输出如下

<script src="assets/minified/asda1kjh12k3jh1k3jh12k.js"></script>
<link rel="stylesheet" href="assets/minified/klh123iuoi13k1j23lk.css"/>

脚本会自动跟踪文件何时更改，并创建一个新的压缩文件，具有不同的名称，因此它将在用户的浏览器中自动刷新。注意：不要在同一个w-minify块中将js和css文件放在一起。

配置压缩

在可以使用之前需要配置压缩函数。

// get your Htpl instance
$htpl = new \Webiny\Htpl\Htpl($provider, $cache);

// define the minify options
$htpl->setOptions([
    'minify' => [
        'driver'    => 'Webiny\Htpl\Functions\WMinify\WMinify',
        'provider'  => $providerInstance,
        'cache'     => $cacheInstance,
        'webRoot'   => '/minified/'
    ]
]);

参数driver是可选参数。如果没有定义，将使用内置的压缩类。如果您想使用其他压缩类，可以通过扩展\Webiny\Htpl\Functions\WMinify\WMinifyAbstract来创建自己的驱动程序。

参数provider是模板提供程序的一个实例，可以与用于Htpl实例的不同实例。此provider告诉压缩器在哪里查找源文件。

参数cache是缓存的一个实例，也可以与用于Htpl实例的不同实例。此cache告诉压缩器在哪里保存压缩后的文件。

当创建压缩文件时，缓存提供程序将将其存储在某处。为了使用网络URL指向该目录，压缩组件需要知道该位置的Web绝对路径。该路径在webRoot选项中设置。

模板继承

模板继承是通过布局和块来完成的。

例如

layout.htpl内容

<html>
<head>
    <title><w-block="title"></w-block></title>
</head>
<body>
    <w-block="content"></w-block>
</body>
</html>

template.htpl内容

<w-layout template="layout.htpl">
    <w-block="title">Hello World</w-block>
    
    <w-block="content">
        This is my content
    </w-block>
</w-layout>

输出

<html>
<head>
    <title>Hello World</title>
</head>
<body>
    This is my content
</body>
</html>

注意：在w-layout标签内，所有不在w-block标签内的内容都将被删除。

许可和贡献

贡献 > 欢迎提交PR。

许可证 > MIT

资源

要运行单元测试，您需要使用以下命令

$ cd path/to/Htpl/
$ composer install
$ phpunit