README

Twig PatternEngine 允许您将 Twig 作为 Pattern Lab PHP 的模板语言。一旦安装了 PatternEngine，您就可以使用基于 Twig 的 StarterKits 和 StyleguideKits。

安装

Twig PatternEngine 与 Pattern Lab Standard Edition for Twig 预先安装。请从那里开始满足所有您的 Twig 需求。

Composer

Pattern Lab PHP 使用 Composer 来管理项目依赖项和 Pattern Lab 版本。要将 Twig PatternEngine 添加到 Edition 的依赖项列表中，您可以在项目的根目录下在命令行中输入以下内容

composer require pattern-lab/patternengine-twig

有关最新版本的详细信息，请参阅 Packagist：patternengine-twig

概述

本文档分为三个部分

使用模式和Twig
进一步扩展Twig
插件开发者可用的加载器

使用模式和Twig

Twig 提供了两个可能有助于扩展您的模式的功能，即宏和通过模板继承布局。Twig PatternEngine 还支持模式部分语法，这使得在模式中包含另一个模式变得非常容易。

模式包含
宏
模板继承

模式包含

模式包含利用了模式部分语法作为引用系统中的模式而不需要依赖于绝对路径的快捷方式。该格式

{% include "[patternType]-[patternName]" %}

例如，假设我们想在分子中包含以下模式

source/_patterns/00-atoms/03-images/02-landscape-16x9.twig

该 模式类型 是 atoms（来自 00-atoms）和 模式名称 是 landscape-16x9（来自 02-landscape-16x9.twig）。模式子类型在此格式中从不使用，任何用于重新排序的数字都被省略。此模式的简写部分语法如下

{% include "atoms-landscape-16x9" %}

宏

使用Pattern Lab宏的要求

文件必须放在 source/_macros
文件必须具有扩展名 .macro.twig（这可以在配置中修改）
文件名将被用作 Twig 模板中的基础变量名

请注意：请确保宏的键与数据属性的键之间没有重叠。名为 forms.macro.twig 的宏将与 JSON/YAML 中的名为 forms 的根键冲突。两者都通过 {{ forms }} 在 Twig 中访问。

source/_macros 中名为 forms.macro.twig 的简单宏示例

{% macro input(name) %}
    <input type="radio" name="{{ name }}" value="Dave" /> {{ name }}
{% endmacro %}

将在模式中这样使用

{{ forms.input("First name") }}

模板继承

如何在Pattern Lab中使用模板继承

文件必须具有扩展名 .twig。
文件可以通过使用Pattern Lab的正常缩写语法进行扩展（例如，{% extends 'templates-extended-layout'%}）。
可选地将文件放入source/_layouts中，以将其从模式列表中隐藏，然后您只需使用文件名作为参考（例如，{% extends 'extended-layout'%}）。
同一目录下的文件也可以直接使用文件名（但不包括缩写语法），但必须包含扩展名。所以如果file1.twig和file2.twig在同一个目录中，您可以将此代码放入file2.twig中：{% extends 'file1.twig' %}。

在source/_layouts中的简单布局示例，名为base.twig。

<!DOCTYPE html>
<html>
    <head>
        {% block head %}
            <link rel="stylesheet" href="style.css" />
            <title>{% block title %}{% endblock %} - My Webpage</title>
        {% endblock %}
    </head>
    <body>
        <div id="content">{% block content %}{% endblock %}</div>
        <div id="footer">
            {% block footer %}
                &copy; Copyright 2011 by <a href="http://domain.invalid/">you</a>.
            {% endblock %}
        </div>
    </body>
</html>

将在模式中这样使用

{% extends "base.twig" %}

