Source

djangofrdoc / ref / templates / api.txt

Full commit
  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
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
====================================================
The Django template language: For Python programmers
====================================================

This document explains the Django template system from a technical
perspective -- how it works and how to extend it. If you're just looking for
reference on the language syntax, see :doc:`/topics/templates`.

If you're looking to use the Django template system as part of another
application -- i.e., without the rest of the framework -- make sure to read
the `configuration`_ section later in this document.

.. _configuration: `configuring the template system in standalone mode`_

Basics
======

A **template** is a text document, or a normal Python string, that is marked-up
using the Django template language. A template can contain **block tags** or
**variables**.

A **block tag** is a symbol within a template that does something.

This definition is deliberately vague. For example, a block tag can output
content, serve as a control structure (an "if" statement or "for" loop), grab
content from a database or enable access to other template tags.

Block tags are surrounded by ``"{%"`` and ``"%}"``.

Example template with block tags:

.. code-block:: html+django

    {% if is_logged_in %}Thanks for logging in!{% else %}Please log in.{% endif %}

A **variable** is a symbol within a template that outputs a value.

Variable tags are surrounded by ``"{{"`` and ``"}}"``.

Example template with variables:

.. code-block:: html+django

    My first name is {{ first_name }}. My last name is {{ last_name }}.

A **context** is a "variable name" -> "variable value" mapping that is passed
to a template.

A template **renders** a context by replacing the variable "holes" with values
from the context and executing all block tags.

Using the template system
=========================

.. class:: django.template.Template

Using the template system in Python is a two-step process:

    * First, you compile the raw template code into a ``Template`` object.
    * Then, you call the ``render()`` method of the ``Template`` object with a
      given context.

Compiling a string
------------------

The easiest way to create a ``Template`` object is by instantiating it
directly. The class lives at :class:`django.template.Template`. The constructor
takes one argument -- the raw template code::

    >>> from django.template import Template
    >>> t = Template("My name is {{ my_name }}.")
    >>> print t
    <django.template.Template instance>

.. admonition:: Behind the scenes

    The system only parses your raw template code once -- when you create the
    ``Template`` object. From then on, it's stored internally as a "node"
    structure for performance.

    Even the parsing itself is quite fast. Most of the parsing happens via a
    single call to a single, short, regular expression.

Rendering a context
-------------------

.. method:: render(context)

Once you have a compiled ``Template`` object, you can render a context -- or
multiple contexts -- with it. The ``Context`` class lives at
:class:`django.template.Context`, and the constructor takes two (optional)
arguments:

    * A dictionary mapping variable names to variable values.

    * The name of the current application. This application name is used
      to help :ref:`resolve namespaced URLs<topics-http-reversing-url-namespaces>`.
      If you're not using namespaced URLs, you can ignore this argument.

Call the ``Template`` object's ``render()`` method with the context to "fill" the
template::

    >>> from django.template import Context, Template
    >>> t = Template("My name is {{ my_name }}.")

    >>> c = Context({"my_name": "Adrian"})
    >>> t.render(c)
    "My name is Adrian."

    >>> c = Context({"my_name": "Dolores"})
    >>> t.render(c)
    "My name is Dolores."

Variable names must consist of any letter (A-Z), any digit (0-9), an underscore
or a dot.

Dots have a special meaning in template rendering. A dot in a variable name
signifies a **lookup**. Specifically, when the template system encounters a
dot in a variable name, it tries the following lookups, in this order:

    * Dictionary lookup. Example: ``foo["bar"]``
    * Attribute lookup. Example: ``foo.bar``
    * List-index lookup. Example: ``foo[bar]``

The template system uses the first lookup type that works. It's short-circuit
logic. Here are a few examples::

    >>> from django.template import Context, Template
    >>> t = Template("My name is {{ person.first_name }}.")
    >>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}
    >>> t.render(Context(d))
    "My name is Joe."

    >>> class PersonClass: pass
    >>> p = PersonClass()
    >>> p.first_name = "Ron"
    >>> p.last_name = "Nasty"
    >>> t.render(Context({"person": p}))
    "My name is Ron."

    >>> t = Template("The first stooge in the list is {{ stooges.0 }}.")
    >>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})
    >>> t.render(c)
    "The first stooge in the list is Larry."

