api.txt 33 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850
  1. ====================================================
  2. The Django template language: For Python programmers
  3. ====================================================
  4. This document explains the Django template system from a technical
  5. perspective -- how it works and how to extend it. If you're just looking for
  6. reference on the language syntax, see :doc:`/topics/templates`.
  7. If you're looking to use the Django template system as part of another
  8. application -- i.e., without the rest of the framework -- make sure to read
  9. the `configuration`_ section later in this document.
  10. .. _configuration: `configuring the template system in standalone mode`_
  11. Basics
  12. ======
  13. A **template** is a text document, or a normal Python string, that is marked-up
  14. using the Django template language. A template can contain **block tags** or
  15. **variables**.
  16. A **block tag** is a symbol within a template that does something.
  17. This definition is deliberately vague. For example, a block tag can output
  18. content, serve as a control structure (an "if" statement or "for" loop), grab
  19. content from a database or enable access to other template tags.
  20. Block tags are surrounded by ``"{%"`` and ``"%}"``.
  21. Example template with block tags:
  22. .. code-block:: html+django
  23. {% if is_logged_in %}Thanks for logging in!{% else %}Please log in.{% endif %}
  24. A **variable** is a symbol within a template that outputs a value.
  25. Variable tags are surrounded by ``"{{"`` and ``"}}"``.
  26. Example template with variables:
  27. .. code-block:: html+django
  28. My first name is {{ first_name }}. My last name is {{ last_name }}.
  29. A **context** is a "variable name" -> "variable value" mapping that is passed
  30. to a template.
  31. A template **renders** a context by replacing the variable "holes" with values
  32. from the context and executing all block tags.
  33. Using the template system
  34. =========================
  35. .. class:: django.template.Template
  36. Using the template system in Python is a two-step process:
  37. * First, you compile the raw template code into a ``Template`` object.
  38. * Then, you call the ``render()`` method of the ``Template`` object with a
  39. given context.
  40. Compiling a string
  41. ------------------
  42. The easiest way to create a ``Template`` object is by instantiating it
  43. directly. The class lives at :class:`django.template.Template`. The constructor
  44. takes one argument -- the raw template code::
  45. >>> from django.template import Template
  46. >>> t = Template("My name is {{ my_name }}.")
  47. >>> print(t)
  48. <django.template.Template instance>
  49. .. admonition:: Behind the scenes
  50. The system only parses your raw template code once -- when you create the
  51. ``Template`` object. From then on, it's stored internally as a "node"
  52. structure for performance.
  53. Even the parsing itself is quite fast. Most of the parsing happens via a
  54. single call to a single, short, regular expression.
  55. Rendering a context
  56. -------------------
  57. .. method:: render(context)
  58. Once you have a compiled ``Template`` object, you can render a context -- or
  59. multiple contexts -- with it. The ``Context`` class lives at
  60. :class:`django.template.Context`, and the constructor takes two (optional)
  61. arguments:
  62. * A dictionary mapping variable names to variable values.
  63. * The name of the current application. This application name is used
  64. to help :ref:`resolve namespaced URLs<topics-http-reversing-url-namespaces>`.
  65. If you're not using namespaced URLs, you can ignore this argument.
  66. Call the ``Template`` object's ``render()`` method with the context to "fill" the
  67. template::
  68. >>> from django.template import Context, Template
  69. >>> t = Template("My name is {{ my_name }}.")
  70. >>> c = Context({"my_name": "Adrian"})
  71. >>> t.render(c)
  72. "My name is Adrian."
  73. >>> c = Context({"my_name": "Dolores"})
  74. >>> t.render(c)
  75. "My name is Dolores."
  76. Variables and lookups
  77. ~~~~~~~~~~~~~~~~~~~~~
  78. Variable names must consist of any letter (A-Z), any digit (0-9), an underscore
  79. (but they must not start with an underscore) or a dot.
  80. Dots have a special meaning in template rendering. A dot in a variable name
  81. signifies a **lookup**. Specifically, when the template system encounters a
  82. dot in a variable name, it tries the following lookups, in this order:
  83. * Dictionary lookup. Example: ``foo["bar"]``
  84. * Attribute lookup. Example: ``foo.bar``
  85. * List-index lookup. Example: ``foo[bar]``
  86. Note that "bar" in a template expression like ``{{ foo.bar }}`` will be
  87. interpreted as a literal string and not using the value of the variable "bar",
  88. if one exists in the template context.
  89. The template system uses the first lookup type that works. It's short-circuit
  90. logic. Here are a few examples::
  91. >>> from django.template import Context, Template
  92. >>> t = Template("My name is {{ person.first_name }}.")
  93. >>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}
  94. >>> t.render(Context(d))
  95. "My name is Joe."
  96. >>> class PersonClass: pass
  97. >>> p = PersonClass()
  98. >>> p.first_name = "Ron"
  99. >>> p.last_name = "Nasty"
  100. >>> t.render(Context({"person": p}))
  101. "My name is Ron."
  102. >>> t = Template("The first stooge in the list is {{ stooges.0 }}.")
  103. >>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})
  104. >>> t.render(c)
  105. "The first stooge in the list is Larry."
  106. If any part of the variable is callable, the template system will try calling
  107. it. Example::
  108. >>> class PersonClass2:
  109. ... def name(self):
  110. ... return "Samantha"
  111. >>> t = Template("My name is {{ person.name }}.")
  112. >>> t.render(Context({"person": PersonClass2}))
  113. "My name is Samantha."
  114. .. versionchanged:: 1.3
  115. Previously, only variables that originated with an attribute lookup would
  116. be called by the template system. This change was made for consistency
  117. across lookup types.
  118. Callable variables are slightly more complex than variables which only require
  119. straight lookups. Here are some things to keep in mind:
  120. * If the variable raises an exception when called, the exception will be
  121. propagated, unless the exception has an attribute
  122. ``silent_variable_failure`` whose value is ``True``. If the exception
  123. *does* have a ``silent_variable_failure`` attribute whose value is
  124. ``True``, the variable will render as an empty string. Example::
  125. >>> t = Template("My name is {{ person.first_name }}.")
  126. >>> class PersonClass3:
  127. ... def first_name(self):
  128. ... raise AssertionError("foo")
  129. >>> p = PersonClass3()
  130. >>> t.render(Context({"person": p}))
  131. Traceback (most recent call last):
  132. ...
  133. AssertionError: foo
  134. >>> class SilentAssertionError(Exception):
  135. ... silent_variable_failure = True
  136. >>> class PersonClass4:
  137. ... def first_name(self):
  138. ... raise SilentAssertionError
  139. >>> p = PersonClass4()
  140. >>> t.render(Context({"person": p}))
  141. "My name is ."
  142. Note that :exc:`django.core.exceptions.ObjectDoesNotExist`, which is the
  143. base class for all Django database API ``DoesNotExist`` exceptions, has
  144. ``silent_variable_failure = True``. So if you're using Django templates
  145. with Django model objects, any ``DoesNotExist`` exception will fail
  146. silently.
  147. * A variable can only be called if it has no required arguments. Otherwise,
  148. the system will return an empty string.
  149. .. _alters-data-description:
  150. * Obviously, there can be side effects when calling some variables, and
  151. it'd be either foolish or a security hole to allow the template system
  152. to access them.
  153. A good example is the :meth:`~django.db.models.Model.delete` method on
  154. each Django model object. The template system shouldn't be allowed to do
  155. something like this::
  156. I will now delete this valuable data. {{ data.delete }}
  157. To prevent this, set an ``alters_data`` attribute on the callable
  158. variable. The template system won't call a variable if it has
  159. ``alters_data=True`` set, and will instead replace the variable with
  160. :setting:`TEMPLATE_STRING_IF_INVALID`, unconditionally. The
  161. dynamically-generated :meth:`~django.db.models.Model.delete` and
  162. :meth:`~django.db.models.Model.save` methods on Django model objects get
  163. ``alters_data=True`` automatically. Example::
  164. def sensitive_function(self):
  165. self.database_record.delete()
  166. sensitive_function.alters_data = True
  167. * .. versionadded:: 1.4
  168. Occasionally you may want to turn off this feature for other reasons,
  169. and tell the template system to leave a variable un-called no matter
  170. what. To do so, set a ``do_not_call_in_templates`` attribute on the
  171. callable with the value ``True``. The template system then will act as
  172. if your variable is not callable (allowing you to access attributes of
  173. the callable, for example).
  174. .. _invalid-template-variables:
  175. How invalid variables are handled
  176. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  177. Generally, if a variable doesn't exist, the template system inserts the
  178. value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set to
  179. ``''`` (the empty string) by default.
  180. Filters that are applied to an invalid variable will only be applied if
  181. :setting:`TEMPLATE_STRING_IF_INVALID` is set to ``''`` (the empty string). If
  182. :setting:`TEMPLATE_STRING_IF_INVALID` is set to any other value, variable
  183. filters will be ignored.
  184. This behavior is slightly different for the ``if``, ``for`` and ``regroup``
  185. template tags. If an invalid variable is provided to one of these template
  186. tags, the variable will be interpreted as ``None``. Filters are always
  187. applied to invalid variables within these template tags.
  188. If :setting:`TEMPLATE_STRING_IF_INVALID` contains a ``'%s'``, the format marker will
  189. be replaced with the name of the invalid variable.
  190. .. admonition:: For debug purposes only!
  191. While :setting:`TEMPLATE_STRING_IF_INVALID` can be a useful debugging tool,
  192. it is a bad idea to turn it on as a 'development default'.
  193. Many templates, including those in the Admin site, rely upon the
  194. silence of the template system when a non-existent variable is
  195. encountered. If you assign a value other than ``''`` to
  196. :setting:`TEMPLATE_STRING_IF_INVALID`, you will experience rendering
  197. problems with these templates and sites.
  198. Generally, :setting:`TEMPLATE_STRING_IF_INVALID` should only be enabled
  199. in order to debug a specific template problem, then cleared
  200. once debugging is complete.
  201. Builtin variables
  202. ~~~~~~~~~~~~~~~~~
  203. Every context contains ``True``, ``False`` and ``None``. As you would expect,
  204. these variables resolve to the corresponding Python objects.
  205. .. versionadded:: 1.5
  206. Before Django 1.5, these variables weren't a special case, and they
  207. resolved to ``None`` unless you defined them in the context.
  208. Playing with Context objects
  209. ----------------------------
  210. .. class:: django.template.Context
  211. Most of the time, you'll instantiate ``Context`` objects by passing in a
  212. fully-populated dictionary to ``Context()``. But you can add and delete items
  213. from a ``Context`` object once it's been instantiated, too, using standard
  214. dictionary syntax::
  215. >>> c = Context({"foo": "bar"})
  216. >>> c['foo']
  217. 'bar'
  218. >>> del c['foo']
  219. >>> c['foo']
  220. ''
  221. >>> c['newvariable'] = 'hello'
  222. >>> c['newvariable']
  223. 'hello'
  224. .. method:: pop()
  225. .. method:: push()
  226. .. exception:: django.template.ContextPopException
  227. A ``Context`` object is a stack. That is, you can ``push()`` and ``pop()`` it.
  228. If you ``pop()`` too much, it'll raise
  229. ``django.template.ContextPopException``::
  230. >>> c = Context()
  231. >>> c['foo'] = 'first level'
  232. >>> c.push()
  233. >>> c['foo'] = 'second level'
  234. >>> c['foo']
  235. 'second level'
  236. >>> c.pop()
  237. >>> c['foo']
  238. 'first level'
  239. >>> c['foo'] = 'overwritten'
  240. >>> c['foo']
  241. 'overwritten'
  242. >>> c.pop()
  243. Traceback (most recent call last):
  244. ...
  245. django.template.ContextPopException
  246. .. method:: update(other_dict)
  247. In addition to ``push()`` and ``pop()``, the ``Context``
  248. object also defines an ``update()`` method. This works like ``push()``
  249. but takes a dictionary as an argument and pushes that dictionary onto
  250. the stack instead of an empty one.
  251. >>> c = Context()
  252. >>> c['foo'] = 'first level'
  253. >>> c.update({'foo': 'updated'})
  254. {'foo': 'updated'}
  255. >>> c['foo']
  256. 'updated'
  257. >>> c.pop()
  258. {'foo': 'updated'}
  259. >>> c['foo']
  260. 'first level'
  261. Using a ``Context`` as a stack comes in handy in some custom template tags, as
  262. you'll see below.
  263. .. _subclassing-context-requestcontext:
  264. Subclassing Context: RequestContext
  265. -----------------------------------
  266. .. class:: django.template.RequestContext
  267. Django comes with a special ``Context`` class,
  268. ``django.template.RequestContext``, that acts slightly differently than the
  269. normal ``django.template.Context``. The first difference is that it takes an
  270. :class:`~django.http.HttpRequest` as its first argument. For example::
  271. c = RequestContext(request, {
  272. 'foo': 'bar',
  273. })
  274. The second difference is that it automatically populates the context with a few
  275. variables, according to your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
  276. The :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting is a tuple of callables --
  277. called **context processors** -- that take a request object as their argument
  278. and return a dictionary of items to be merged into the context. By default,
  279. :setting:`TEMPLATE_CONTEXT_PROCESSORS` is set to::
  280. ("django.contrib.auth.context_processors.auth",
  281. "django.core.context_processors.debug",
  282. "django.core.context_processors.i18n",
  283. "django.core.context_processors.media",
  284. "django.core.context_processors.static",
  285. "django.core.context_processors.tz",
  286. "django.contrib.messages.context_processors.messages")
  287. In addition to these, ``RequestContext`` always uses
  288. ``django.core.context_processors.csrf``. This is a security
  289. related context processor required by the admin and other contrib apps, and,
  290. in case of accidental misconfiguration, it is deliberately hardcoded in and
  291. cannot be turned off by the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
  292. Each processor is applied in order. That means, if one processor adds a
  293. variable to the context and a second processor adds a variable with the same
  294. name, the second will override the first. The default processors are explained
  295. below.
  296. .. admonition:: When context processors are applied
  297. When you use ``RequestContext``, the variables you supply directly
  298. are added first, followed any variables supplied by context
  299. processors. This means that a context processor may overwrite a
  300. variable you've supplied, so take care to avoid variable names
  301. which overlap with those supplied by your context processors.
  302. Also, you can give ``RequestContext`` a list of additional processors, using the
  303. optional, third positional argument, ``processors``. In this example, the
  304. ``RequestContext`` instance gets a ``ip_address`` variable::
  305. def ip_address_processor(request):
  306. return {'ip_address': request.META['REMOTE_ADDR']}
  307. def some_view(request):
  308. # ...
  309. c = RequestContext(request, {
  310. 'foo': 'bar',
  311. }, [ip_address_processor])
  312. return HttpResponse(t.render(c))
  313. .. note::
  314. If you're using Django's :func:`~django.shortcuts.render_to_response()`
  315. shortcut to populate a template with the contents of a dictionary, your
  316. template will be passed a ``Context`` instance by default (not a
  317. ``RequestContext``). To use a ``RequestContext`` in your template
  318. rendering, pass an optional third argument to
  319. :func:`~django.shortcuts.render_to_response()`: a ``RequestContext``
  320. instance. Your code might look like this::
  321. def some_view(request):
  322. # ...
  323. return render_to_response('my_template.html',
  324. my_data_dictionary,
  325. context_instance=RequestContext(request))
  326. Alternatively, use the :meth:`~django.shortcuts.render()` shortcut which is
  327. the same as a call to :func:`~django.shortcuts.render_to_response()` with a
  328. context_instance argument that forces the use of a ``RequestContext``.
  329. Here's what each of the default processors does:
  330. django.contrib.auth.context_processors.auth
  331. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  332. If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
  333. ``RequestContext`` will contain these three variables:
  334. * ``user`` -- An ``auth.User`` instance representing the currently
  335. logged-in user (or an ``AnonymousUser`` instance, if the client isn't
  336. logged in).
  337. * ``perms`` -- An instance of
  338. ``django.contrib.auth.context_processors.PermWrapper``, representing the
  339. permissions that the currently logged-in user has.
  340. .. versionchanged:: 1.3
  341. Prior to version 1.3, ``PermWrapper`` was located in
  342. ``django.contrib.auth.context_processors``.
  343. django.core.context_processors.debug
  344. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  345. If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
  346. ``RequestContext`` will contain these two variables -- but only if your
  347. :setting:`DEBUG` setting is set to ``True`` and the request's IP address
  348. (``request.META['REMOTE_ADDR']``) is in the :setting:`INTERNAL_IPS` setting:
  349. * ``debug`` -- ``True``. You can use this in templates to test whether
  350. you're in :setting:`DEBUG` mode.
  351. * ``sql_queries`` -- A list of ``{'sql': ..., 'time': ...}`` dictionaries,
  352. representing every SQL query that has happened so far during the request
  353. and how long it took. The list is in order by query.
  354. django.core.context_processors.i18n
  355. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  356. If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
  357. ``RequestContext`` will contain these two variables:
  358. * ``LANGUAGES`` -- The value of the :setting:`LANGUAGES` setting.
  359. * ``LANGUAGE_CODE`` -- ``request.LANGUAGE_CODE``, if it exists. Otherwise,
  360. the value of the :setting:`LANGUAGE_CODE` setting.
  361. See :doc:`/topics/i18n/index` for more.
  362. django.core.context_processors.media
  363. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  364. If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
  365. ``RequestContext`` will contain a variable ``MEDIA_URL``, providing the
  366. value of the :setting:`MEDIA_URL` setting.
  367. django.core.context_processors.static
  368. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  369. .. function:: django.core.context_processors.static
  370. .. versionadded:: 1.3
  371. If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
  372. ``RequestContext`` will contain a variable ``STATIC_URL``, providing the
  373. value of the :setting:`STATIC_URL` setting.
  374. django.core.context_processors.csrf
  375. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  376. This processor adds a token that is needed by the :ttag:`csrf_token` template
  377. tag for protection against :doc:`Cross Site Request Forgeries
  378. </ref/contrib/csrf>`.
  379. django.core.context_processors.request
  380. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  381. If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
  382. ``RequestContext`` will contain a variable ``request``, which is the current
  383. :class:`~django.http.HttpRequest`. Note that this processor is not enabled by default;
  384. you'll have to activate it.
  385. django.contrib.messages.context_processors.messages
  386. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  387. If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
  388. ``RequestContext`` will contain a single additional variable:
  389. * ``messages`` -- A list of messages (as strings) that have been set
  390. via the user model (using ``user.message_set.create``) or through
  391. the :doc:`messages framework </ref/contrib/messages>`.
  392. Writing your own context processors
  393. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  394. A context processor has a very simple interface: It's just a Python function
  395. that takes one argument, an :class:`~django.http.HttpRequest` object, and
  396. returns a dictionary that gets added to the template context. Each context
  397. processor *must* return a dictionary.
  398. Custom context processors can live anywhere in your code base. All Django cares
  399. about is that your custom context processors are pointed-to by your
  400. :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
  401. Loading templates
  402. -----------------
  403. Generally, you'll store templates in files on your filesystem rather than using
  404. the low-level ``Template`` API yourself. Save templates in a directory
  405. specified as a **template directory**.
  406. Django searches for template directories in a number of places, depending on
  407. your template-loader settings (see "Loader types" below), but the most basic
  408. way of specifying template directories is by using the :setting:`TEMPLATE_DIRS`
  409. setting.
  410. The TEMPLATE_DIRS setting
  411. ~~~~~~~~~~~~~~~~~~~~~~~~~
  412. Tell Django what your template directories are by using the
  413. :setting:`TEMPLATE_DIRS` setting in your settings file. This should be set to a
  414. list or tuple of strings that contain full paths to your template
  415. directory(ies). Example::
  416. TEMPLATE_DIRS = (
  417. "/home/html/templates/lawrence.com",
  418. "/home/html/templates/default",
  419. )
  420. Your templates can go anywhere you want, as long as the directories and
  421. templates are readable by the Web server. They can have any extension you want,
  422. such as ``.html`` or ``.txt``, or they can have no extension at all.
  423. Note that these paths should use Unix-style forward slashes, even on Windows.
  424. .. _ref-templates-api-the-python-api:
  425. The Python API
  426. ~~~~~~~~~~~~~~
  427. Django has two ways to load templates from files:
  428. .. function:: django.template.loader.get_template(template_name)
  429. ``get_template`` returns the compiled template (a ``Template`` object) for
  430. the template with the given name. If the template doesn't exist, it raises
  431. ``django.template.TemplateDoesNotExist``.
  432. .. function:: django.template.loader.select_template(template_name_list)
  433. ``select_template`` is just like ``get_template``, except it takes a list
  434. of template names. Of the list, it returns the first template that exists.
  435. For example, if you call ``get_template('story_detail.html')`` and have the
  436. above :setting:`TEMPLATE_DIRS` setting, here are the files Django will look for,
  437. in order:
  438. * ``/home/html/templates/lawrence.com/story_detail.html``
  439. * ``/home/html/templates/default/story_detail.html``
  440. If you call ``select_template(['story_253_detail.html', 'story_detail.html'])``,
  441. here's what Django will look for:
  442. * ``/home/html/templates/lawrence.com/story_253_detail.html``
  443. * ``/home/html/templates/default/story_253_detail.html``
  444. * ``/home/html/templates/lawrence.com/story_detail.html``
  445. * ``/home/html/templates/default/story_detail.html``
  446. When Django finds a template that exists, it stops looking.
  447. .. admonition:: Tip
  448. You can use ``select_template()`` for super-flexible "templatability." For
  449. example, if you've written a news story and want some stories to have
  450. custom templates, use something like
  451. ``select_template(['story_%s_detail.html' % story.id, 'story_detail.html'])``.
  452. That'll allow you to use a custom template for an individual story, with a
  453. fallback template for stories that don't have custom templates.
  454. Using subdirectories
  455. ~~~~~~~~~~~~~~~~~~~~
  456. It's possible -- and preferable -- to organize templates in subdirectories of
  457. the template directory. The convention is to make a subdirectory for each
  458. Django app, with subdirectories within those subdirectories as needed.
  459. Do this for your own sanity. Storing all templates in the root level of a
  460. single directory gets messy.
  461. To load a template that's within a subdirectory, just use a slash, like so::
  462. get_template('news/story_detail.html')
  463. Using the same :setting:`TEMPLATE_DIRS` setting from above, this example
  464. ``get_template()`` call will attempt to load the following templates:
  465. * ``/home/html/templates/lawrence.com/news/story_detail.html``
  466. * ``/home/html/templates/default/news/story_detail.html``
  467. .. _template-loaders:
  468. Loader types
  469. ~~~~~~~~~~~~
  470. By default, Django uses a filesystem-based template loader, but Django comes
  471. with a few other template loaders, which know how to load templates from other
  472. sources.
  473. Some of these other loaders are disabled by default, but you can activate them
  474. by editing your :setting:`TEMPLATE_LOADERS` setting. :setting:`TEMPLATE_LOADERS`
  475. should be a tuple of strings, where each string represents a template loader
  476. class. Here are the template loaders that come with Django:
  477. ``django.template.loaders.filesystem.Loader``
  478. Loads templates from the filesystem, according to :setting:`TEMPLATE_DIRS`.
  479. This loader is enabled by default.
  480. ``django.template.loaders.app_directories.Loader``
  481. Loads templates from Django apps on the filesystem. For each app in
  482. :setting:`INSTALLED_APPS`, the loader looks for a ``templates``
  483. subdirectory. If the directory exists, Django looks for templates in there.
  484. This means you can store templates with your individual apps. This also
  485. makes it easy to distribute Django apps with default templates.
  486. For example, for this setting::
  487. INSTALLED_APPS = ('myproject.polls', 'myproject.music')
  488. ...then ``get_template('foo.html')`` will look for ``foo.html`` in these
  489. directories, in this order:
  490. * ``/path/to/myproject/polls/templates/``
  491. * ``/path/to/myproject/music/templates/``
  492. ... and will use the one it finds first.
  493. The order of :setting:`INSTALLED_APPS` is significant! For example, if you
  494. want to customize the Django admin, you might choose to override the
  495. standard ``admin/base_site.html`` template, from ``django.contrib.admin``,
  496. with your own ``admin/base_site.html`` in ``myproject.polls``. You must
  497. then make sure that your ``myproject.polls`` comes *before*
  498. ``django.contrib.admin`` in :setting:`INSTALLED_APPS`, otherwise
  499. ``django.contrib.admin``'s will be loaded first and yours will be ignored.
  500. Note that the loader performs an optimization when it is first imported:
  501. it caches a list of which :setting:`INSTALLED_APPS` packages have a
  502. ``templates`` subdirectory.
  503. This loader is enabled by default.
  504. ``django.template.loaders.eggs.Loader``
  505. Just like ``app_directories`` above, but it loads templates from Python
  506. eggs rather than from the filesystem.
  507. This loader is disabled by default.
  508. ``django.template.loaders.cached.Loader``
  509. By default, the templating system will read and compile your templates every
  510. time they need to be rendered. While the Django templating system is quite
  511. fast, the overhead from reading and compiling templates can add up.
  512. The cached template loader is a class-based loader that you configure with
  513. a list of other loaders that it should wrap. The wrapped loaders are used to
  514. locate unknown templates when they are first encountered. The cached loader
  515. then stores the compiled ``Template`` in memory. The cached ``Template``
  516. instance is returned for subsequent requests to load the same template.
  517. For example, to enable template caching with the ``filesystem`` and
  518. ``app_directories`` template loaders you might use the following settings::
  519. TEMPLATE_LOADERS = (
  520. ('django.template.loaders.cached.Loader', (
  521. 'django.template.loaders.filesystem.Loader',
  522. 'django.template.loaders.app_directories.Loader',
  523. )),
  524. )
  525. .. note::
  526. All of the built-in Django template tags are safe to use with the
  527. cached loader, but if you're using custom template tags that come from
  528. third party packages, or that you wrote yourself, you should ensure
  529. that the ``Node`` implementation for each tag is thread-safe. For more
  530. information, see :ref:`template tag thread safety
  531. considerations<template_tag_thread_safety>`.
  532. This loader is disabled by default.
  533. Django uses the template loaders in order according to the
  534. :setting:`TEMPLATE_LOADERS` setting. It uses each loader until a loader finds a
  535. match.
  536. The ``render_to_string`` shortcut
  537. ===================================
  538. .. function:: django.template.loader.render_to_string(template_name, dictionary=None, context_instance=None)
  539. To cut down on the repetitive nature of loading and rendering
  540. templates, Django provides a shortcut function which largely
  541. automates the process: ``render_to_string()`` in
  542. :mod:`django.template.loader`, which loads a template, renders it and
  543. returns the resulting string::
  544. from django.template.loader import render_to_string
  545. rendered = render_to_string('my_template.html', {'foo': 'bar'})
  546. The ``render_to_string`` shortcut takes one required argument --
  547. ``template_name``, which should be the name of the template to load
  548. and render (or a list of template names, in which case Django will use
  549. the first template in the list that exists) -- and two optional arguments:
  550. dictionary
  551. A dictionary to be used as variables and values for the
  552. template's context. This can also be passed as the second
  553. positional argument.
  554. context_instance
  555. An instance of ``Context`` or a subclass (e.g., an instance of
  556. ``RequestContext``) to use as the template's context. This can
  557. also be passed as the third positional argument.
  558. See also the :func:`~django.shortcuts.render_to_response()` shortcut, which
  559. calls ``render_to_string`` and feeds the result into an :class:`~django.http.HttpResponse`
  560. suitable for returning directly from a view.
  561. Configuring the template system in standalone mode
  562. ==================================================
  563. .. note::
  564. This section is only of interest to people trying to use the template
  565. system as an output component in another application. If you're using the
  566. template system as part of a Django application, nothing here applies to
  567. you.
  568. Normally, Django will load all the configuration information it needs from its
  569. own default configuration file, combined with the settings in the module given
  570. in the :envvar:`DJANGO_SETTINGS_MODULE` environment variable. But if you're
  571. using the template system independently of the rest of Django, the environment
  572. variable approach isn't very convenient, because you probably want to configure
  573. the template system in line with the rest of your application rather than
  574. dealing with settings files and pointing to them via environment variables.
  575. To solve this problem, you need to use the manual configuration option described
  576. in :ref:`settings-without-django-settings-module`. Simply import the appropriate
  577. pieces of the templating system and then, *before* you call any of the
  578. templating functions, call :func:`django.conf.settings.configure()` with any
  579. settings you wish to specify. You might want to consider setting at least
  580. :setting:`TEMPLATE_DIRS` (if you're going to use template loaders),
  581. :setting:`DEFAULT_CHARSET` (although the default of ``utf-8`` is probably fine)
  582. and :setting:`TEMPLATE_DEBUG`. If you plan to use the :ttag:`url` template tag,
  583. you will also need to set the :setting:`ROOT_URLCONF` setting. All available
  584. settings are described in the :doc:`settings documentation </ref/settings>`,
  585. and any setting starting with ``TEMPLATE_`` is of obvious interest.
  586. .. _topic-template-alternate-language:
  587. Using an alternative template language
  588. ======================================
  589. The Django ``Template`` and ``Loader`` classes implement a simple API for
  590. loading and rendering templates. By providing some simple wrapper classes that
  591. implement this API we can use third party template systems like `Jinja2
  592. <http://jinja.pocoo.org/docs/>`_ or `Cheetah <http://www.cheetahtemplate.org/>`_. This
  593. allows us to use third-party template libraries without giving up useful Django
  594. features like the Django ``Context`` object and handy shortcuts like
  595. :func:`~django.shortcuts.render_to_response()`.
  596. The core component of the Django templating system is the ``Template`` class.
  597. This class has a very simple interface: it has a constructor that takes a single
  598. positional argument specifying the template string, and a ``render()`` method
  599. that takes a :class:`~django.template.Context` object and returns a string
  600. containing the rendered response.
  601. Suppose we're using a template language that defines a ``Template`` object with
  602. a ``render()`` method that takes a dictionary rather than a ``Context`` object.
  603. We can write a simple wrapper that implements the Django ``Template`` interface::
  604. import some_template_language
  605. class Template(some_template_language.Template):
  606. def render(self, context):
  607. # flatten the Django Context into a single dictionary.
  608. context_dict = {}
  609. for d in context.dicts:
  610. context_dict.update(d)
  611. return super(Template, self).render(context_dict)
  612. That's all that's required to make our fictional ``Template`` class compatible
  613. with the Django loading and rendering system!
  614. The next step is to write a ``Loader`` class that returns instances of our custom
  615. template class instead of the default :class:`~django.template.Template`. Custom ``Loader``
  616. classes should inherit from ``django.template.loader.BaseLoader`` and override
  617. the ``load_template_source()`` method, which takes a ``template_name`` argument,
  618. loads the template from disk (or elsewhere), and returns a tuple:
  619. ``(template_string, template_origin)``.
  620. The ``load_template()`` method of the ``Loader`` class retrieves the template
  621. string by calling ``load_template_source()``, instantiates a ``Template`` from
  622. the template source, and returns a tuple: ``(template, template_origin)``. Since
  623. this is the method that actually instantiates the ``Template``, we'll need to
  624. override it to use our custom template class instead. We can inherit from the
  625. builtin :class:`django.template.loaders.app_directories.Loader` to take advantage
  626. of the ``load_template_source()`` method implemented there::
  627. from django.template.loaders import app_directories
  628. class Loader(app_directories.Loader):
  629. is_usable = True
  630. def load_template(self, template_name, template_dirs=None):
  631. source, origin = self.load_template_source(template_name, template_dirs)
  632. template = Template(source)
  633. return template, origin
  634. Finally, we need to modify our project settings, telling Django to use our custom
  635. loader. Now we can write all of our templates in our alternative template
  636. language while continuing to use the rest of the Django templating system.