Skip to content

Commit 10bb11d

Browse files
dmolsendmolsen
committed
rewriting the README
1 parent d885671 commit 10bb11d

File tree

1 file changed

+306
-6
lines changed

1 file changed

+306
-6
lines changed

‎README.md

Lines changed: 306 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,314 @@ Pattern Lab PHP uses [Composer](https://getcomposer.org/) to manage project depe
88

99
composer require pattern-lab/patternengine-twig
1010

11-
## Using Twig Macros
11+
## Overview
1212

13-
The Twig PatternEngine will automatically find and load Twig macros making them available to every pattern. To use this feature add your `.macro` files to `source/_macros/`. If your macro file is called `forms.macro` and it has a macro called `input()` you'd access it in your Twig templates as `{{ forms.input() }}`. **Please note:** ensure that there is no overlap between the keys for your macros and the keys for your data attributes.
13+
This document is broken into three parts:
1414

15-
## Enabling `dump()`
15+
* [Working with Patterns and Twig](#working-with-patterns-and-twig)
16+
* [Extending Twig Further](#extending-twig-further)
17+
* [Available Loaders](#available-loaders)
1618

17-
To use `dump()` set `twigDebug` in `configs/config.yml` to `true`.
19+
## Working with Patterns and Twig
1820

19-
## Modifying the Default Date and Interval Format
21+
Twig provides access to two features that may help you extend your patterns, [macros](http://twig.sensiolabs.org/doc/templates.html#macros) and layouts via[template inheritance](http://twig.sensiolabs.org/doc/templates.html#template-inheritance). The Twig PatternEngine also supports the [pattern partial syntax](http://patternlab.io/docs/pattern-including.html) to make including one pattern within another very easy.
2022

21-
You can modify the default date and interval formats for Twig by editing the `twigDefaultDateFormat` and `twigDefaultIntervalFormat` in `configs/config.yml`. Set them to an empty string to use Twig's default formats. **Please note:** both must be set for this feature to work.
23+
* [Pattern includes](#pattern-includes)
24+
* [Macros](#macros)
25+
* [Template inheritance](#template-inheritance)
26+
27+
### Pattern includes
28+
29+
Pattern includes take advantage of the [pattern partial syntax](http://patternlab.io/docs/pattern-including.html) as a shorthand for referencing patterns from across the system without needing to rely on absolute paths. The format:
30+
31+
```
32+
{% include "[patternType]-[patternName]" }}
33+
```
34+
35+
For example, let's say we wanted to include the following pattern in a molecule:
36+
37+
```
38+
source/_patterns/00-atoms/03-images/02-landscape-16x9.twig
39+
```
40+
41+
The **pattern type** is _atoms_ (from `00-atoms`) and the **pattern name** is _landscape-16x9_ from (from `02-landscape-16x9.twig`). Pattern sub-types are never used in this format and any digits for re-ordering are dropped. The shorthand partial syntax for this pattern would be:
42+
43+
```
44+
{% include "atoms-landscape-16x9" %}
45+
```
46+
47+
### Macros
48+
49+
The requirements for using macros with Pattern Lab:
50+
51+
* Files must go in `source/_macros`
52+
* Files must have the extension `.macro.twig` (_this can be modified in the config_)
53+
* The filename will be used as the base variable name in Twig templates
54+
55+
**Please note:** ensure that there is no overlap between the keys for your macros and the keys for your data attributes. A macro with the name `forms.macro.twig` will conflict with a root key with the name `forms` in your JSON/YAML. Both are accessed via `{{ forms }}` in Twig.
56+
57+
An example of a simple macro called `forms.macro.twig` in `source/_macros`:
58+
59+
```twig
60+
{% macro input(name) %}
61+
<input type="radio" name="{{ name }}" value="Dave" /> {{ name }}
62+
{% endmacro %}
63+
```
64+
65+
Would be used like this in a pattern:
66+
67+
```twig
68+
{{ forms.input("First name") }}
69+
```
70+
71+
### Template inheritance
72+
73+
The requirements for using template inheritance with Pattern Lab:
74+
75+
* Files must go in `source/_layouts`
76+
* Files must have the extension `.twig`
77+
* The filename will be used as the reference in the `extends` tag
78+
79+
An example of a simple layout called `base.twig` in `source/_layouts`:
80+
81+
```twig
82+
<!DOCTYPE html>
83+
<html>
84+
<head>
85+
{% block head %}
86+
<link rel="stylesheet" href="style.css" />
87+
<title>{% block title %}{% endblock %} - My Webpage</title>
88+
{% endblock %}
89+
</head>
90+
<body>
91+
<div id="content">{% block content %}{% endblock %}</div>
92+
<div id="footer">
93+
{% block footer %}
94+
&copy; Copyright 2011 by <a href="http://domain.invalid/">you</a>.
95+
{% endblock %}
96+
</div>
97+
</body>
98+
</html>
99+
```
100+
101+
Would be used like this in a pattern:
102+
103+
```twig
104+
{% extends "base.twig" %}
105+
106+
{% block title %}Index{% endblock %}
107+
{% block head %}
108+
{{ parent() }}
109+
<style type="text/css">
110+
.important { color: #336699; }
111+
</style>
112+
{% endblock %}
113+
{% block content %}
114+
<h1>Index</h1>
115+
<p class="important">
116+
Welcome on my awesome homepage.
117+
</p>
118+
{% endblock %}
119+
```
120+
121+
## Extending Twig Further
122+
123+
Twig comes with a number of ways to extend the underlying template parser. You can you can add [extra tags](http://twig.sensiolabs.org/doc/advanced.html#tags), [filters](http://twig.sensiolabs.org/doc/advanced.html#filters), [tests](http://twig.sensiolabs.org/doc/advanced.html#tests), and [functions](http://twig.sensiolabs.org/doc/advanced.html#functions). The Twig PatternEngine tries to simplify these extensions by allowing you to create files in specific folders and then auto-load the extensions for you. Learn more about:
124+
125+
* [Filters](#filters)
126+
* [Functions](#functions)
127+
* [Tags](#tags)
128+
* [Tests](#tests)
129+
130+
You can also:
131+
132+
* [Enable `dump()`](#enable-dump)
133+
* [Modify the Default Date and Interval Formats](#modify-the-default-date-and-interval-formats)
134+
135+
### Filters
136+
137+
The requirements for using filters with Pattern Lab:
138+
139+
* Files must go in `source/_twig-components/filters`
140+
* Files must have the extension `.filter.twig` (_this can be modified in the config_)
141+
* The filter **must** set the variable `$filter`
142+
* Only one filter per file (_e.g. can only set `$filter` once per file_)
143+
144+
An example function called `rot13.filter.twig` in `source/_twig-components/filters`:
145+
146+
```php
147+
<?php
148+
149+
$filter = new Twig_SimpleFilter('rot13', function ($string) {
150+
return str_rot13($string);
151+
});
152+
153+
?>
154+
```
155+
156+
Would be used like this in a pattern:
157+
158+
```twig
159+
{{ bar|rot13 }}
160+
```
161+
162+
### Functions
163+
164+
The requirements for using functions with Pattern Lab:
165+
166+
* Files must go in `source/_twig-components/functions`
167+
* Files must have the extension `.function.twig` (_this can be modified in the config_)
168+
* The function **must** set the variable `$function`
169+
* Only one function per file (_e.g. can only set `$function` once per file_)
170+
171+
An example function called `boo.function.twig` in `source/_twig-components/functions`:
172+
173+
```php
174+
<?php
175+
176+
$function = new Twig_SimpleFunction('boo', function ($string) {
177+
return $string." boo! ";
178+
});
179+
180+
?>
181+
```
182+
183+
Would be used like this in a pattern:
184+
185+
```twig
186+
{{ boo("ghost says what?") }}
187+
```
188+
189+
### Tests
190+
191+
The requirements for using tests with Pattern Lab:
192+
193+
* Files must go in `source/_twig-components/tests`
194+
* Files must have the extension `.test.twig` (_this can be modified in the config_)
195+
* The test **must** set the variable `$test`
196+
* Only one test per file (_e.g. can only set `$test` once per file_)
197+
198+
An example of a simple test called `red.test.twig` in `source/_twig-components/tests`:
199+
200+
```php
201+
<?php
202+
203+
$test = new Twig_SimpleTest('red', function ($value) {
204+
205+
if (isset($value["color"]) && $value["color"] == 'red') {
206+
return true;
207+
}
208+
209+
return false;
210+
});
211+
212+
?>
213+
```
214+
215+
Would be used like this in a pattern:
216+
217+
```twig
218+
{% if shirt is red %}
219+
Why did I ever sign-up with Starfleet?
220+
{% endif %}
221+
```
222+
223+
Where the JSON for the data to set `shirt` would be:
224+
225+
```json
226+
"shirt": {
227+
"color": "red"
228+
}
229+
```
230+
231+
**Reminder:** all data in Pattern Lab is stored as an array and _not_ as an object. So `$object->attribute` won't work in tests.
232+
233+
### Tags
234+
235+
The requirements for using tags with Pattern Lab:
236+
237+
* Files must go in `source/_twig-components/tags`
238+
* Files must have the extension `.tag.twig` (_this can be modified in the config_)
239+
* The filename **must** be reflected in class names. (e.g. `Project_{filename}_Node` and `Project_{filename}_TokenParser`)
240+
* Only one tag per file
241+
242+
Tags are the most complicated extension to set-up with Pattern Lab. Three steps are needed to define a new tag in Twig:
243+
244+
* Defining a Token Parser class (_responsible for parsing the template code_)
245+
* Defining a Node class (_responsible for converting the parsed code to PHP_)
246+
* Registering the tag.
247+
248+
Pattern Lab takes care of the registering for you based on the file name.
249+
250+
An example of a simple tag called `setdupe.test.twig` in `source/_twig-components/tests` that mimics the default `set` tag. Please note all of the locations where class names incorporate the filename, `setdupe`.:
251+
252+
```php
253+
<?php
254+
255+
// these files are loaded three times and we can't re-set a class
256+
if (!class_exists("Project_setdupe_Node")) {
257+
258+
class Project_setdupe_Node extends Twig_Node {
259+
260+
public function __construct($name, Twig_Node_Expression $value, $line, $tag = null) {
261+
parent::__construct(array('value' => $value), array('name' => $name), $line, $tag);
262+
}
263+
264+
public function compile(Twig_Compiler $compiler) {
265+
$compiler
266+
->addDebugInfo($this)
267+
->write('$context[\''.$this->getAttribute('name').'\'] = ')
268+
->subcompile($this->getNode('value'))
269+
->raw(";\n");
270+
}
271+
272+
}
273+
274+
}
275+
276+
// these files are loaded three times and we can't re-set a class
277+
if (!class_exists("Project_setdupe_TokenParser")) {
278+
279+
class Project_setdupe_TokenParser extends Twig_TokenParser {
280+
281+
public function parse(Twig_Token $token) {
282+
283+
$parser = $this->parser;
284+
$stream = $parser->getStream();
285+
286+
$name = $stream->expect(Twig_Token::NAME_TYPE)->getValue();
287+
$stream->expect(Twig_Token::OPERATOR_TYPE, '=');
288+
$value = $parser->getExpressionParser()->parseExpression();
289+
$stream->expect(Twig_Token::BLOCK_END_TYPE);
290+
291+
return new Project_setdupe_Node($name, $value, $token->getLine(), $this->getTag());
292+
}
293+
294+
public function getTag() {
295+
return 'setdupe';
296+
}
297+
298+
}
299+
300+
}
301+
302+
?>
303+
```
304+
305+
Would be used like this in a pattern:
306+
307+
```
308+
{% setdupe name = "Ziggy" %}
309+
{{ name }}
310+
```
311+
312+
### Enable `dump()`
313+
314+
To use `dump()` set `twigDebug` in `config/config.yml` to `true`.
315+
316+
### Modify the Default Date and Interval Formats
317+
318+
You can modify the default date and interval formats for Twig by editing the `twigDefaultDateFormat` and `twigDefaultIntervalFormat` in `config/config.yml`. Set them to an empty string to use Twig's default formats. **Please note:** both must be set for this feature to work.
22319

23320
## Available Loaders
24321

@@ -59,3 +356,6 @@ $patternLoaderClass = $patternEngineBasePath."\Loaders\PatternLoader";
59356
$patternLoader = new $patternLoaderClass($options);
60357
$code = $patternLoader->render(array("pattern" => $patternContent, "data" => $data));
61358
print $output; // outputs the given pattern
359+
360+
361+
::""''''''

0 commit comments

Comments
 (0)