If any part of the variable is callable, the template system will try calling
it. Example::

    >>> class PersonClass2:
    ...     def name(self):
    ...         return "Samantha"
    >>> t = Template("My name is {{ person.name }}.")
    >>> t.render(Context({"person": PersonClass2}))
    "My name is Samantha."

.. versionchanged:: 1.3
    Previously, only variables that originated with an attribute lookup would
    be called by the template system. This change was made for consistency
    across lookup types.

Callable variables are slightly more complex than variables which only require
straight lookups. Here are some things to keep in mind:

    * If the variable raises an exception when called, the exception will be
      propagated, unless the exception has an attribute
      ``silent_variable_failure`` whose value is ``True``. If the exception
      *does* have a ``silent_variable_failure`` attribute whose value is
      ``True``, the variable will render as an empty string. Example::

        >>> t = Template("My name is {{ person.first_name }}.")
        >>> class PersonClass3:
        ...     def first_name(self):
        ...         raise AssertionError("foo")
        >>> p = PersonClass3()
        >>> t.render(Context({"person": p}))
        Traceback (most recent call last):
        ...
        AssertionError: foo

        >>> class SilentAssertionError(Exception):
        ...     silent_variable_failure = True
        >>> class PersonClass4:
        ...     def first_name(self):
        ...         raise SilentAssertionError
        >>> p = PersonClass4()
        >>> t.render(Context({"person": p}))
        "My name is ."

      Note that :exc:`django.core.exceptions.ObjectDoesNotExist`, which is the
      base class for all Django database API ``DoesNotExist`` exceptions, has
      ``silent_variable_failure = True``. So if you're using Django templates
      with Django model objects, any ``DoesNotExist`` exception will fail
      silently.

    * A variable can only be called if it has no required arguments. Otherwise,
      the system will return an empty string.

    * Obviously, there can be side effects when calling some variables, and
      it'd be either foolish or a security hole to allow the template system
      to access them.

      A good example is the :meth:`~django.db.models.Model.delete` method on
      each Django model object. The template system shouldn't be allowed to do
      something like this::

        I will now delete this valuable data. {{ data.delete }}

      To prevent this, set an ``alters_data`` attribute on the callable
      variable. The template system won't call a variable if it has
      ``alters_data=True`` set, and will instead replace the variable with
      :setting:`TEMPLATE_STRING_IF_INVALID`, unconditionally.  The
      dynamically-generated :meth:`~django.db.models.Model.delete` and
      :meth:`~django.db.models.Model.save` methods on Django model objects get
      ``alters_data=True`` automatically. Example::

        def sensitive_function(self):
            self.database_record.delete()
        sensitive_function.alters_data = True

    * .. versionadded:: 1.4
         Occasionally you may want to turn off this feature for other reasons,
         and tell the template system to leave a variable un-called no matter
         what.  To do so, set a ``do_not_call_in_templates`` attribute on the
         callable with the value ``True``.  The template system then will act as
         if your variable is not callable (allowing you to access attributes of
         the callable, for example).


.. _invalid-template-variables:

How invalid variables are handled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Generally, if a variable doesn't exist, the template system inserts the
value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set to
``''`` (the empty string) by default.

Filters that are applied to an invalid variable will only be applied if
:setting:`TEMPLATE_STRING_IF_INVALID` is set to ``''`` (the empty string). If
:setting:`TEMPLATE_STRING_IF_INVALID` is set to any other value, variable
filters will be ignored.

This behavior is slightly different for the ``if``, ``for`` and ``regroup``
template tags. If an invalid variable is provided to one of these template
tags, the variable will be interpreted as ``None``. Filters are always
applied to invalid variables within these template tags.

If :setting:`TEMPLATE_STRING_IF_INVALID` contains a ``'%s'``, the format marker will
be replaced with the name of the invalid variable.

