README

ZianoType

ZianoType 是一个受 react JSX 语法启发的 PHP 模板引擎。

为什么选择 ZianoType？

• 语言
  • 是有效的 HTML。任何 HTML 编辑器都可以。
  • 受 react JSX 语法启发，比 twig 或其他模板语言更易于阅读。
  • 转换为原生 PHP 代码，并缓存到磁盘上。
• 支持多个查找文件夹（例如，如果文件未在 themes/cool 中找到，它还会检查 themes/default）。
• 易于包含其他模板，并传递参数以及 innerHTML。
• 使用 PHP 变量和函数编写条件和循环。
• 使用 PHP 变量输出变量，无需编写 <?php 或 <?= 标签。
• 如果包含的模板无法渲染，它将渲染错误消息并继续渲染其余内容，以防止整个页面中断。
• ZianoType 在 zlib/png 许可下发布。

注意：此库目前处于早期阶段，因此可能存在错误。如果您遇到任何错误，请随时提交问题或拉取请求。

示例

这应该能给您一个 ZianoType 模板的外观

<h1 title="$title">$title</h1>
<z if="empty($articles)">
    No articles available
</z>
<z else-if="count($articles) === 1">
    <z include="components/article.html" only="true" />
</z>
<z else>
    <z for-each="$articles as $article">
        <z include="components/article.html" article="$article" only="false" />
    </z>
</z>

<z> 标签是一个特殊的（保留）标签，它根据提供的属性控制各种功能。

设置

通过 composer 安装

composer require lusito/ziano-type:dev-master

在您的 php 脚本中包含自动加载器，除非您已经这样做

require __DIR__ . '/vendor/autoload.php';

为了更好地捕获错误，您应该添加一个错误处理器，它像这样抛出 ErrorException

set_error_handler(function ($errno, $errstr, $errfile, $errline ,array $errcontex) {
    throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
});

您需要使用的唯一类是 Lusito\ZianoType\Renderer

use Lusito\ZianoType\Renderer;

$renderer = new Renderer([
    'themes' => [
        // This array will be checked in-order to find template files
        ['extended', 'themes/extended/templates'],
        ['default', 'themes/default/templates']
    ],
    // This is the path of the cache directory
    'cachePath' => __DIR__ . '/cache',
    // Script and stylesheet filepaths can be added here:
    'scripts' => [...],
    'stylesheets' => [...]
]);
// define some properties:
$props = [
    'basepath' => '/ZianoType/example/',
    'siteTitle' => 'ZianoType',
    'pageTitle' => 'example',
    //...
];
$innerHTML = '';
$renderer->render("layout/index.html", $props, $innerHTML);

如果要将渲染值作为返回值而不是打印到 stdout，请将第四个参数设置为 true 调用 render

请参阅示例文件夹以获取更详细的设置和模板。

使用代码

打印变量

如上所示，您可以直接在 HTML 和属性中使用原生 PHP 变量。就像您写了 echo "hello $variable!";

您还可以使用花括号： {$complex['syntax']}。

如果您需要编写更复杂的代码，请使用双花括号： {{trim(' hello' . $title)}}。

您这样写的任何内容都将以转义形式打印，即 < 将成为 <。

如果您需要以纯文本形式写入文本，请使用 <z raw="$value" />。但请注意，模板文件必须是有效的 HTML。例如，您可能必须编写如下代码

<z raw="&lt;i title=&quot;woot&quot;&gt;text&lt;/i&gt;" />
<!-- Result: -->
<i title="woot">text</i>

但如果您在模板中发现自己这样做，那么重新思考您的方法并将该纯文本作为变量传递可能是个好主意。

<z> 标签

根据您添加到 <z> 标签的属性，它执行不同的操作。从标签开始到标签结束之间的所有内容都将用作相应目的的 innerHTML

• if="$condition"，else-if="$condition"，else。
  • 这些控制结构允许您创建条件。如果条件成立，则将包含内HTML。期望作为条件的正常 PHP 代码。
• for-each="$items as $item" 或 for-each="$items as $key=>$value"。
  • 正如您所期望的，它遍历所有项目，并为每个项目包含内HTML。
• include="path/to/file.html".
  • 这允许您包含另一个模板。所有额外的 <z> 标签属性都将作为 PHP 变量传递给包含的模板。此外，innerHTML 也将作为模板传递，但必须手动使用 <z render="innerHTML"> 包含。
• render="innerHTML" 渲染从外部传递给此模板的 innerHTML。
• render="scripts" 渲染此渲染操作配置的所有脚本标签。
• render="stylesheets" 渲染此渲染操作的所有链接（样式表）标签。
• raw="$value" 不进行转义渲染原始属性的值（参见上面的部分）。
• use="Vendor\Namespace\Class".
  • 这将在缓存的生成的 PHP 代码顶部写入 PHP use-语句，以便您可以轻松地使用其他类。

z-extract="$value" 属性

例如，您可能想在代码中设置一个标签的多个属性，而不想编写复杂的代码。

PHP 代码中的某个位置

$code = [
    'title' => 'My Title',
    'alt' => 'Alternative Text',
    'src' => 'foo/bar.png'
];

模板中的某个位置

<img z-extract="$code" />

这将确保，在包含的代码中的每个键值对都将作为 $key="$value" 打印在标签中。目前尚不支持 <z include="">，但它已在待办事项列表中。

更多详细示例

将 innerHTML 和 props 传递给另一个模板

假设您有一个名为 'elements/article.html' 的模板

<h1>$title</h1>
<p><z render="innerHTML" /></p>

然后您可以这样包含它

<z include="elements/article.html" title="Foo just got barred>
    Foo got a <a href="#link">speeding ticket</a> and is now behind bars.
</z>

在上面的示例中，您可以看到 <z> 标签的另一项使用：渲染 innerHTML。

报告问题

某些内容没有按预期工作？您需要尚未实现的功能？请检查 问题跟踪器，如果您的問題尚未列出，请添加一个新问题。请尽量提供详细的问题描述，包括重现步骤。

贡献

太棒了！如果您想通过新功能或提交错误修复来贡献，请 Fork 此存储库并提交一个拉取请求。请确保在提交前所有单元测试都通过，并在引入新功能时添加新测试。

许可证

ziano-type 已在 zlib/libpng 许可下发布，这意味着您可以免费使用它，在商业和非商业项目中没有附带条件。感谢您的贡献，但不是强制性的。