README

The Twig PatternEngine allows you to use Twig as the template language for Pattern Lab PHP. Once the PatternEngine is installed you can use Twig-based StarterKits and StyleguideKits.

安装

The Twig PatternEngine comes pre-installed with the Pattern Lab Standard Edition for Twig. Please start there for all your Twig needs.

Composer

Pattern Lab PHP uses Composer to manage project dependencies with Pattern Lab Editions. To add the Twig PatternEngine to the dependencies list for your Edition you can type the following in the command line at the base of your project

composer require pattern-lab/patternengine-twig

See Packagist for information on the latest release.

概述

This document is broken into three parts

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

使用模式和Twig

Twig提供了两个可能帮助您扩展模式的特性，宏和通过模板继承布局。Twig PatternEngine还支持模式部分语法，使得在一个模式中包含另一个模式变得非常简单。

模式包含
宏
模板继承

模式包含

模式包含利用了模式部分语法作为引用系统内模式的一种快捷方式，无需依赖绝对路径。格式

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

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

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

该模式类型是原子（来自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 }}

启用 `dump()`

要使用 dump()，请在 config/config.yml 中将 twigDebug 设置为 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

gajdamaka / patternengine-twig

维护者

详细信息

README

安装

Composer

概述

使用模式和Twig

模式包含

宏

模板继承

进一步扩展Twig

过滤器

函数

测试

标签

启用 `dump()`

修改默认日期和间隔格式

快速禁用扩展

可用加载器

字符串加载器

文件系统加载器

模式加载器

gajdamaka / patternengine-twig

维护者

详细信息

README

安装

Composer

概述

使用模式和Twig

模式包含

宏

模板继承

进一步扩展Twig

过滤器

函数

测试

标签

启用 dump()

修改默认日期和间隔格式

快速禁用扩展

可用加载器

字符串加载器

文件系统加载器

模式加载器

启用 `dump()`