.. admonition:: For debug purposes only!

    While :setting:`TEMPLATE_STRING_IF_INVALID` can be a useful debugging tool,
    it is a bad idea to turn it on as a 'development default'.

    Many templates, including those in the Admin site, rely upon the
    silence of the template system when a non-existent variable is
    encountered. If you assign a value other than ``''`` to
    :setting:`TEMPLATE_STRING_IF_INVALID`, you will experience rendering
    problems with these templates and sites.

    Generally, :setting:`TEMPLATE_STRING_IF_INVALID` should only be enabled
    in order to debug a specific template problem, then cleared
    once debugging is complete.

Playing with Context objects
----------------------------

.. class:: django.template.Context

Most of the time, you'll instantiate ``Context`` objects by passing in a
fully-populated dictionary to ``Context()``. But you can add and delete items
from a ``Context`` object once it's been instantiated, too, using standard
dictionary syntax::

    >>> c = Context({"foo": "bar"})
    >>> c['foo']
    'bar'
    >>> del c['foo']
    >>> c['foo']
    ''
    >>> c['newvariable'] = 'hello'
    >>> c['newvariable']
    'hello'

.. method:: pop()
.. method:: push()
.. exception:: django.template.ContextPopException

A ``Context`` object is a stack. That is, you can ``push()`` and ``pop()`` it.
If you ``pop()`` too much, it'll raise
``django.template.ContextPopException``::

    >>> c = Context()
    >>> c['foo'] = 'first level'
    >>> c.push()
    >>> c['foo'] = 'second level'
    >>> c['foo']
    'second level'
    >>> c.pop()
    >>> c['foo']
    'first level'
    >>> c['foo'] = 'overwritten'
    >>> c['foo']
    'overwritten'
    >>> c.pop()
    Traceback (most recent call last):
    ...
    django.template.ContextPopException

.. method:: update(other_dict)

In addition to ``push()`` and ``pop()``, the ``Context``
object also defines an ``update()`` method. This works like ``push()``
but takes a dictionary as an argument and pushes that dictionary onto
the stack instead of an empty one.

    >>> c = Context()
    >>> c['foo'] = 'first level'
    >>> c.update({'foo': 'updated'})
    {'foo': 'updated'}
    >>> c['foo']
    'updated'
    >>> c.pop()
    {'foo': 'updated'}
    >>> c['foo']
    'first level'

Using a ``Context`` as a stack comes in handy in some custom template tags, as
you'll see below.

.. _subclassing-context-requestcontext:

Subclassing Context: RequestContext
-----------------------------------

.. class:: django.template.RequestContext

Django comes with a special ``Context`` class,
``django.template.RequestContext``, that acts slightly differently than the
normal ``django.template.Context``. The first difference is that it takes an
:class:`~django.http.HttpRequest` as its first argument. For example::

    c = RequestContext(request, {
        'foo': 'bar',
    })

The second difference is that it automatically populates the context with a few
variables, according to your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.

The :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting is a tuple of callables --
called **context processors** -- that take a request object as their argument
and return a dictionary of items to be merged into the context. By default,
:setting:`TEMPLATE_CONTEXT_PROCESSORS` is set to::

    ("django.contrib.auth.context_processors.auth",
    "django.core.context_processors.debug",
    "django.core.context_processors.i18n",
    "django.core.context_processors.media",
    "django.core.context_processors.static",
    "django.contrib.messages.context_processors.messages")

.. versionadded:: 1.2
   In addition to these, ``RequestContext`` always uses
   ``django.core.context_processors.csrf``.  This is a security
   related context processor required by the admin and other contrib apps, and,
   in case of accidental misconfiguration, it is deliberately hardcoded in and
   cannot be turned off by the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.

.. versionadded:: 1.2
   The ``'messages'`` context processor was added.  For more information, see
   the :doc:`messages documentation </ref/contrib/messages>`.

.. versionchanged:: 1.2
    The auth context processor was moved in this release from its old location
    ``django.core.context_processors.auth`` to
    ``django.contrib.auth.context_processors.auth``.

