vendor/twig/twig/doc/tags/embed.rst

   1 ``embed``
   2 =========
   3
   4 .. versionadded:: 1.8
   5     The ``embed`` tag was added in Twig 1.8.
   6
   7 The ``embed`` tag combines the behaviour of :doc:`include<include>` and
   8 :doc:`extends<extends>`.
   9 It allows you to include another template's contents, just like ``include``
  10 does. But it also allows you to override any block defined inside the
  11 included template, like when extending a template.
  12
  13 Think of an embedded template as a "micro layout skeleton".
  14
  15 .. code-block:: jinja
  16
  17     {% embed "teasers_skeleton.twig" %}
  18         {# These blocks are defined in "teasers_skeleton.twig" #}
  19         {# and we override them right here:                    #}
  20         {% block left_teaser %}
  21             Some content for the left teaser box
  22         {% endblock %}
  23         {% block right_teaser %}
  24             Some content for the right teaser box
  25         {% endblock %}
  26     {% endembed %}
  27
  28 The ``embed`` tag takes the idea of template inheritance to the level of
  29 content fragments. While template inheritance allows for "document skeletons",
  30 which are filled with life by child templates, the ``embed`` tag allows you to
  31 create "skeletons" for smaller units of content and re-use and fill them
  32 anywhere you like.
  33
  34 Since the use case may not be obvious, let's look at a simplified example.
  35 Imagine a base template shared by multiple HTML pages, defining a single block
  36 named "content":
  37
  38 .. code-block:: text
  39
  40     ┌─── page layout ─────────────────────┐
  41     │                                     │
  42     │           ┌── block "content" ──┐   │
  43     │           │                     │   │
  44     │           │                     │   │
  45     │           │ (child template to  │   │
  46     │           │  put content here)  │   │
  47     │           │                     │   │
  48     │           │                     │   │
  49     │           └─────────────────────┘   │
  50     │                                     │
  51     └─────────────────────────────────────┘
  52
  53 Some pages ("foo" and "bar") share the same content structure -
  54 two vertically stacked boxes:
  55
  56 .. code-block:: text
  57
  58     ┌─── page layout ─────────────────────┐
  59     │                                     │
  60     │           ┌── block "content" ──┐   │
  61     │           │ ┌─ block "top" ───┐ │   │
  62     │           │ │                 │ │   │
  63     │           │ └─────────────────┘ │   │
  64     │           │ ┌─ block "bottom" ┐ │   │
  65     │           │ │                 │ │   │
  66     │           │ └─────────────────┘ │   │
  67     │           └─────────────────────┘   │
  68     │                                     │
  69     └─────────────────────────────────────┘
  70
  71 While other pages ("boom" and "baz") share a different content structure -
  72 two boxes side by side:
  73
  74 .. code-block:: text
  75
  76     ┌─── page layout ─────────────────────┐
  77     │                                     │
  78     │           ┌── block "content" ──┐   │
  79     │           │                     │   │
  80     │           │ ┌ block ┐ ┌ block ┐ │   │
  81     │           │ │"left" │ │"right"│ │   │
  82     │           │ │       │ │       │ │   │
  83     │           │ │       │ │       │ │   │
  84     │           │ └───────┘ └───────┘ │   │
  85     │           └─────────────────────┘   │
  86     │                                     │
  87     └─────────────────────────────────────┘
  88
  89 Without the ``embed`` tag, you have two ways to design your templates:
  90
  91  * Create two "intermediate" base templates that extend the master layout
  92    template: one with vertically stacked boxes to be used by the "foo" and
  93    "bar" pages and another one with side-by-side boxes for the "boom" and
  94    "baz" pages.
  95
  96  * Embed the markup for the top/bottom and left/right boxes into each page
  97    template directly.
  98
  99 These two solutions do not scale well because they each have a major drawback:
 100
 101  * The first solution may indeed work for this simplified example. But imagine
 102    we add a sidebar, which may again contain different, recurring structures
 103    of content. Now we would need to create intermediate base templates for
 104    all occurring combinations of content structure and sidebar structure...
 105    and so on.
 106
 107  * The second solution involves duplication of common code with all its negative
 108    consequences: any change involves finding and editing all affected copies
 109    of the structure, correctness has to be verified for each copy, copies may
 110    go out of sync by careless modifications etc.
 111
 112 In such a situation, the ``embed`` tag comes in handy. The common layout
 113 code can live in a single base template, and the two different content structures,
 114 let's call them "micro layouts" go into separate templates which are embedded
 115 as necessary:
 116
 117 Page template ``foo.twig``:
 118
 119 .. code-block:: jinja
 120
 121     {% extends "layout_skeleton.twig" %}
 122
 123     {% block content %}
 124         {% embed "vertical_boxes_skeleton.twig" %}
 125             {% block top %}
 126                 Some content for the top box
 127             {% endblock %}
 128
 129             {% block bottom %}
 130                 Some content for the bottom box
 131             {% endblock %}
 132         {% endembed %}
 133     {% endblock %}
 134
 135 And here is the code for ``vertical_boxes_skeleton.twig``:
 136
 137 .. code-block:: html+jinja
 138
 139     <div class="top_box">
 140         {% block top %}
 141             Top box default content
 142         {% endblock %}
 143     </div>
 144
 145     <div class="bottom_box">
 146         {% block bottom %}
 147             Bottom box default content
 148         {% endblock %}
 149     </div>
 150
 151 The goal of the ``vertical_boxes_skeleton.twig`` template being to factor
 152 out the HTML markup for the boxes.
 153
 154 The ``embed`` tag takes the exact same arguments as the ``include`` tag:
 155
 156 .. code-block:: jinja
 157
 158     {% embed "base" with {'foo': 'bar'} %}
 159         ...
 160     {% endembed %}
 161
 162     {% embed "base" with {'foo': 'bar'} only %}
 163         ...
 164     {% endembed %}
 165
 166     {% embed "base" ignore missing %}
 167         ...
 168     {% endembed %}
 169
 170 .. warning::
 171
 172     As embedded templates do not have "names", auto-escaping strategies based
 173     on the template "filename" won't work as expected if you change the
 174     context (for instance, if you embed a CSS/JavaScript template into an HTML
 175     one). In that case, explicitly set the default auto-escaping strategy with
 176     the ``autoescape`` tag.
 177
 178 .. seealso:: :doc:`include<../tags/include>`