← Back to branch summary

~ubuntu-branches/ubuntu/utopic/mako/utopic-proposed

« back to all changes in this revision

Viewing changes to doc/_sources/inheritance.txt

  • Committer: Package Import Robot
  • Author(s): Piotr Ożarowski
  • Date: 2014-06-10 20:38:26 UTC
  • mfrom: (1.4.7)
  • Revision ID: package-import@ubuntu.com-20140610203826-5gtppywd9v3gf14a
Tags: 1.0.0-1
* New upstream release
* Add python-changelog and python-sphinx-paramlinks to Build-Depends
  (needed while rebuilding documentation)
* Enable Python 3.X tests during build (add necessary packages to
  Build-Depends)
* Update links to upstream changelog (now points to changelog.rst)
* Add lintian override for source-is-missing doc/searchindex.js
  (this file is generated by sphinx-build, all sources are in the tarball)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/_sources/inheritance.txt
192
192
Where above an inheriting template can define ``<%block name="title">`` just once, and it will be
193
193
used in the base template both in the ``<title>`` section as well as the ``<h2>``.
194
194
 
 
195
 
 
196
 
195
197
But what about Defs?
196
198
====================
197
199
 
494
496
 
495
497
and you're now a template inheritance ninja!
496
498
 
 
499
Using ``<%include>`` with Template Inheritance
 
500
==============================================
 
501
 
 
502
A common source of confusion is the behavior of the ``<%include>`` tag,
 
503
often in conjunction with its interaction within template inheritance.
 
504
Key to understanding the ``<%include>`` tag is that it is a *dynamic*, e.g.
 
505
runtime, include, and not a static include.   The ``<%include>`` is only processed
 
506
as the template renders, and not at inheritance setup time.   When encountered,
 
507
the referenced template is run fully as an entirely separate template with no
 
508
linkage to any current inheritance structure.
 
509
 
 
510
If the tag were on the other hand a *static* include, this would allow source
 
511
within the included template to interact within the same inheritance context
 
512
as the calling template, but currently Mako has no static include facility.
 
513
 
 
514
In practice, this means that ``<%block>`` elements defined in an ``<%include>``
 
515
file will not interact with corresponding ``<%block>`` elements in the calling
 
516
template.
 
517
 
 
518
A common mistake is along these lines:
 
519
 
 
520
.. sourcecode:: mako
 
521
 
 
522
    ## partials.mako
 
523
    <%block name="header">
 
524
        Global Header
 
525
    </%block>
 
526
 
 
527
    ## parent.mako
 
528
    <%include file="partials.mako">
 
529
 
 
530
    ## child.mako
 
531
    <%inherit file="parent.mako">
 
532
    <%block name="header">
 
533
        Custom Header
 
534
    </%block>
 
535
 
 
536
Above, one might expect that the ``"header"`` block declared in ``child.mako``
 
537
might be invoked, as a result of it overriding the same block present in
 
538
``parent.mako`` via the include for ``partials.mako``.  But this is not the case.
 
539
Instead, ``parent.mako`` will invoke ``partials.mako``, which then invokes
 
540
``"header"`` in ``partials.mako``, and then is finished rendering.  Nothing
 
541
from ``child.mako`` will render; there is no interaction between the ``"header"``
 
542
block in ``child.mako`` and the ``"header"`` block in ``partials.mako``.
 
543
 
 
544
Instead, ``parent.mako`` must explicitly state the inheritance structure.
 
545
In order to call upon specific elements of ``partials.mako``, we will call upon
 
546
it as a namespace:
 
547
 
 
548
.. sourcecode:: mako
 
549
 
 
550
    ## partials.mako
 
551
    <%block name="header">
 
552
        Global Header
 
553
    </%block>
 
554
 
 
555
    ## parent.mako
 
556
    <%namespace name="partials" file="partials.mako"/>
 
557
    <%block name="header">
 
558
        ${partials.header()}
 
559
    </%block>
 
560
 
 
561
    ## child.mako
 
562
    <%inherit file="parent.mako">
 
563
    <%block name="header">
 
564
        Custom Header
 
565
    </%block>
 
566
 
 
567
Where above, ``parent.mako`` states the inheritance structure that ``child.mako``
 
568
is to participate within.  ``partials.mako`` only defines defs/blocks that can be
 
569
used on a per-name basis.
 
570
 
 
571
Another scenario is below, which results in both ``"SectionA"`` blocks being rendered for the ``child.mako`` document:
 
572
 
 
573
.. sourcecode:: mako
 
574
 
 
575
    ## base.mako
 
576
    ${self.body()}
 
577
    <%block name="SectionA">
 
578
        base.mako
 
579
    </%block>
 
580
 
 
581
    ## parent.mako
 
582
    <%inherit file="base.mako">
 
583
    <%include file="child.mako">
 
584
 
 
585
    ## child.mako
 
586
    <%block name="SectionA">
 
587
        child.mako
 
588
    </%block>
 
589
 
 
590
The resolution is similar; instead of using ``<%include>``, we call upon the blocks
 
591
of ``child.mako`` using a namespace:
 
592
 
 
593
.. sourcecode:: mako
 
594
 
 
595
    ## parent.mako
 
596
    <%inherit file="base.mako">
 
597
    <%namespace name="child" file="child.mako">
 
598
 
 
599
    <%block name="SectionA">
 
600
        ${child.SectionA()}
 
601
    </%block>
 
602
 
 
603
 
497
604
.. _inheritance_attr:
498
605
 
499
606
Inheritable Attributes