Each processor is applied in order. That means, if one processor adds a
variable to the context and a second processor adds a variable with the same
name, the second will override the first. The default processors are explained
below.

.. admonition:: When context processors are applied

    When you use ``RequestContext``, the variables you supply directly
    are added first, followed any variables supplied by context
    processors. This means that a context processor may overwrite a
    variable you've supplied, so take care to avoid variable names
    which overlap with those supplied by your context processors.

Also, you can give ``RequestContext`` a list of additional processors, using the
optional, third positional argument, ``processors``. In this example, the
``RequestContext`` instance gets a ``ip_address`` variable::

    def ip_address_processor(request):
        return {'ip_address': request.META['REMOTE_ADDR']}

    def some_view(request):
        # ...
        c = RequestContext(request, {
            'foo': 'bar',
        }, [ip_address_processor])
        return HttpResponse(t.render(c))

.. note::
    If you're using Django's ``render_to_response()`` shortcut to populate a
    template with the contents of a dictionary, your template will be passed a
    ``Context`` instance by default (not a ``RequestContext``). To use a
    ``RequestContext`` in your template rendering, pass an optional third
    argument to ``render_to_response()``: a ``RequestContext``
    instance. Your code might look like this::

        def some_view(request):
            # ...
            return render_to_response('my_template.html',
                                      my_data_dictionary,
                                      context_instance=RequestContext(request))

Here's what each of the default processors does:

django.contrib.auth.context_processors.auth
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
``RequestContext`` will contain these three variables:

    * ``user`` -- An ``auth.User`` instance representing the currently
      logged-in user (or an ``AnonymousUser`` instance, if the client isn't
      logged in).

    * ``perms`` -- An instance of
      ``django.contrib.auth.context_processors.PermWrapper``, representing the
      permissions that the currently logged-in user has.

.. versionchanged:: 1.2
    This context processor was moved in this release from
    ``django.core.context_processors.auth`` to its current location.

.. versionchanged:: 1.3
    Prior to version 1.3, ``PermWrapper`` was located in
    ``django.contrib.auth.context_processors``.


django.core.context_processors.debug
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
``RequestContext`` will contain these two variables -- but only if your
:setting:`DEBUG` setting is set to ``True`` and the request's IP address
(``request.META['REMOTE_ADDR']``) is in the :setting:`INTERNAL_IPS` setting:

    * ``debug`` -- ``True``. You can use this in templates to test whether
      you're in :setting:`DEBUG` mode.
    * ``sql_queries`` -- A list of ``{'sql': ..., 'time': ...}`` dictionaries,
      representing every SQL query that has happened so far during the request
      and how long it took. The list is in order by query.

django.core.context_processors.i18n
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
``RequestContext`` will contain these two variables:

    * ``LANGUAGES`` -- The value of the :setting:`LANGUAGES` setting.
    * ``LANGUAGE_CODE`` -- ``request.LANGUAGE_CODE``, if it exists. Otherwise,
      the value of the :setting:`LANGUAGE_CODE` setting.

See :doc:`/topics/i18n/index` for more.

django.core.context_processors.media
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
``RequestContext`` will contain a variable ``MEDIA_URL``, providing the
value of the :setting:`MEDIA_URL` setting.

django.core.context_processors.static
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 1.3

If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
``RequestContext`` will contain a variable ``STATIC_URL``, providing the
value of the :setting:`STATIC_URL` setting.

django.core.context_processors.csrf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 1.2

This processor adds a token that is needed by the ``csrf_token`` template tag
for protection against :doc:`Cross Site Request Forgeries </ref/contrib/csrf>`.

django.core.context_processors.request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
``RequestContext`` will contain a variable ``request``, which is the current
:class:`~django.http.HttpRequest`. Note that this processor is not enabled by default;
you'll have to activate it.

django.contrib.messages.context_processors.messages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
``RequestContext`` will contain a single additional variable:

    * ``messages`` -- A list of messages (as strings) that have been set
      via the user model (using ``user.message_set.create``) or through
      the :doc:`messages framework </ref/contrib/messages>`.

