{"title":"Templates","version":"2.0","locale":"ko","docname":"topics/templates","url":"/ko/2.0/topics/templates/","canonical":"https://djangodocs.dev/ko/2.0/topics/templates/","summary":"Being a web framework, Django needs a convenient way to generate HTML dynamically. The most common approach relies on templates. A template contains the static…","html":"

TemplatesLink to this heading#

\n

Being a web framework, Django needs a convenient way to generate HTML\ndynamically. The most common approach relies on templates. A template contains\nthe static parts of the desired HTML output as well as some special syntax\ndescribing how dynamic content will be inserted. For a hands-on example of\ncreating HTML pages with templates, see Tutorial 3.

\n

A Django project can be configured with one or several template engines (or\neven zero if you don’t use templates). Django ships built-in backends for its\nown template system, creatively called the Django template language (DTL), and\nfor the popular alternative Jinja2. Backends for other template languages may\nbe available from third-parties.

\n

Django defines a standard API for loading and rendering templates regardless\nof the backend. Loading consists of finding the template for a given identifier\nand preprocessing it, usually compiling it to an in-memory representation.\nRendering means interpolating the template with context data and returning the\nresulting string.

\n

The Django template language is Django’s own\ntemplate system. Until Django 1.8 it was the only built-in option available.\nIt’s a good template library even though it’s fairly opinionated and sports a\nfew idiosyncrasies. If you don’t have a pressing reason to choose another\nbackend, you should use the DTL, especially if you’re writing a pluggable\napplication and you intend to distribute templates. Django’s contrib apps that\ninclude templates, like django.contrib.admin,\nuse the DTL.

\n

For historical reasons, both the generic support for template engines and the\nimplementation of the Django template language live in the django.template\nnamespace.

\n\n
\n

Support for template enginesLink to this heading#

\n
\n

ConfigurationLink to this heading#

\n

Templates engines are configured with the TEMPLATES setting. It’s a\nlist of configurations, one for each engine. The default value is empty. The\nsettings.py generated by the startproject command defines a\nmore useful value:

\n
Code
TEMPLATES = [\n    {\n        'BACKEND': 'django.template.backends.django.DjangoTemplates',\n        'DIRS': [],\n        'APP_DIRS': True,\n        'OPTIONS': {\n            # ... some options here ...\n        },\n    },\n]\n
\n

BACKEND is a dotted Python path to a template\nengine class implementing Django’s template backend API. The built-in backends\nare django.template.backends.django.DjangoTemplates and\ndjango.template.backends.jinja2.Jinja2.

\n

Since most engines load templates from files, the top-level configuration for\neach engine contains two common settings:

\n\n

While uncommon, it’s possible to configure several instances of the same\nbackend with different options. In that case you should define a unique\nNAME for each engine.

\n

OPTIONS contains backend-specific settings.

\n
\n
\n

UsageLink to this heading#

\n

The django.template.loader module defines two functions to load templates.

\n
\n
\nget_template(template_name, using=None)Link to this definition#
\n

This function loads the template with the given name and returns a\nTemplate object.

\n

The exact type of the return value depends on the backend that loaded the\ntemplate. Each backend has its own Template class.

\n

get_template() tries each template engine in order until one succeeds.\nIf the template cannot be found, it raises\nTemplateDoesNotExist. If the template is found but\ncontains invalid syntax, it raises\nTemplateSyntaxError.

\n

How templates are searched and loaded depends on each engine’s backend and\nconfiguration.

\n

If you want to restrict the search to a particular template engine, pass\nthe engine’s NAME in the using argument.

\n
\n\n
\n
\nselect_template(template_name_list, using=None)Link to this definition#
\n

select_template() is just like get_template(), except it takes a\nlist of template names. It tries each name in order and returns the first\ntemplate that exists.

\n
\n\n

If loading a template fails, the following two exceptions, defined in\ndjango.template, may be raised:

\n
\n
\nexception TemplateDoesNotExist(msg, tried=None, backend=None, chain=None)Link to this definition#
\n

This exception is raised when a template cannot be found. It accepts the\nfollowing optional arguments for populating the template postmortem on the debug page:

\n
\n
backend

The template backend instance from which the exception originated.

\n
\n
tried

A list of sources that were tried when finding the template. This is\nformatted as a list of tuples containing (origin, status), where\norigin is an origin-like object and\nstatus is a string with the reason the template wasn’t found.

\n
\n
chain

A list of intermediate TemplateDoesNotExist\nexceptions raised when trying to load a template. This is used by\nfunctions, such as get_template(), that\ntry to load a given template from multiple engines.

\n
\n
\n
\n\n
\n
\nexception TemplateSyntaxError(msg)Link to this definition#
\n

This exception is raised when a template was found but contains errors.

\n
\n\n

Template objects returned by get_template() and select_template()\nmust provide a render() method with the following signature:

\n
\n
\nTemplate.render(context=None, request=None)Link to this definition#
\n

Renders this template with a given context.

\n

If context is provided, it must be a dict. If it isn’t\nprovided, the engine will render the template with an empty context.

\n

If request is provided, it must be an HttpRequest.\nThen the engine must make it, as well as the CSRF token, available in the\ntemplate. How this is achieved is up to each backend.

\n
\n\n

Here’s an example of the search algorithm. For this example the\nTEMPLATES setting is:

\n
Code
TEMPLATES = [\n    {\n        'BACKEND': 'django.template.backends.django.DjangoTemplates',\n        'DIRS': [\n            '/home/html/example.com',\n            '/home/html/default',\n        ],\n    },\n    {\n        'BACKEND': 'django.template.backends.jinja2.Jinja2',\n        'DIRS': [\n            '/home/html/jinja2',\n        ],\n    },\n]\n
\n

If you call get_template('story_detail.html'), here are the files Django\nwill look for, in order:

\n\n

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

\n\n

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

\n\n

It’s possible – and preferable – to organize templates in subdirectories\ninside each directory containing templates. The convention is to make a\nsubdirectory for each Django app, with subdirectories within those\nsubdirectories as needed.

\n

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

\n

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

\n
Code
get_template('news/story_detail.html')\n
\n

Using the same TEMPLATES option as above, this will attempt to load\nthe following templates:

\n\n

In addition, to cut down on the repetitive nature of loading and rendering\ntemplates, Django provides a shortcut function which automates the process.

\n
\n
\nrender_to_string(template_name, context=None, request=None, using=None)Link to this definition#
\n

render_to_string() loads a template like get_template() and\ncalls its render() method immediately. It takes the following\narguments.

\n
\n
template_name

The name of the template to load and render. If it’s a list of template\nnames, Django uses select_template() instead of\nget_template() to find the template.

\n
\n
context

A dict to be used as the template’s context for rendering.

\n
\n
request

An optional HttpRequest that will be available\nduring the template’s rendering process.

\n
\n
using

An optional template engine NAME. The\nsearch for the template will be restricted to that engine.

\n
\n
\n

Usage example:

\n
Code
from django.template.loader import render_to_string\nrendered = render_to_string('my_template.html', {'foo': 'bar'})\n
\n
\n\n

See also the render() shortcut which calls\nrender_to_string() and feeds the result into an\nHttpResponse suitable for returning from a view.

\n

Finally, you can use configured engines directly:

\n
\n
\nenginesLink to this definition#
\n

Template engines are available in django.template.engines:

\n
Code
from django.template import engines\n\ndjango_engine = engines['django']\ntemplate = django_engine.from_string("Hello {{ name }}!")\n
\n

The lookup key — 'django' in this example — is the engine’s\nNAME.

\n
\n\n
\n
\n

Built-in backendsLink to this heading#

\n
\n
\nclass DjangoTemplatesLink to this definition#
\n
\n\n

Set BACKEND to\n'django.template.backends.django.DjangoTemplates' to configure a Django\ntemplate engine.

\n

When APP_DIRS is True, DjangoTemplates\nengines look for templates in the templates subdirectory of installed\napplications. This generic name was kept for backwards-compatibility.

\n

DjangoTemplates engines accept the following OPTIONS:

\n\n
\n
\nclass Jinja2Link to this definition#
\n
\n\n

Requires Jinja2 to be installed:

\n
Shell
$ pip install Jinja2\n
\n

Set BACKEND to\n'django.template.backends.jinja2.Jinja2' to configure a Jinja2 engine.

\n

When APP_DIRS is True, Jinja2 engines\nlook for templates in the jinja2 subdirectory of installed applications.

\n

The most important entry in OPTIONS is\n'environment'. It’s a dotted Python path to a callable returning a Jinja2\nenvironment. It defaults to 'jinja2.Environment'. Django invokes that\ncallable and passes other options as keyword arguments. Furthermore, Django\nadds defaults that differ from Jinja2’s for a few options:

\n\n

Jinja2 engines also accept the following OPTIONS:

\n\n\n

The default configuration is purposefully kept to a minimum. If a template is\nrendered with a request (e.g. when using render()),\nthe Jinja2 backend adds the globals request, csrf_input, and\ncsrf_token to the context. Apart from that, this backend doesn’t create a\nDjango-flavored environment. It doesn’t know about Django filters and tags.\nIn order to use Django-specific APIs, you must configure them into the\nenvironment.

\n

For example, you can create myproject/jinja2.py with this content:

\n
Code
from django.contrib.staticfiles.storage import staticfiles_storage\nfrom django.urls import reverse\n\nfrom jinja2 import Environment\n\n\ndef environment(**options):\n    env = Environment(**options)\n    env.globals.update({\n        'static': staticfiles_storage.url,\n        'url': reverse,\n    })\n    return env\n
\n

and set the 'environment' option to 'myproject.jinja2.environment'.

\n

Then you could use the following constructs in Jinja2 templates:

\n
Html Jinja
<img src="{{ static('path/to/company-logo.png') }}" alt="Company Logo">\n\n<a href="{{ url('admin:index') }}">Administration</a>\n
\n

The concepts of tags and filters exist both in the Django template language\nand in Jinja2 but they’re used differently. Since Jinja2 supports passing\narguments to callables in templates, many features that require a template tag\nor filter in Django templates can be achieved simply by calling a function in\nJinja2 templates, as shown in the example above. Jinja2’s global namespace\nremoves the need for template context processors. The Django template language\ndoesn’t have an equivalent of Jinja2 tests.

\n
\n
\n

Custom backendsLink to this heading#

\n

Here’s how to implement a custom template backend in order to use another\ntemplate system. A template backend is a class that inherits\ndjango.template.backends.base.BaseEngine. It must implement\nget_template() and optionally from_string(). Here’s an example for a\nfictional foobar template library:

\n
Code
from django.template import TemplateDoesNotExist, TemplateSyntaxError\nfrom django.template.backends.base import BaseEngine\nfrom django.template.backends.utils import csrf_input_lazy, csrf_token_lazy\n\nimport foobar\n\n\nclass FooBar(BaseEngine):\n\n    # Name of the subdirectory containing the templates for this engine\n    # inside an installed application.\n    app_dirname = 'foobar'\n\n    def __init__(self, params):\n        params = params.copy()\n        options = params.pop('OPTIONS').copy()\n        super().__init__(params)\n\n        self.engine = foobar.Engine(**options)\n\n    def from_string(self, template_code):\n        try:\n          return Template(self.engine.from_string(template_code))\n        except foobar.TemplateCompilationFailed as exc:\n            raise TemplateSyntaxError(exc.args)\n\n    def get_template(self, template_name):\n        try:\n            return Template(self.engine.get_template(template_name))\n        except foobar.TemplateNotFound as exc:\n            raise TemplateDoesNotExist(exc.args, backend=self)\n        except foobar.TemplateCompilationFailed as exc:\n            raise TemplateSyntaxError(exc.args)\n\n\nclass Template:\n\n    def __init__(self, template):\n        self.template = template\n\n    def render(self, context=None, request=None):\n        if context is None:\n            context = {}\n        if request is not None:\n            context['request'] = request\n            context['csrf_input'] = csrf_input_lazy(request)\n            context['csrf_token'] = csrf_token_lazy(request)\n        return self.template.render(context)\n
\n

See DEP 182 for more information.

\n
\n
\n

Debug integration for custom enginesLink to this heading#

\n

The Django debug page has hooks to provide detailed information when a template\nerror arises. Custom template engines can use these hooks to enhance the\ntraceback information that appears to users. The following hooks are available:

\n
\n

Template postmortemLink to this heading#

\n

The postmortem appears when TemplateDoesNotExist is\nraised. It lists the template engines and loaders that were used when trying\nto find a given template. For example, if two Django engines are configured,\nthe postmortem will appear like:

\n\"/ko/2.0/_images/postmortem.png\"\n

Custom engines can populate the postmortem by passing the backend and\ntried arguments when raising TemplateDoesNotExist.\nBackends that use the postmortem should specify an origin on the template object.

\n
\n
\n

Contextual line informationLink to this heading#

\n

If an error happens during template parsing or rendering, Django can display\nthe line the error happened on. For example:

\n\"/ko/2.0/_images/template-lines.png\"\n

Custom engines can populate this information by setting a template_debug\nattribute on exceptions raised during parsing and rendering. This attribute\nis a dict with the following values:

\n
    \n

  • 'name': The name of the template in which the exception occurred.

    • \n

  • 'message': The exception message.

    • \n

  • 'source_lines': The lines before, after, and including the line the\nexception occurred on. This is for context, so it shouldn’t contain more than\n20 lines or so.

    • \n

  • 'line': The line number on which the exception occurred.

    • \n

  • 'before': The content on the error line before the token that raised the\nerror.

    • \n

  • 'during': The token that raised the error.

    • \n

  • 'after': The content on the error line after the token that raised the\nerror.

    • \n

  • 'total': The number of lines in source_lines.

    • \n

  • 'top': The line number where source_lines starts.

    • \n

  • 'bottom': The line number where source_lines ends.

    • \n
\n

Given the above template error, template_debug would look like:

\n
Code
{\n    'name': '/path/to/template.html',\n    'message': "Invalid block tag: 'syntax'",\n    'source_lines': [\n        (1, 'some\\n'),\n        (2, 'lines\\n'),\n        (3, 'before\\n'),\n        (4, 'Hello {% syntax error %} {{ world }}\\n'),\n        (5, 'some\\n'),\n        (6, 'lines\\n'),\n        (7, 'after\\n'),\n        (8, ''),\n    ],\n    'line': 4,\n    'before': 'Hello ',\n    'during': '{% syntax error %}',\n    'after': ' {{ world }}\\n',\n    'total': 9,\n    'bottom': 9,\n    'top': 1,\n}\n
\n
\n
\n

Origin API and 3rd-party integrationLink to this heading#

\n

Django templates have an Origin object available\nthrough the template.origin attribute. This enables debug information to be\ndisplayed in the template postmortem, as well as\nin 3rd-party libraries, like the Django Debug Toolbar.

\n

Custom engines can provide their own template.origin information by\ncreating an object that specifies the following attributes:

\n
    \n

  • 'name': The full path to the template.

    • \n

  • 'template_name': The relative path to the template as passed into the\nthe template loading methods.

    • \n

  • 'loader_name': An optional string identifying the function or class used\nto load the template, e.g. django.template.loaders.filesystem.Loader.

    • \n
\n
\n
\n
\n
\n

The Django template languageLink to this heading#

\n
\n

SyntaxLink to this heading#

\n\n

A Django template is simply a text document or a Python string marked-up using\nthe Django template language. Some constructs are recognized and interpreted\nby the template engine. The main ones are variables and tags.

\n

A template is rendered with a context. Rendering replaces variables with their\nvalues, which are looked up in the context, and executes tags. Everything else\nis output as is.

\n

The syntax of the Django template language involves four constructs.

\n
\n

VariablesLink to this heading#

\n

A variable outputs a value from the context, which is a dict-like object\nmapping keys to values.

\n

Variables are surrounded by {{ and }} like this:

\n
Django template
My first name is {{ first_name }}. My last name is {{ last_name }}.\n
\n

With a context of {'first_name': 'John', 'last_name': 'Doe'}, this\ntemplate renders to:

\n
Django template
My first name is John. My last name is Doe.\n
\n

Dictionary lookup, attribute lookup and list-index lookups are implemented\nwith a dot notation:

\n
Django template
{{ my_dict.key }}\n{{ my_object.attribute }}\n{{ my_list.0 }}\n
\n

If a variable resolves to a callable, the template system will call it with no\narguments and use its result instead of the callable.

\n
\n
\n

TagsLink to this heading#

\n

Tags provide arbitrary logic in the rendering process.

\n

This definition is deliberately vague. For example, a tag can output content,\nserve as a control structure e.g. an “if” statement or a “for” loop, grab\ncontent from a database, or even enable access to other template tags.

\n

Tags are surrounded by {% and %} like this:

\n
Django template
{% csrf_token %}\n
\n

Most tags accept arguments:

\n
Django template
{% cycle 'odd' 'even' %}\n
\n

Some tags require beginning and ending tags:

\n
Django template
{% if user.is_authenticated %}Hello, {{ user.username }}.{% endif %}\n
\n

A reference of built-in tags is\navailable as well as instructions for writing custom tags.

\n
\n
\n

FiltersLink to this heading#

\n

Filters transform the values of variables and tag arguments.

\n

They look like this:

\n
Django template
{{ django|title }}\n
\n

With a context of {'django': 'the web framework for perfectionists with\ndeadlines'}, this template renders to:

\n
Django template
The Web Framework For Perfectionists With Deadlines\n
\n

Some filters take an argument:

\n
Django template
{{ my_date|date:"Y-m-d" }}\n
\n

A reference of built-in filters is\navailable as well as instructions for writing custom filters.

\n
\n
\n

CommentsLink to this heading#

\n

Comments look like this:

\n
Django template
{# this won't be rendered #}\n
\n

A {% comment %} tag provides multi-line comments.

\n
\n
\n
\n

ComponentsLink to this heading#

\n\n
\n

EngineLink to this heading#

\n

django.template.Engine encapsulates an instance of the Django\ntemplate system. The main reason for instantiating an\nEngine directly is to use the Django template\nlanguage outside of a Django project.

\n

django.template.backends.django.DjangoTemplates is a thin wrapper\nadapting django.template.Engine to Django’s template backend API.

\n
\n
\n

TemplateLink to this heading#

\n

django.template.Template represents a compiled template.\nTemplates are obtained with Engine.get_template() or Engine.from_string()

\n

Likewise django.template.backends.django.Template is a thin wrapper\nadapting django.template.Template to the common template API.

\n
\n
\n

ContextLink to this heading#

\n

django.template.Context holds some metadata in addition to the\ncontext data. It is passed to Template.render() for rendering a template.

\n

django.template.RequestContext is a subclass of\nContext that stores the current\nHttpRequest and runs template context processors.

\n

The common API doesn’t have an equivalent concept. Context data is passed in a\nplain dict and the current HttpRequest is passed\nseparately if needed.

\n
\n
\n

LoadersLink to this heading#

\n

Template loaders are responsible for locating templates, loading them, and\nreturning Template objects.

\n

Django provides several built-in template loaders\nand supports custom template loaders.

\n
\n
\n

Context processorsLink to this heading#

\n

Context processors are functions that receive the current\nHttpRequest as an argument and return a dict of\ndata to be added to the rendering context.

\n

Their main use is to add common data shared by all templates to the context\nwithout repeating code in every view.

\n

Django provides many built-in context processors.\nImplementing a custom context processor is as simple as defining a function.

\n
\n
\n
","rootId":"module-django.template","toc":[{"title":"Support for template engines","anchor":"support-for-template-engines","children":[{"title":"Configuration","anchor":"configuration","children":[]},{"title":"Usage","anchor":"usage","children":[]},{"title":"Built-in backends","anchor":"module-django.template.backends.django","children":[]},{"title":"Custom backends","anchor":"custom-backends","children":[]},{"title":"Debug integration for custom engines","anchor":"debug-integration-for-custom-engines","children":[{"title":"Template postmortem","anchor":"template-postmortem","children":[]},{"title":"Contextual line information","anchor":"contextual-line-information","children":[]},{"title":"Origin API and 3rd-party integration","anchor":"origin-api-and-3rd-party-integration","children":[]}]}]},{"title":"The Django template language","anchor":"the-django-template-language","children":[{"title":"Syntax","anchor":"syntax","children":[{"title":"Variables","anchor":"variables","children":[]},{"title":"Tags","anchor":"tags","children":[]},{"title":"Filters","anchor":"filters","children":[]},{"title":"Comments","anchor":"comments","children":[]}]},{"title":"Components","anchor":"components","children":[{"title":"Engine","anchor":"engine","children":[]},{"title":"Template","anchor":"template","children":[]},{"title":"Context","anchor":"context","children":[]},{"title":"Loaders","anchor":"loaders","children":[]},{"title":"Context processors","anchor":"context-processors","children":[]}]}]}],"breadcrumbs":[{"docname":"topics/index","title":"Using Django","url":"/ko/2.0/topics/"}],"prev":{"docname":"topics/forms/media","title":"Form Assets (the Media class)","url":"/ko/2.0/topics/forms/media/"},"next":{"docname":"topics/class-based-views/index","title":"Class-based views","url":"/ko/2.0/topics/class-based-views/"},"formats":{"html":"/ko/2.0/topics/templates/","markdown":"/ko/2.0/topics/templates.md","json":"/ko/2.0/topics/templates.json"},"source":"https://github.com/django/django/blob/stable/2.0.x/docs/topics/templates.txt","official":"https://docs.djangoproject.com/ko/2.0/topics/templates/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11"],"inLocales":["en","zh-hans","fr","ja","id","pt-br","ko","es","el","pl"]}