/usr/share/doc/php-twig/manual/tags/embed.html is in php-twig-doc 2.4.6-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>embed — php-twig-doc 2.4.6 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '2.4.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="extends" href="extends.html" />
<link rel="prev" title="do" href="do.html" />
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="extends.html" title="extends"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="do.html" title="do"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">php-twig-doc 2.4.6 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Tags</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="embed">
<h1><code class="docutils literal"><span class="pre">embed</span></code><a class="headerlink" href="#embed" title="Permalink to this headline">¶</a></h1>
<p>The <code class="docutils literal"><span class="pre">embed</span></code> tag combines the behaviour of <a class="reference internal" href="include.html"><span class="doc">include</span></a> and
<a class="reference internal" href="extends.html"><span class="doc">extends</span></a>.
It allows you to include another template’s contents, just like <code class="docutils literal"><span class="pre">include</span></code>
does. But it also allows you to override any block defined inside the
included template, like when extending a template.</p>
<p>Think of an embedded template as a “micro layout skeleton”.</p>
<div class="highlight-jinja"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">embed</span> <span class="s2">"teasers_skeleton.twig"</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> </span><span class="c">{# These blocks are defined in "teasers_skeleton.twig" #}</span><span class="x"></span>
<span class="x"> </span><span class="c">{# and we override them right here: #}</span><span class="x"></span>
<span class="x"> </span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">left_teaser</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> Some content for the left teaser box</span>
<span class="x"> </span><span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> </span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">right_teaser</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> Some content for the right teaser box</span>
<span class="x"> </span><span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="x"></span>
<span class="cp">{%</span> <span class="k">endembed</span> <span class="cp">%}</span><span class="x"></span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">embed</span></code> tag takes the idea of template inheritance to the level of
content fragments. While template inheritance allows for “document skeletons”,
which are filled with life by child templates, the <code class="docutils literal"><span class="pre">embed</span></code> tag allows you to
create “skeletons” for smaller units of content and re-use and fill them
anywhere you like.</p>
<p>Since the use case may not be obvious, let’s look at a simplified example.
Imagine a base template shared by multiple HTML pages, defining a single block
named “content”:</p>
<div class="highlight-text"><div class="highlight"><pre><span></span>┌─── page layout ─────────────────────┐
│ │
│ ┌── block "content" ──┐ │
│ │ │ │
│ │ │ │
│ │ (child template to │ │
│ │ put content here) │ │
│ │ │ │
│ │ │ │
│ └─────────────────────┘ │
│ │
└─────────────────────────────────────┘
</pre></div>
</div>
<p>Some pages (“foo” and “bar”) share the same content structure -
two vertically stacked boxes:</p>
<div class="highlight-text"><div class="highlight"><pre><span></span>┌─── page layout ─────────────────────┐
│ │
│ ┌── block "content" ──┐ │
│ │ ┌─ block "top" ───┐ │ │
│ │ │ │ │ │
│ │ └─────────────────┘ │ │
│ │ ┌─ block "bottom" ┐ │ │
│ │ │ │ │ │
│ │ └─────────────────┘ │ │
│ └─────────────────────┘ │
│ │
└─────────────────────────────────────┘
</pre></div>
</div>
<p>While other pages (“boom” and “baz”) share a different content structure -
two boxes side by side:</p>
<div class="highlight-text"><div class="highlight"><pre><span></span>┌─── page layout ─────────────────────┐
│ │
│ ┌── block "content" ──┐ │
│ │ │ │
│ │ ┌ block ┐ ┌ block ┐ │ │
│ │ │"left" │ │"right"│ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ └───────┘ └───────┘ │ │
│ └─────────────────────┘ │
│ │
└─────────────────────────────────────┘
</pre></div>
</div>
<p>Without the <code class="docutils literal"><span class="pre">embed</span></code> tag, you have two ways to design your templates:</p>
<blockquote>
<div><ul class="simple">
<li>Create two “intermediate” base templates that extend the master layout
template: one with vertically stacked boxes to be used by the “foo” and
“bar” pages and another one with side-by-side boxes for the “boom” and
“baz” pages.</li>
<li>Embed the markup for the top/bottom and left/right boxes into each page
template directly.</li>
</ul>
</div></blockquote>
<p>These two solutions do not scale well because they each have a major drawback:</p>
<blockquote>
<div><ul class="simple">
<li>The first solution may indeed work for this simplified example. But imagine
we add a sidebar, which may again contain different, recurring structures
of content. Now we would need to create intermediate base templates for
all occurring combinations of content structure and sidebar structure…
and so on.</li>
<li>The second solution involves duplication of common code with all its negative
consequences: any change involves finding and editing all affected copies
of the structure, correctness has to be verified for each copy, copies may
go out of sync by careless modifications etc.</li>
</ul>
</div></blockquote>
<p>In such a situation, the <code class="docutils literal"><span class="pre">embed</span></code> tag comes in handy. The common layout
code can live in a single base template, and the two different content structures,
let’s call them “micro layouts” go into separate templates which are embedded
as necessary:</p>
<p>Page template <code class="docutils literal"><span class="pre">foo.twig</span></code>:</p>
<div class="highlight-jinja"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">"layout_skeleton.twig"</span> <span class="cp">%}</span><span class="x"></span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> </span><span class="cp">{%</span> <span class="k">embed</span> <span class="s2">"vertical_boxes_skeleton.twig"</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> </span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">top</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> Some content for the top box</span>
<span class="x"> </span><span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> </span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">bottom</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> Some content for the bottom box</span>
<span class="x"> </span><span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> </span><span class="cp">{%</span> <span class="k">endembed</span> <span class="cp">%}</span><span class="x"></span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="x"></span>
</pre></div>
</div>
<p>And here is the code for <code class="docutils literal"><span class="pre">vertical_boxes_skeleton.twig</span></code>:</p>
<div class="highlight-html+jinja"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">"top_box"</span><span class="p">></span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">top</span> <span class="cp">%}</span>
Top box default content
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="p"></</span><span class="nt">div</span><span class="p">></span>
<span class="p"><</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">"bottom_box"</span><span class="p">></span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">bottom</span> <span class="cp">%}</span>
Bottom box default content
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="p"></</span><span class="nt">div</span><span class="p">></span>
</pre></div>
</div>
<p>The goal of the <code class="docutils literal"><span class="pre">vertical_boxes_skeleton.twig</span></code> template being to factor
out the HTML markup for the boxes.</p>
<p>The <code class="docutils literal"><span class="pre">embed</span></code> tag takes the exact same arguments as the <code class="docutils literal"><span class="pre">include</span></code> tag:</p>
<div class="highlight-jinja"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">embed</span> <span class="s2">"base"</span> <span class="k">with</span> <span class="o">{</span><span class="s1">'foo'</span><span class="o">:</span> <span class="s1">'bar'</span><span class="o">}</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> ...</span>
<span class="cp">{%</span> <span class="k">endembed</span> <span class="cp">%}</span><span class="x"></span>
<span class="cp">{%</span> <span class="k">embed</span> <span class="s2">"base"</span> <span class="k">with</span> <span class="o">{</span><span class="s1">'foo'</span><span class="o">:</span> <span class="s1">'bar'</span><span class="o">}</span> <span class="nv">only</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> ...</span>
<span class="cp">{%</span> <span class="k">endembed</span> <span class="cp">%}</span><span class="x"></span>
<span class="cp">{%</span> <span class="k">embed</span> <span class="s2">"base"</span> <span class="k">ignore missing</span> <span class="cp">%}</span><span class="x"></span>
<span class="x"> ...</span>
<span class="cp">{%</span> <span class="k">endembed</span> <span class="cp">%}</span><span class="x"></span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">As embedded templates do not have “names”, auto-escaping strategies based
on the template name won’t work as expected if you change the context (for
instance, if you embed a CSS/JavaScript template into an HTML one). In that
case, explicitly set the default auto-escaping strategy with the
<code class="docutils literal"><span class="pre">autoescape</span></code> tag.</p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="include.html"><span class="doc">include</span></a></p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="do.html"
title="previous chapter"><code class="docutils literal"><span class="pre">do</span></code></a></p>
<h4>Next topic</h4>
<p class="topless"><a href="extends.html"
title="next chapter"><code class="docutils literal"><span class="pre">extends</span></code></a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/tags/embed.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="extends.html" title="extends"
>next</a> |</li>
<li class="right" >
<a href="do.html" title="do"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">php-twig-doc 2.4.6 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >Tags</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright by the Twig Team.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.7.
</div>
</body>
</html>
|