.. versionadded:: 1.2
   This template context variable was previously supplied by the ``'auth'``
   context processor.  For backwards compatibility the ``'auth'`` context
   processor will continue to supply the ``messages`` variable until Django
   1.4.  If you use the ``messages`` variable, your project will work with
   either (or both) context processors, but it is recommended to add
   ``django.contrib.messages.context_processors.messages`` so your project
   will be prepared for the future upgrade.

Writing your own context processors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A context processor has a very simple interface: It's just a Python function
that takes one argument, an :class:`~django.http.HttpRequest` object, and
returns a dictionary that gets added to the template context. Each context
processor *must* return a dictionary.

Custom context processors can live anywhere in your code base. All Django cares
about is that your custom context processors are pointed-to by your
:setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.

Loading templates
-----------------

Generally, you'll store templates in files on your filesystem rather than using
the low-level ``Template`` API yourself. Save templates in a directory
specified as a **template directory**.

Django searches for template directories in a number of places, depending on
your template-loader settings (see "Loader types" below), but the most basic
way of specifying template directories is by using the :setting:`TEMPLATE_DIRS`
setting.

The TEMPLATE_DIRS setting
~~~~~~~~~~~~~~~~~~~~~~~~~

Tell Django what your template directories are by using the
:setting:`TEMPLATE_DIRS` setting in your settings file. This should be set to a
list or tuple of strings that contain full paths to your template
directory(ies). Example::

    TEMPLATE_DIRS = (
        "/home/html/templates/lawrence.com",
        "/home/html/templates/default",
    )

Your templates can go anywhere you want, as long as the directories and
templates are readable by the Web server. They can have any extension you want,
such as ``.html`` or ``.txt``, or they can have no extension at all.

Note that these paths should use Unix-style forward slashes, even on Windows.

.. _ref-templates-api-the-python-api:

The Python API
~~~~~~~~~~~~~~

Django has two ways to load templates from files:

.. function:: django.template.loader.get_template(template_name)

    ``get_template`` returns the compiled template (a ``Template`` object) for
    the template with the given name. If the template doesn't exist, it raises
    ``django.template.TemplateDoesNotExist``.

.. function:: django.template.loader.select_template(template_name_list)

    ``select_template`` is just like ``get_template``, except it takes a list
    of template names. Of the list, it returns the first template that exists.

For example, if you call ``get_template('story_detail.html')`` and have the
above :setting:`TEMPLATE_DIRS` setting, here are the files Django will look for,
in order:

    * ``/home/html/templates/lawrence.com/story_detail.html``
    * ``/home/html/templates/default/story_detail.html``

If you call ``select_template(['story_253_detail.html', 'story_detail.html'])``,
here's what Django will look for:

    * ``/home/html/templates/lawrence.com/story_253_detail.html``
    * ``/home/html/templates/default/story_253_detail.html``
    * ``/home/html/templates/lawrence.com/story_detail.html``
    * ``/home/html/templates/default/story_detail.html``

When Django finds a template that exists, it stops looking.

.. admonition:: Tip

    You can use ``select_template()`` for super-flexible "templatability." For
    example, if you've written a news story and want some stories to have
    custom templates, use something like
    ``select_template(['story_%s_detail.html' % story.id, 'story_detail.html'])``.
    That'll allow you to use a custom template for an individual story, with a
    fallback template for stories that don't have custom templates.

Using subdirectories
~~~~~~~~~~~~~~~~~~~~

It's possible -- and preferable -- to organize templates in subdirectories of
the template directory. The convention is to make a subdirectory for each
Django app, with subdirectories within those subdirectories as needed.

Do this for your own sanity. Storing all templates in the root level of a
single directory gets messy.

To load a template that's within a subdirectory, just use a slash, like so::

    get_template('news/story_detail.html')

Using the same :setting:`TEMPLATE_DIRS` setting from above, this example
``get_template()`` call will attempt to load the following templates:

    * ``/home/html/templates/lawrence.com/news/story_detail.html``
    * ``/home/html/templates/default/news/story_detail.html``

