twig implementation

author: Nicolas Lœuillet <nicolas.loeuillet@gmail.com> 2013-08-03 19:26:54 +0200
committer: Nicolas Lœuillet <nicolas.loeuillet@gmail.com> 2013-08-03 19:26:54 +0200
commit: 4f5b44bd3bd490309eb2ba7b44df4769816ba729 (patch)
tree: 6cefe170dfe0a5a361cb1e2d1fc4d580a3316d02 /vendor/twig/twig/doc/tags/extends.rst
parent: 2b840e0cfb63a453bea67a98541f3df9c273c5f5 (diff)
download: wallabag-4f5b44bd3bd490309eb2ba7b44df4769816ba729.tar.gz
wallabag-4f5b44bd3bd490309eb2ba7b44df4769816ba729.tar.zst
wallabag-4f5b44bd3bd490309eb2ba7b44df4769816ba729.zip
1 files changed, 268 insertions, 0 deletions
diff --git a/vendor/twig/twig/doc/tags/extends.rst b/vendor/twig/twig/doc/tags/extends.rst
new file mode 100644
index 00000000..f995a5dc
--- /dev/null
+++ b/vendor/twig/twig/doc/tags/extends.rst
@@ -0,0 +1,268 @@
+``extends``
+===========
+The ``extends`` tag can be used to extend a template from another one.
+.. note::
+    Like PHP, Twig does not support multiple inheritance. So you can only have
+    one extends tag called per rendering. However, Twig supports horizontal
+    :doc:`reuse<use>`.
+Let's define a base template, ``base.html``, which defines a simple HTML
+skeleton document:
+.. code-block:: html+jinja
+    <!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>
+In this example, the :doc:`block<block>` tags define four blocks that child
+templates can fill in.
+All the ``block`` tag does is to tell the template engine that a child
+template may override those portions of the template.
+Child Template
+--------------
+A child template might look like this:
+.. code-block:: jinja
+    {% extends "base.html" %}
+    {% 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 %}
+The ``extends`` tag is the key here. It tells the template engine that this
+template "extends" another template. When the template system evaluates this
+template, first it locates the parent. The extends tag should be the first tag
+in the template.
+Note that since the child template doesn't define the ``footer`` block, the
+value from the parent template is used instead.
+You can't define multiple ``block`` tags with the same name in the same
+template. This limitation exists because a block tag works in "both"
+directions. That is, a block tag doesn't just provide a hole to fill - it also
+defines the content that fills the hole in the *parent*. If there were two
+similarly-named ``block`` tags in a template, that template's parent wouldn't
+know which one of the blocks' content to use.
+If you want to print a block multiple times you can however use the
+``block`` function:
+.. code-block:: jinja
+    <title>{% block title %}{% endblock %}</title>
+    <h1>{{ block('title') }}</h1>
+    {% block body %}{% endblock %}
+Parent Blocks
+-------------
+It's possible to render the contents of the parent block by using the
+:doc:`parent<../functions/parent>` function. This gives back the results of
+the parent block:
+.. code-block:: jinja
+    {% block sidebar %}
+        <h3>Table Of Contents</h3>
+        ...
+        {{ parent() }}
+    {% endblock %}
+Named Block End-Tags
+--------------------
+Twig allows you to put the name of the block after the end tag for better
+readability:
+.. code-block:: jinja
+    {% block sidebar %}
+        {% block inner_sidebar %}
+            ...
+        {% endblock inner_sidebar %}
+    {% endblock sidebar %}
+Of course, the name after the ``endblock`` word must match the block name.
+Block Nesting and Scope
+-----------------------
+Blocks can be nested for more complex layouts. Per default, blocks have access
+to variables from outer scopes:
+.. code-block:: jinja
+    {% for item in seq %}
+        <li>{% block loop_item %}{{ item }}{% endblock %}</li>
+    {% endfor %}
+Block Shortcuts
+---------------
+For blocks with few content, it's possible to use a shortcut syntax. The
+following constructs do the same:
+.. code-block:: jinja
+    {% block title %}
+        {{ page_title|title }}
+    {% endblock %}
+.. code-block:: jinja
+    {% block title page_title|title %}
+Dynamic Inheritance
+-------------------
+Twig supports dynamic inheritance by using a variable as the base template:
+.. code-block:: jinja
+    {% extends some_var %}
+If the variable evaluates to a ``Twig_Template`` object, Twig will use it as
+the parent template::
+    // {% extends layout %}
+    $layout = $twig->loadTemplate('some_layout_template.twig');
+    $twig->display('template.twig', array('layout' => $layout));
+.. versionadded:: 1.2
+    The possibility to pass an array of templates has been added in Twig 1.2.
+You can also provide a list of templates that are checked for existence. The
+first template that exists will be used as a parent:
+.. code-block:: jinja
+    {% extends ['layout.html', 'base_layout.html'] %}
+Conditional Inheritance
+-----------------------
+As the template name for the parent can be any valid Twig expression, it's
+possible to make the inheritance mechanism conditional:
+.. code-block:: jinja
+    {% extends standalone ? "minimum.html" : "base.html" %}
+In this example, the template will extend the "minimum.html" layout template
+if the ``standalone`` variable evaluates to ``true``, and "base.html"
+otherwise.
+How blocks work?
+----------------
+A block provides a way to change how a certain part of a template is rendered
+but it does not interfere in any way with the logic around it.
+Let's take the following example to illustrate how a block work and more
+importantly, how it does not work:
+.. code-block:: jinja
+    {# base.twig #}
+    {% for post in posts %}
+        {% block post %}
+            <h1>{{ post.title }}</h1>
+            <p>{{ post.body }}</p>
+        {% endblock %}
+    {% endfor %}
+If you render this template, the result would be exactly the same with or
+without the ``block`` tag. The ``block`` inside the ``for`` loop is just a way
+to make it overridable by a child template:
+.. code-block:: jinja
+    {# child.twig #}
+    {% extends "base.twig" %}
+    {% block post %}
+        <article>
+            <header>{{ post.title }}</header>
+            <section>{{ post.text }}</section>
+        </article>
+    {% endblock %}
+Now, when rendering the child template, the loop is going to use the block
+defined in the child template instead of the one defined in the base one; the
+executed template is then equivalent to the following one:
+.. code-block:: jinja
+    {% for post in posts %}
+        <article>
+            <header>{{ post.title }}</header>
+            <section>{{ post.text }}</section>
+        </article>
+    {% endfor %}
+Let's take another example: a block included within an ``if`` statement:
+.. code-block:: jinja
+    {% if posts is empty %}
+        {% block head %}
+            {{ parent() }}
+            <meta name="robots" content="noindex, follow">
+        {% endblock head %}
+    {% endif %}
+Contrary to what you might think, this template does not define a block
+conditionally; it just makes overridable by a child template the output of
+what will be rendered when the condition is ``true``.
+If you want the output to be displayed conditionally, use the following
+instead:
+.. code-block:: jinja
+    {% block head %}
+        {{ parent() }}
+        {% if posts is empty %}
+            <meta name="robots" content="noindex, follow">
+        {% endif %}
+    {% endblock head %}
+.. seealso:: :doc:`block<../functions/block>`, :doc:`block<../tags/block>`, :doc:`parent<../functions/parent>`, :doc:`use<../tags/use>`
author	Nicolas Lœuillet <nicolas.loeuillet@gmail.com>	2013-08-03 19:26:54 +0200
committer	Nicolas Lœuillet <nicolas.loeuillet@gmail.com>	2013-08-03 19:26:54 +0200
commit	4f5b44bd3bd490309eb2ba7b44df4769816ba729 (patch)
tree	6cefe170dfe0a5a361cb1e2d1fc4d580a3316d02 /vendor/twig/twig/doc/tags/extends.rst
parent	2b840e0cfb63a453bea67a98541f3df9c273c5f5 (diff)
download	wallabag-4f5b44bd3bd490309eb2ba7b44df4769816ba729.tar.gz wallabag-4f5b44bd3bd490309eb2ba7b44df4769816ba729.tar.zst wallabag-4f5b44bd3bd490309eb2ba7b44df4769816ba729.zip

diff --git a/vendor/twig/twig/doc/tags/extends.rst b/vendor/twig/twig/doc/tags/extends.rst new file mode 100644 index 00000000..f995a5dc --- /dev/null +++ b/vendor/twig/twig/doc/tags/extends.rst
@@ -0,0 +1,268 @@
	1	``extends``
	2	===========
	3
	4	The ``extends`` tag can be used to extend a template from another one.
	5
	6	.. note::
	7
	8	Like PHP, Twig does not support multiple inheritance. So you can only have
	9	one extends tag called per rendering. However, Twig supports horizontal
	10	:doc:`reuse<use>`.
	11
	12	Let's define a base template, ``base.html``, which defines a simple HTML
	13	skeleton document:
	14
	15	.. code-block:: html+jinja
	16
	17	<!DOCTYPE html>
	18	<html>
	19	<head>
	20	{% block head %}
	21	<link rel="stylesheet" href="style.css" />
	22	<title>{% block title %}{% endblock %} - My Webpage</title>
	23	{% endblock %}
	24	</head>
	25	<body>
	26	<div id="content">{% block content %}{% endblock %}</div>
	27	<div id="footer">
	28	{% block footer %}
	29	© Copyright 2011 by <a href="http://domain.invalid/">you</a>.
	30	{% endblock %}
	31	</div>
	32	</body>
	33	</html>
	34
	35	In this example, the :doc:`block<block>` tags define four blocks that child
	36	templates can fill in.
	37
	38	All the ``block`` tag does is to tell the template engine that a child
	39	template may override those portions of the template.
	40
	41	Child Template
	42	--------------
	43
	44	A child template might look like this:
	45
	46	.. code-block:: jinja
	47
	48	{% extends "base.html" %}
	49
	50	{% block title %}Index{% endblock %}
	51	{% block head %}
	52	{{ parent() }}
	53	<style type="text/css">
	54	.important { color: #336699; }
	55	</style>
	56	{% endblock %}
	57	{% block content %}
	58	<h1>Index</h1>
	59	<p class="important">
	60	Welcome on my awesome homepage.
	61	</p>
	62	{% endblock %}
	63
	64	The ``extends`` tag is the key here. It tells the template engine that this
	65	template "extends" another template. When the template system evaluates this
	66	template, first it locates the parent. The extends tag should be the first tag
	67	in the template.
	68
	69	Note that since the child template doesn't define the ``footer`` block, the
	70	value from the parent template is used instead.
	71
	72	You can't define multiple ``block`` tags with the same name in the same
	73	template. This limitation exists because a block tag works in "both"
	74	directions. That is, a block tag doesn't just provide a hole to fill - it also
	75	defines the content that fills the hole in the parent. If there were two
	76	similarly-named ``block`` tags in a template, that template's parent wouldn't
	77	know which one of the blocks' content to use.
	78
	79	If you want to print a block multiple times you can however use the
	80	``block`` function:
	81
	82	.. code-block:: jinja
	83
	84	<title>{% block title %}{% endblock %}</title>
	85	<h1>{{ block('title') }}</h1>
	86	{% block body %}{% endblock %}
	87
	88	Parent Blocks
	89	-------------
	90
	91	It's possible to render the contents of the parent block by using the
	92	:doc:`parent<../functions/parent>` function. This gives back the results of
	93	the parent block:
	94
	95	.. code-block:: jinja
	96
	97	{% block sidebar %}
	98	<h3>Table Of Contents</h3>
	99	...
	100	{{ parent() }}
	101	{% endblock %}
	102
	103	Named Block End-Tags
	104	--------------------
	105
	106	Twig allows you to put the name of the block after the end tag for better
	107	readability:
	108
	109	.. code-block:: jinja
	110
	111	{% block sidebar %}
	112	{% block inner_sidebar %}
	113	...
	114	{% endblock inner_sidebar %}
	115	{% endblock sidebar %}
	116
	117	Of course, the name after the ``endblock`` word must match the block name.
	118
	119	Block Nesting and Scope
	120	-----------------------
	121
	122	Blocks can be nested for more complex layouts. Per default, blocks have access
	123	to variables from outer scopes:
	124
	125	.. code-block:: jinja
	126
	127	{% for item in seq %}
	128	<li>{% block loop_item %}{{ item }}{% endblock %}</li>
	129	{% endfor %}
	130
	131	Block Shortcuts
	132	---------------
	133
	134	For blocks with few content, it's possible to use a shortcut syntax. The
	135	following constructs do the same:
	136
	137	.. code-block:: jinja
	138
	139	{% block title %}
	140	{{ page_title\|title }}
	141	{% endblock %}
	142
	143	.. code-block:: jinja
	144
	145	{% block title page_title\|title %}
	146
	147	Dynamic Inheritance
	148	-------------------
	149
	150	Twig supports dynamic inheritance by using a variable as the base template:
	151
	152	.. code-block:: jinja
	153
	154	{% extends some_var %}
	155
	156	If the variable evaluates to a ``Twig_Template`` object, Twig will use it as
	157	the parent template::
	158
	159	// {% extends layout %}
	160
	161	$layout = $twig->loadTemplate('some_layout_template.twig');
	162
	163	$twig->display('template.twig', array('layout' => $layout));
	164
	165	.. versionadded:: 1.2
	166	The possibility to pass an array of templates has been added in Twig 1.2.
	167
	168	You can also provide a list of templates that are checked for existence. The
	169	first template that exists will be used as a parent:
	170
	171	.. code-block:: jinja
	172
	173	{% extends ['layout.html', 'base_layout.html'] %}
	174
	175	Conditional Inheritance
	176	-----------------------
	177
	178	As the template name for the parent can be any valid Twig expression, it's
	179	possible to make the inheritance mechanism conditional:
	180
	181	.. code-block:: jinja
	182
	183	{% extends standalone ? "minimum.html" : "base.html" %}
	184
	185	In this example, the template will extend the "minimum.html" layout template
	186	if the ``standalone`` variable evaluates to ``true``, and "base.html"
	187	otherwise.
	188
	189	How blocks work?
	190	----------------
	191
	192	A block provides a way to change how a certain part of a template is rendered
	193	but it does not interfere in any way with the logic around it.
	194
	195	Let's take the following example to illustrate how a block work and more
	196	importantly, how it does not work:
	197
	198	.. code-block:: jinja
	199
	200	{# base.twig #}
	201
	202	{% for post in posts %}
	203	{% block post %}
	204	<h1>{{ post.title }}</h1>
	205	<p>{{ post.body }}</p>
	206	{% endblock %}
	207	{% endfor %}
	208
	209	If you render this template, the result would be exactly the same with or
	210	without the ``block`` tag. The ``block`` inside the ``for`` loop is just a way
	211	to make it overridable by a child template:
	212
	213	.. code-block:: jinja
	214
	215	{# child.twig #}
	216
	217	{% extends "base.twig" %}
	218
	219	{% block post %}
	220	<article>
	221	<header>{{ post.title }}</header>
	222	<section>{{ post.text }}</section>
	223	</article>
	224	{% endblock %}
	225
	226	Now, when rendering the child template, the loop is going to use the block
	227	defined in the child template instead of the one defined in the base one; the
	228	executed template is then equivalent to the following one:
	229
	230	.. code-block:: jinja
	231
	232	{% for post in posts %}
	233	<article>
	234	<header>{{ post.title }}</header>
	235	<section>{{ post.text }}</section>
	236	</article>
	237	{% endfor %}
	238
	239	Let's take another example: a block included within an ``if`` statement:
	240
	241	.. code-block:: jinja
	242
	243	{% if posts is empty %}
	244	{% block head %}
	245	{{ parent() }}
	246
	247	<meta name="robots" content="noindex, follow">
	248	{% endblock head %}
	249	{% endif %}
	250
	251	Contrary to what you might think, this template does not define a block
	252	conditionally; it just makes overridable by a child template the output of
	253	what will be rendered when the condition is ``true``.
	254
	255	If you want the output to be displayed conditionally, use the following
	256	instead:
	257
	258	.. code-block:: jinja
	259
	260	{% block head %}
	261	{{ parent() }}
	262
	263	{% if posts is empty %}
	264	<meta name="robots" content="noindex, follow">
	265	{% endif %}
	266	{% endblock head %}
	267
	268	.. seealso:: :doc:`block<../functions/block>`, :doc:`block<../tags/block>`, :doc:`parent<../functions/parent>`, :doc:`use<../tags/use>`