{% block title %}Index{% endblock %}
{% block head %}
    {{ parent() }}
    <style type="text/css">
        .important { color: #336699; }
    </style>
{% endblock %}
{% block content %}
    <h1>Index</h1>
    <p class="important">
        Welcome on my awesome homepage.
    </p>
{% endblock %}

上面所有关于extends的使用也适用于includes、embed以及可能许多其他的Twig标签。如果您遇到有趣或意外的使用案例，请告诉我们！

进一步扩展Twig

Twig提供了一些扩展底层模板解析器的方法。您可以添加额外标签、过滤器、测试和函数。Twig PatternEngine试图通过允许您在特定文件夹中创建文件，并为您自动加载扩展来简化这些扩展。了解更多关于

过滤器
函数
标签
测试

您还可以

启用dump()
修改默认日期和间隔格式
快速禁用扩展

过滤器

使用Pattern Lab的过滤器要求

文件必须放在source/_twig-components/filters
文件必须具有扩展名.filter.php（这可以在配置中修改）
过滤器必须设置变量$filter
每个文件只能有一个过滤器（例如，每个文件只能设置一次$filter）

在source/_twig-components/filters中的示例函数名为rot13.filter.php

<?php

$filter = new Twig_SimpleFilter('rot13', function ($string) {
	return str_rot13($string);
});

?>

在模式中使用此过滤器的方式如下

{{ bar|rot13 }}

函数

使用Pattern Lab的函数要求

文件必须放在source/_twig-components/functions
文件必须具有扩展名.function.php（这可以在配置中修改）
函数必须设置变量$function
每个文件只能有一个函数（例如，每个文件只能设置一次$function）

在source/_twig-components/functions中的示例函数名为boo.function.php

<?php

$function = new Twig_SimpleFunction('boo', function ($string) {
	return $string." boo! ";
});

?>

在模式中使用此函数的方式如下

{{ boo("ghost says what?") }}

测试

使用Pattern Lab的测试要求

文件必须放在source/_twig-components/tests
文件必须具有扩展名.test.php（这可以在配置中修改）
测试必须设置变量$test
每个文件只能有一个测试（例如，每个文件只能设置一次$test）

在source/_twig-components/tests中的简单测试示例，名为red.test.php

<?php

$test = new Twig_SimpleTest('red', function ($value) {
	
	if (isset($value["color"]) && $value["color"] == 'red') {
		return true;
	}
	
	return false;
});

?>

在模式中使用此测试的方式如下

{% if shirt is red %}
	Why did I ever sign-up with Starfleet?
{% endif %}

设置shirt的数据的JSON将在这里

"shirt": {
	"color": "red"
}

提醒：Pattern Lab中的所有数据都以数组的形式存储，而不是以对象的形式。因此，在测试中$object->attribute将不会工作。

<?php

// these files are loaded three times and we can't re-set a class
if (!class_exists("Project_setdupe_Node")) {
	
	class Project_setdupe_Node extends Twig_Node {
		
		public function __construct($name, Twig_Node_Expression $value, $line, $tag = null) {
			parent::__construct(array('value' => $value), array('name' => $name), $line, $tag);
		}
		
		public function compile(Twig_Compiler $compiler) {
			$compiler
				->addDebugInfo($this)
				->write('$context[\''.$this->getAttribute('name').'\'] = ')
				->subcompile($this->getNode('value'))
				->raw(";\n");
		}
		
	}
	
}

// these files are loaded three times and we can't re-set a class
if (!class_exists("Project_setdupe_TokenParser")) {
	
	class Project_setdupe_TokenParser extends Twig_TokenParser {
		
		public function parse(Twig_Token $token) {
			
			$parser = $this->parser;
			$stream = $parser->getStream();
			
			$name = $stream->expect(Twig_Token::NAME_TYPE)->getValue();
			$stream->expect(Twig_Token::OPERATOR_TYPE, '=');
			$value = $parser->getExpressionParser()->parseExpression();
			$stream->expect(Twig_Token::BLOCK_END_TYPE);
			
			return new Project_setdupe_Node($name, $value, $token->getLine(), $this->getTag());
		}
		
		public function getTag() {
			return 'setdupe';
		}
		
	}
	
}

?>

在模式中使用该标签的方式如下

{% setdupe name = "Ziggy" %}
{{ name }}

添加自定义Twig扩展

Twig扩展是一组作为一个单一包提供的Twig函数、过滤器、标签、全局变量和测试。这种方法比使用上述方法添加单个函数或过滤器更为高级，但允许更大的灵活性，因为整个Twig扩展可以在多个环境中安装。

要使用PHP类\MyProject\MyCustomTwigExtension添加Twig扩展，请在config.yml中添加以下内容

twigExtensions:
    - '\MyProject\MyCustomTwigExtension'

底层的操作基本上是这样的

$twig = new Twig_Environment($loader);

foreach ($twigExtensions as $twigExtension) {
    $twig->addExtension(new $twigExtension());
}

如果有两个Twig扩展声明了函数、过滤器等；后者会覆盖前者。在Pattern Lab的_twig-components文件夹中声明的任何内容都会覆盖使用此方法声明的自定义Twig扩展。

有关此示例的示例，请参阅ExampleTwigExtension.php在此存储库中。您可以通过将以下内容添加到config.yml来启用它

twigExtensions:
    - '\PatternLab\PatternEngine\Twig\ExampleTwigExtension'

然后将其放在任何Twig文件中

<p>Testing: {{ testPlFunction('testing...') }}</p>

在ExampleTwigExtension.php中的函数声明看起来像这样

new Twig_SimpleFunction('testPlFunction', function($arg) {
    return 'Thanks for testing out the Pattern Lab Example Twig Extension with this arg: ' . $arg;
}),

这打开了无数令人兴奋的可能性；享受乐趣吧！

启用`dump()`

要使用dump()，请将twigDebug在config/config.yml中设置为true。

修改默认日期和间隔格式

您可以通过编辑config/config.yml中的twigDefaultDateFormat和twigDefaultIntervalFormat来修改Twig的默认日期和间隔格式。将它们设置为空字符串以使用Twig的默认格式。请注意：两者都必须设置才能使用此功能。

快速禁用扩展

要禁用不再使用的扩展，只需将文件名开头的下划线添加到文件名中，然后重新生成您的网站。例如，启用的rot13过滤器

source/_twig-components/filters/rot13.filter.php

禁用的rot13过滤器

source/_twig-components/filters/_rot13.filter.php

然后使用以下命令重新生成您的Pattern Lab网站

php core/console --generate

可用的加载器

如果您正在构建一个将解析Twig文件的插件，您有权访问三个加载器。建议您使用这些加载器而不是直接访问Twig，因为这些加载器将与其他PatternEngines一起工作。

字符串加载器

字符串加载器接收一个简单的字符串并将其编译。要使用

$data         = array("hello" => "world");
$string       = "If I say hello you say {{ hello }}.";
$stringLoader = \PatternLab\Template::getStringLoader();
$output       = $stringLoader->render(array("string" => $string, "data" => $data));
print $output; // outputs "If I say hello you say world."

文件系统加载器

文件系统加载器将在配置的StyleguideKit目录中查找模板并编译它们。文件系统加载器的模板位置不能修改。要使用

$data             = array(...);
$filesystemLoader = \PatternLab\Template::getFilesystemLoader();
$output           = $filesystemLoader->render(array("template" => "viewall", "data" => $data));
print $output; // outputs the viewall view from the configured styleguidekit

模式加载器

模式加载器查找模式并允许使用Pattern Lab特定的部分语法。要使用

$data                  = array(...);
$patternContent        = file_get_contents("path/to/pattern");
$patternEngineBasePath = \PatternLab\PatternEngine::getInstance()->getBasePath();
$patternLoaderClass    = $patternEngineBasePath."\Loaders\PatternLoader";
$patternLoader         = new $patternLoaderClass($options);
$code                  = $patternLoader->render(array("pattern" => $patternContent, "data" => $data));
print $output; // outputs the given pattern

pattern-lab / patternengine-twig

维护者

详情

README

安装

Composer

概述

使用模式和Twig

模式包含

宏

模板继承

进一步扩展Twig

过滤器

函数

测试

标签

添加自定义Twig扩展

启用`dump()`

修改默认日期和间隔格式

快速禁用扩展

可用的加载器

字符串加载器

文件系统加载器

模式加载器

pattern-lab / patternengine-twig

维护者

详情

README

安装

Composer

概述

使用模式和Twig

模式包含

宏

模板继承

进一步扩展Twig

过滤器

函数

测试

标签

添加自定义Twig扩展

启用dump()

修改默认日期和间隔格式

快速禁用扩展

可用的加载器

字符串加载器

文件系统加载器

模式加载器

启用`dump()`