.. _template-loaders:

Loader types
~~~~~~~~~~~~

By default, Django uses a filesystem-based template loader, but Django comes
with a few other template loaders, which know how to load templates from other
sources.

Some of these other loaders are disabled by default, but you can activate them
by editing your :setting:`TEMPLATE_LOADERS` setting. :setting:`TEMPLATE_LOADERS`
should be a tuple of strings, where each string represents a template loader
class. Here are the template loaders that come with Django:

.. versionchanged:: 1.2
    Template loaders were based on callables (usually functions) before Django
    1.2, starting with the 1.2 release there is a new class-based API, all the
    loaders described below implement this new API.

``django.template.loaders.filesystem.Loader``
    Loads templates from the filesystem, according to :setting:`TEMPLATE_DIRS`.
    This loader is enabled by default.

``django.template.loaders.app_directories.Loader``
    Loads templates from Django apps on the filesystem. For each app in
    :setting:`INSTALLED_APPS`, the loader looks for a ``templates``
    subdirectory. If the directory exists, Django looks for templates in there.

    This means you can store templates with your individual apps. This also
    makes it easy to distribute Django apps with default templates.

    For example, for this setting::

        INSTALLED_APPS = ('myproject.polls', 'myproject.music')

    ...then ``get_template('foo.html')`` will look for templates in these
    directories, in this order:

        * ``/path/to/myproject/polls/templates/foo.html``
        * ``/path/to/myproject/music/templates/foo.html``

    Note that the loader performs an optimization when it is first imported: It
    caches a list of which :setting:`INSTALLED_APPS` packages have a
    ``templates`` subdirectory.

    This loader is enabled by default.

``django.template.loaders.eggs.Loader``
    Just like ``app_directories`` above, but it loads templates from Python
    eggs rather than from the filesystem.

    This loader is disabled by default.

``django.template.loaders.cached.Loader``
    By default, the templating system will read and compile your templates every
    time they need to be rendered. While the Django templating system is quite
    fast, the overhead from reading and compiling templates can add up.

    The cached template loader is a class-based loader that you configure with
    a list of other loaders that it should wrap. The wrapped loaders are used to
    locate unknown templates when they are first encountered. The cached loader
    then stores the compiled ``Template`` in memory. The cached ``Template``
    instance is returned for subsequent requests to load the same template.

    For example, to enable template caching with the ``filesystem`` and
    ``app_directories`` template loaders you might use the following settings::

        TEMPLATE_LOADERS = (
            ('django.template.loaders.cached.Loader', (
                'django.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
            )),
        )

    .. note::
        All of the built-in Django template tags are safe to use with the cached
        loader, but if you're using custom template tags that come from third
        party packages, or that you wrote yourself, you should ensure that the
        ``Node`` implementation for each tag is thread-safe. For more
        information, see
        :ref:`template tag thread safety considerations<template_tag_thread_safety>`.

    This loader is disabled by default.

Django uses the template loaders in order according to the
:setting:`TEMPLATE_LOADERS` setting. It uses each loader until a loader finds a
match.

The ``render_to_string`` shortcut
===================================

.. function:: django.template.loader.render_to_string(template_name, dictionary=None, context_instance=None)

To cut down on the repetitive nature of loading and rendering
templates, Django provides a shortcut function which largely
automates the process: ``render_to_string()`` in
:mod:`django.template.loader`, which loads a template, renders it and
returns the resulting string::

    from django.template.loader import render_to_string
    rendered = render_to_string('my_template.html', { 'foo': 'bar' })

The ``render_to_string`` shortcut takes one required argument --
``template_name``, which should be the name of the template to load
and render (or a list of template names, in which case Django will use
the first template in the list that exists) -- and two optional arguments:

    dictionary
        A dictionary to be used as variables and values for the
        template's context. This can also be passed as the second
        positional argument.

    context_instance
        An instance of ``Context`` or a subclass (e.g., an instance of
        ``RequestContext``) to use as the template's context. This can
        also be passed as the third positional argument.

See also the :func:`~django.shortcuts.render_to_response()` shortcut, which
calls ``render_to_string`` and feeds the result into an :class:`~django.http.HttpResponse`
suitable for returning directly from a view.

Configuring the template system in standalone mode
==================================================

.. note::

    This section is only of interest to people trying to use the template
    system as an output component in another application. If you're using the
    template system as part of a Django application, nothing here applies to
    you.

Normally, Django will load all the configuration information it needs from its
own default configuration file, combined with the settings in the module given
in the :envvar:`DJANGO_SETTINGS_MODULE` environment variable. But if you're
using the template system independently of the rest of Django, the environment
variable approach isn't very convenient, because you probably want to configure
the template system in line with the rest of your application rather than
dealing with settings files and pointing to them via environment variables.

To solve this problem, you need to use the manual configuration option described
in :ref:`settings-without-django-settings-module`. Simply import the appropriate
pieces of the templating system and then, *before* you call any of the
templating functions, call :func:`django.conf.settings.configure()` with any
settings you wish to specify. You might want to consider setting at least
:setting:`TEMPLATE_DIRS` (if you're going to use template loaders),
:setting:`DEFAULT_CHARSET` (although the default of ``utf-8`` is probably fine)
and :setting:`TEMPLATE_DEBUG`. All available settings are described in the
:doc:`settings documentation </ref/settings>`, and any setting starting with
``TEMPLATE_`` is of obvious interest.

.. _topic-template-alternate-language:

Using an alternative template language
======================================

.. versionadded:: 1.2

The Django ``Template`` and ``Loader`` classes implement a simple API for
loading and rendering templates. By providing some simple wrapper classes that
implement this API we can use third party template systems like `Jinja2
<http://jinja.pocoo.org/2/>`_ or `Cheetah <http://www.cheetahtemplate.org/>`_. This
allows us to use third-party template libraries without giving up useful Django
features like the Django ``Context`` object and handy shortcuts like
``render_to_response()``.

The core component of the Django templating system is the ``Template`` class.
This class has a very simple interface: it has a constructor that takes a single
positional argument specifying the template string, and a ``render()`` method
that takes a :class:`~django.template.Context` object and returns a string
containing the rendered response.

Suppose we're using a template language that defines a ``Template`` object with
a ``render()`` method that takes a dictionary rather than a ``Context`` object.
We can write a simple wrapper that implements the Django ``Template`` interface::

    import some_template_language
    class Template(some_template_language.Template):
        def render(self, context):
            # flatten the Django Context into a single dictionary.
            context_dict = {}
            for d in context.dicts:
                context_dict.update(d)
            return super(Template, self).render(context_dict)

That's all that's required to make our fictional ``Template`` class compatible
with the Django loading and rendering system!

The next step is to write a ``Loader`` class that returns instances of our custom
template class instead of the default :class:`~django.template.Template`. Custom ``Loader``
classes should inherit from ``django.template.loader.BaseLoader`` and override
the ``load_template_source()`` method, which takes a ``template_name`` argument,
loads the template from disk (or elsewhere), and returns a tuple:
``(template_string, template_origin)``.

The ``load_template()`` method of the ``Loader`` class retrieves the template
string by calling ``load_template_source()``, instantiates a ``Template`` from
the template source, and returns a tuple: ``(template, template_origin)``. Since
this is the method that actually instantiates the ``Template``, we'll need to
override it to use our custom template class instead. We can inherit from the
builtin :class:`django.template.loaders.app_directories.Loader` to take advantage
of the ``load_template_source()`` method implemented there::

    from django.template.loaders import app_directories
    class Loader(app_directories.Loader):
        is_usable = True

        def load_template(self, template_name, template_dirs=None):
            source, origin = self.load_template_source(template_name, template_dirs)
            template = Template(source)
            return template, origin

Finally, we need to modify our project settings, telling Django to use our custom
loader. Now we can write all of our templates in our alternative template
language while continuing to use the rest of the Django templating system.