diff options
Diffstat (limited to 'parts/django/docs/ref/templates')
| -rw-r--r-- | parts/django/docs/ref/templates/api.txt | 815 | ||||
| -rw-r--r-- | parts/django/docs/ref/templates/builtins.txt | 2107 | ||||
| -rw-r--r-- | parts/django/docs/ref/templates/index.txt | 19 |
3 files changed, 2941 insertions, 0 deletions
diff --git a/parts/django/docs/ref/templates/api.txt b/parts/django/docs/ref/templates/api.txt new file mode 100644 index 0000000..1111869 --- /dev/null +++ b/parts/django/docs/ref/templates/api.txt @@ -0,0 +1,815 @@ +==================================================== +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 **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`` + * Method call. 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." + + >>> class PersonClass2: + ... def first_name(self): + ... return "Samantha" + >>> p = PersonClass2() + >>> t.render(Context({"person": p})) + "My name is Samantha." + + >>> 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." + +Method lookups are slightly more complex than the other lookup types. Here are +some things to keep in mind: + + * If, during the method lookup, a method raises an exception, 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, 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 method call will only work if the method has no required arguments. + Otherwise, the system will move to the next lookup type (list-index + lookup). + + * Obviously, some methods have side effects, 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 a function attribute ``alters_data`` on the method. + The template system won't execute a method if the method has + ``alters_data=True`` set. 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 + +.. _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 +----------------------------------- + +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.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). + + * ``messages`` -- A list of messages (as strings) that have been set + via the :doc:`messages framework </ref/contrib/messages>`. + + * ``perms`` -- An instance of + ``django.core.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.2 + Prior to version 1.2, the ``messages`` variable was a lazy accessor for + ``user.get_and_delete_messages()``. It has been changed to include any + messages added via the :doc:`messages framework </ref/contrib/messages>`. + +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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 1.0 + +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.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. +Here are the template loaders that come with Django: + +``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. diff --git a/parts/django/docs/ref/templates/builtins.txt b/parts/django/docs/ref/templates/builtins.txt new file mode 100644 index 0000000..44bbc37 --- /dev/null +++ b/parts/django/docs/ref/templates/builtins.txt @@ -0,0 +1,2107 @@ +================================== +Built-in template tags and filters +================================== + +This document describes Django's built-in template tags and filters. It is +recommended that you use the :doc:`automatic documentation +</ref/contrib/admin/admindocs>`, if available, as this will also include +documentation for any custom tags or filters installed. + +.. _ref-templates-builtins-tags: + +Built-in tag reference +---------------------- + +.. highlightlang:: html+django + +.. templatetag:: autoescape + +autoescape +~~~~~~~~~~ + +.. versionadded:: 1.0 + +Control the current auto-escaping behavior. This tag takes either ``on`` or +``off`` as an argument and that determines whether auto-escaping is in effect +inside the block. The block is closed with an ``endautoescape`` ending tag. + +When auto-escaping is in effect, all variable content has HTML escaping applied +to it before placing the result into the output (but after any filters have +been applied). This is equivalent to manually applying the ``escape`` filter +to each variable. + +The only exceptions are variables that are already marked as "safe" from +escaping, either by the code that populated the variable, or because it has had +the ``safe`` or ``escape`` filters applied. + +Sample usage:: + + {% autoescape on %} + {{ body }} + {% endautoescape %} + +.. templatetag:: block + +block +~~~~~ + +Define a block that can be overridden by child templates. See +:ref:`Template inheritance <template-inheritance>` for more information. + +.. templatetag:: comment + +comment +~~~~~~~ + +Ignore everything between ``{% comment %}`` and ``{% endcomment %}`` + +.. templatetag:: csrf_token + +csrf_token +~~~~~~~~~~ + +.. versionadded:: 1.1.2 + +In the Django 1.1.X series, this is a no-op tag that returns an empty string for +future compatibility purposes. In Django 1.2 and later, it is used for CSRF +protection, as described in the documentation for :doc:`Cross Site Request +Forgeries </ref/contrib/csrf>`. + +.. templatetag:: cycle + +cycle +~~~~~ + +.. versionchanged:: 1.0 + Cycle among the given strings or variables each time this tag is encountered. + +Within a loop, cycles among the given strings each time through the +loop:: + + {% for o in some_list %} + <tr class="{% cycle 'row1' 'row2' %}"> + ... + </tr> + {% endfor %} + +You can use variables, too. For example, if you have two template variables, +``rowvalue1`` and ``rowvalue2``, you can cycle between their values like this:: + + {% for o in some_list %} + <tr class="{% cycle rowvalue1 rowvalue2 %}"> + ... + </tr> + {% endfor %} + +Yes, you can mix variables and strings:: + + {% for o in some_list %} + <tr class="{% cycle 'row1' rowvalue2 'row3' %}"> + ... + </tr> + {% endfor %} + +In some cases you might want to refer to the next value of a cycle from +outside of a loop. To do this, just give the ``{% cycle %}`` tag a name, using +"as", like this:: + + {% cycle 'row1' 'row2' as rowcolors %} + +From then on, you can insert the current value of the cycle wherever you'd like +in your template:: + + <tr class="{% cycle rowcolors %}">...</tr> + <tr class="{% cycle rowcolors %}">...</tr> + +You can use any number of values in a ``{% cycle %}`` tag, separated by spaces. +Values enclosed in single (``'``) or double quotes (``"``) are treated as +string literals, while values without quotes are treated as template variables. + +Note that the variables included in the cycle will not be escaped. +This is because template tags do not escape their content. Any HTML or +Javascript code contained in the printed variable will be rendered +as-is, which could potentially lead to security issues. + +If you need to escape the variables in the cycle, you must do so +explicitly:: + + {% filter force_escape %} + {% cycle var1 var2 var3 %} + {% endfilter %} + +For backwards compatibility, the ``{% cycle %}`` tag supports the much inferior +old syntax from previous Django versions. You shouldn't use this in any new +projects, but for the sake of the people who are still using it, here's what it +looks like:: + + {% cycle row1,row2,row3 %} + +In this syntax, each value gets interpreted as a literal string, and there's no +way to specify variable values. Or literal commas. Or spaces. Did we mention +you shouldn't use this syntax in any new projects? + +.. templatetag:: debug + +debug +~~~~~ + +Output a whole load of debugging information, including the current context and +imported modules. + +.. templatetag:: extends + +extends +~~~~~~~ + +Signal that this template extends a parent template. + +This tag can be used in two ways: + + * ``{% extends "base.html" %}`` (with quotes) uses the literal value + ``"base.html"`` as the name of the parent template to extend. + + * ``{% extends variable %}`` uses the value of ``variable``. If the variable + evaluates to a string, Django will use that string as the name of the + parent template. If the variable evaluates to a ``Template`` object, + Django will use that object as the parent template. + +See :ref:`template-inheritance` for more information. + +.. templatetag:: filter + +filter +~~~~~~ + +Filter the contents of the variable through variable filters. + +Filters can also be piped through each other, and they can have arguments -- +just like in variable syntax. + +Sample usage:: + + {% filter force_escape|lower %} + This text will be HTML-escaped, and will appear in all lowercase. + {% endfilter %} + +.. templatetag:: firstof + +firstof +~~~~~~~ + +Outputs the first variable passed that is not False, without escaping. + +Outputs nothing if all the passed variables are False. + +Sample usage:: + + {% firstof var1 var2 var3 %} + +This is equivalent to:: + + {% if var1 %} + {{ var1|safe }} + {% else %}{% if var2 %} + {{ var2|safe }} + {% else %}{% if var3 %} + {{ var3|safe }} + {% endif %}{% endif %}{% endif %} + +You can also use a literal string as a fallback value in case all +passed variables are False:: + + {% firstof var1 var2 var3 "fallback value" %} + +Note that the variables included in the firstof tag will not be +escaped. This is because template tags do not escape their content. +Any HTML or Javascript code contained in the printed variable will be +rendered as-is, which could potentially lead to security issues. + +If you need to escape the variables in the firstof tag, you must do so +explicitly:: + + {% filter force_escape %} + {% firstof var1 var2 var3 "fallback value" %} + {% endfilter %} + +.. templatetag:: for + +for +~~~ + +Loop over each item in an array. For example, to display a list of athletes +provided in ``athlete_list``:: + + <ul> + {% for athlete in athlete_list %} + <li>{{ athlete.name }}</li> + {% endfor %} + </ul> + +You can loop over a list in reverse by using ``{% for obj in list reversed %}``. + +.. versionadded:: 1.0 + +If you need to loop over a list of lists, you can unpack the values +in each sub-list into individual variables. For example, if your context +contains a list of (x,y) coordinates called ``points``, you could use the +following to output the list of points:: + + {% for x, y in points %} + There is a point at {{ x }},{{ y }} + {% endfor %} + +This can also be useful if you need to access the items in a dictionary. +For example, if your context contained a dictionary ``data``, the following +would display the keys and values of the dictionary:: + + {% for key, value in data.items %} + {{ key }}: {{ value }} + {% endfor %} + +The for loop sets a number of variables available within the loop: + + ========================== ================================================ + Variable Description + ========================== ================================================ + ``forloop.counter`` The current iteration of the loop (1-indexed) + ``forloop.counter0`` The current iteration of the loop (0-indexed) + ``forloop.revcounter`` The number of iterations from the end of the + loop (1-indexed) + ``forloop.revcounter0`` The number of iterations from the end of the + loop (0-indexed) + ``forloop.first`` True if this is the first time through the loop + ``forloop.last`` True if this is the last time through the loop + ``forloop.parentloop`` For nested loops, this is the loop "above" the + current one + ========================== ================================================ + +for ... empty +^^^^^^^^^^^^^ + +.. versionadded:: 1.1 + +The ``for`` tag can take an optional ``{% empty %}`` clause that will be +displayed if the given array is empty or could not be found:: + + <ul> + {% for athlete in athlete_list %} + <li>{{ athlete.name }}</li> + {% empty %} + <li>Sorry, no athlete in this list!</li> + {% endfor %} + <ul> + +The above is equivalent to -- but shorter, cleaner, and possibly faster +than -- the following:: + + <ul> + {% if athlete_list %} + {% for athlete in athlete_list %} + <li>{{ athlete.name }}</li> + {% endfor %} + {% else %} + <li>Sorry, no athletes in this list.</li> + {% endif %} + </ul> + +.. templatetag:: if + +if +~~ + +The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e. +exists, is not empty, and is not a false boolean value) the contents of the +block are output:: + + {% if athlete_list %} + Number of athletes: {{ athlete_list|length }} + {% else %} + No athletes. + {% endif %} + +In the above, if ``athlete_list`` is not empty, the number of athletes will be +displayed by the ``{{ athlete_list|length }}`` variable. + +As you can see, the ``if`` tag can take an optional ``{% else %}`` clause that +will be displayed if the test fails. + +Boolean operators +^^^^^^^^^^^^^^^^^ + +``if`` tags may use ``and``, ``or`` or ``not`` to test a number of variables or +to negate a given variable:: + + {% if athlete_list and coach_list %} + Both athletes and coaches are available. + {% endif %} + + {% if not athlete_list %} + There are no athletes. + {% endif %} + + {% if athlete_list or coach_list %} + There are some athletes or some coaches. + {% endif %} + + {% if not athlete_list or coach_list %} + There are no athletes or there are some coaches (OK, so + writing English translations of boolean logic sounds + stupid; it's not our fault). + {% endif %} + + {% if athlete_list and not coach_list %} + There are some athletes and absolutely no coaches. + {% endif %} + +.. versionchanged:: 1.2 + +Use of both ``and`` and ``or`` clauses within the same tag is allowed, with +``and`` having higher precedence than ``or`` e.g.:: + + {% if athlete_list and coach_list or cheerleader_list %} + +will be interpreted like: + +.. code-block:: python + + if (athlete_list and coach_list) or cheerleader_list + +Use of actual brackets in the ``if`` tag is invalid syntax. If you need them to +indicate precedence, you should use nested ``if`` tags. + +.. versionadded:: 1.2 + + +``if`` tags may also use the operators ``==``, ``!=``, ``<``, ``>``, +``<=``, ``>=`` and ``in`` which work as follows: + + +``==`` operator +^^^^^^^^^^^^^^^ + +Equality. Example:: + + {% if somevar == "x" %} + This appears if variable somevar equals the string "x" + {% endif %} + +``!=`` operator +^^^^^^^^^^^^^^^ + +Inequality. Example:: + + {% if somevar != "x" %} + This appears if variable somevar does not equal the string "x", + or if somevar is not found in the context + {% endif %} + +``<`` operator +^^^^^^^^^^^^^^ + +Less than. Example:: + + {% if somevar < 100 %} + This appears if variable somevar is less than 100. + {% endif %} + +``>`` operator +^^^^^^^^^^^^^^ + +Greater than. Example:: + + {% if somevar > 0 %} + This appears if variable somevar is greater than 0. + {% endif %} + +``<=`` operator +^^^^^^^^^^^^^^^ + +Less than or equal to. Example:: + + {% if somevar <= 100 %} + This appears if variable somevar is less than 100 or equal to 100. + {% endif %} + +``>=`` operator +^^^^^^^^^^^^^^^ + +Greater than or equal to. Example:: + + {% if somevar >= 1 %} + This appears if variable somevar is greater than 1 or equal to 1. + {% endif %} + +``in`` operator +^^^^^^^^^^^^^^^ + +Contained within. This operator is supported by many Python containers to test +whether the given value is in the container. The following are some examples of +how ``x in y`` will be interpreted:: + + {% if "bc" in "abcdef" %} + This appears since "bc" is a substring of "abcdef" + {% endif %} + + {% if "hello" in greetings %} + If greetings is a list or set, one element of which is the string + "hello", this will appear. + {% endif %} + + {% if user in users %} + If users is a QuerySet, this will appear if user is an + instance that belongs to the QuerySet. + {% endif %} + +``not in`` operator +~~~~~~~~~~~~~~~~~~~~ + +Not contained within. This is the negation of the ``in`` operator. + + +The comparison operators cannot be 'chained' like in Python or in mathematical +notation. For example, instead of using:: + + {% if a > b > c %} (WRONG) + +you should use:: + + {% if a > b and b > c %} + + +Filters +^^^^^^^ + +You can also use filters in the ``if`` expression. For example:: + + {% if messages|length >= 100 %} + You have lots of messages today! + {% endif %} + +Complex expressions +^^^^^^^^^^^^^^^^^^^ + +All of the above can be combined to form complex expressions. For such +expressions, it can be important to know how the operators are grouped when the +expression is evaluated - that is, the precedence rules. The precedence of the +operators, from lowest to highest, is as follows: + + * ``or`` + * ``and`` + * ``not`` + * ``in`` + * ``==``, ``!=``, ``<``, ``>``,``<=``, ``>=`` + +(This follows Python exactly). So, for example, the following complex if tag: + + {% if a == b or c == d and e %} + +...will be interpreted as: + +.. code-block:: python + + (a == b) or ((c == d) and e) + +If you need different precedence, you will need to use nested if tags. Sometimes +that is better for clarity anyway, for the sake of those who do not know the +precedence rules. + + +.. templatetag:: ifchanged + +ifchanged +~~~~~~~~~ + +Check if a value has changed from the last iteration of a loop. + +The 'ifchanged' block tag is used within a loop. It has two possible uses. + +1. Checks its own rendered contents against its previous state and only + displays the content if it has changed. For example, this displays a list of + days, only displaying the month if it changes:: + + <h1>Archive for {{ year }}</h1> + + {% for date in days %} + {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %} + <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a> + {% endfor %} + +2. If given a variable, check whether that variable has changed. For + example, the following shows the date every time it changes, but + only shows the hour if both the hour and the date has changed:: + + {% for date in days %} + {% ifchanged date.date %} {{ date.date }} {% endifchanged %} + {% ifchanged date.hour date.date %} + {{ date.hour }} + {% endifchanged %} + {% endfor %} + +The ``ifchanged`` tag can also take an optional ``{% else %}`` clause that +will be displayed if the value has not changed:: + + {% for match in matches %} + <div style="background-color: + {% ifchanged match.ballot_id %} + {% cycle "red" "blue" %} + {% else %} + grey + {% endifchanged %} + ">{{ match }}</div> + {% endfor %} + +.. templatetag:: ifequal + +ifequal +~~~~~~~ + +Output the contents of the block if the two arguments equal each other. + +Example:: + + {% ifequal user.id comment.user_id %} + ... + {% endifequal %} + +As in the ``{% if %}`` tag, an ``{% else %}`` clause is optional. + +The arguments can be hard-coded strings, so the following is valid:: + + {% ifequal user.username "adrian" %} + ... + {% endifequal %} + +It is only possible to compare an argument to template variables or strings. +You cannot check for equality with Python objects such as ``True`` or +``False``. If you need to test if something is true or false, use the ``if`` +tag instead. + +.. versionadded:: 1.2 + An alternative to the ``ifequal`` tag is to use the :ttag:`if` tag and the ``==`` operator. + +.. templatetag:: ifnotequal + +ifnotequal +~~~~~~~~~~ + +Just like ``ifequal``, except it tests that the two arguments are not equal. + +.. versionadded:: 1.2 + An alternative to the ``ifnotequal`` tag is to use the :ttag:`if` tag and the ``!=`` operator. + +.. templatetag:: include + +include +~~~~~~~ + +Loads a template and renders it with the current context. This is a way of +"including" other templates within a template. + +The template name can either be a variable or a hard-coded (quoted) string, +in either single or double quotes. + +This example includes the contents of the template ``"foo/bar.html"``:: + + {% include "foo/bar.html" %} + +This example includes the contents of the template whose name is contained in +the variable ``template_name``:: + + {% include template_name %} + +An included template is rendered with the context of the template that's +including it. This example produces the output ``"Hello, John"``: + + * Context: variable ``person`` is set to ``"john"``. + * Template:: + + {% include "name_snippet.html" %} + + * The ``name_snippet.html`` template:: + + Hello, {{ person }} + +See also: ``{% ssi %}``. + +.. note:: + The :ttag:`include` tag should be considered as an implementation of + "render this subtemplate and include the HTML", not as "parse this + subtemplate and include its contents as if it were part of the parent". + This means that there is no shared state between included templates -- + each include is a completely independent rendering process. + +.. templatetag:: load + +load +~~~~ + +Load a custom template tag set. + +See :doc:`Custom tag and filter libraries </howto/custom-template-tags>` for more information. + +.. templatetag:: now + +now +~~~ + +Display the current date and/or time, according to the given string. + +Given format can be one of the predefined ones ``DATE_FORMAT``, +``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``, +or a custom format, same as the :tfilter:`date` filter. Note that predefined +formats may vary depending on the current locale. + +Example:: + + It is {% now "jS F Y H:i" %} + +Note that you can backslash-escape a format string if you want to use the +"raw" value. In this example, "f" is backslash-escaped, because otherwise +"f" is a format string that displays the time. The "o" doesn't need to be +escaped, because it's not a format character:: + + It is the {% now "jS o\f F" %} + +This would display as "It is the 4th of September". + +.. templatetag:: regroup + +regroup +~~~~~~~ + +Regroup a list of alike objects by a common attribute. + +This complex tag is best illustrated by use of an example: say that ``people`` +is a list of people represented by dictionaries with ``first_name``, +``last_name``, and ``gender`` keys: + +.. code-block:: python + + people = [ + {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'}, + {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'}, + {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'}, + {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'}, + {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'}, + ] + +...and you'd like to display a hierarchical list that is ordered by gender, +like this: + + * Male: + * George Bush + * Bill Clinton + * Female: + * Margaret Thatcher + * Condoleezza Rice + * Unknown: + * Pat Smith + +You can use the ``{% regroup %}`` tag to group the list of people by gender. +The following snippet of template code would accomplish this:: + + {% regroup people by gender as gender_list %} + + <ul> + {% for gender in gender_list %} + <li>{{ gender.grouper }} + <ul> + {% for item in gender.list %} + <li>{{ item.first_name }} {{ item.last_name }}</li> + {% endfor %} + </ul> + </li> + {% endfor %} + </ul> + +Let's walk through this example. ``{% regroup %}`` takes three arguments: the +list you want to regroup, the attribute to group by, and the name of the +resulting list. Here, we're regrouping the ``people`` list by the ``gender`` +attribute and calling the result ``gender_list``. + +``{% regroup %}`` produces a list (in this case, ``gender_list``) of +**group objects**. Each group object has two attributes: + + * ``grouper`` -- the item that was grouped by (e.g., the string "Male" or + "Female"). + * ``list`` -- a list of all items in this group (e.g., a list of all people + with gender='Male'). + +Note that ``{% regroup %}`` does not order its input! Our example relies on +the fact that the ``people`` list was ordered by ``gender`` in the first place. +If the ``people`` list did *not* order its members by ``gender``, the regrouping +would naively display more than one group for a single gender. For example, +say the ``people`` list was set to this (note that the males are not grouped +together): + +.. code-block:: python + + people = [ + {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'}, + {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'}, + {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'}, + {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'}, + {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'}, + ] + +With this input for ``people``, the example ``{% regroup %}`` template code +above would result in the following output: + + * Male: + * Bill Clinton + * Unknown: + * Pat Smith + * Female: + * Margaret Thatcher + * Male: + * George Bush + * Female: + * Condoleezza Rice + +The easiest solution to this gotcha is to make sure in your view code that the +data is ordered according to how you want to display it. + +Another solution is to sort the data in the template using the ``dictsort`` +filter, if your data is in a list of dictionaries:: + + {% regroup people|dictsort:"gender" by gender as gender_list %} + +.. templatetag:: spaceless + +spaceless +~~~~~~~~~ + +Removes whitespace between HTML tags. This includes tab +characters and newlines. + +Example usage:: + + {% spaceless %} + <p> + <a href="foo/">Foo</a> + </p> + {% endspaceless %} + +This example would return this HTML:: + + <p><a href="foo/">Foo</a></p> + +Only space between *tags* is removed -- not space between tags and text. In +this example, the space around ``Hello`` won't be stripped:: + + {% spaceless %} + <strong> + Hello + </strong> + {% endspaceless %} + +.. templatetag:: ssi + +ssi +~~~ + +Output the contents of a given file into the page. + +Like a simple "include" tag, ``{% ssi %}`` includes the contents of another +file -- which must be specified using an absolute path -- in the current +page:: + + {% ssi /home/html/ljworld.com/includes/right_generic.html %} + +If the optional "parsed" parameter is given, the contents of the included +file are evaluated as template code, within the current context:: + + {% ssi /home/html/ljworld.com/includes/right_generic.html parsed %} + +Note that if you use ``{% ssi %}``, you'll need to define +:setting:`ALLOWED_INCLUDE_ROOTS` in your Django settings, as a security measure. + +See also: ``{% include %}``. + +.. templatetag:: templatetag + +templatetag +~~~~~~~~~~~ + +Output one of the syntax characters used to compose template tags. + +Since the template system has no concept of "escaping", to display one of the +bits used in template tags, you must use the ``{% templatetag %}`` tag. + +The argument tells which template bit to output: + + ================== ======= + Argument Outputs + ================== ======= + ``openblock`` ``{%`` + ``closeblock`` ``%}`` + ``openvariable`` ``{{`` + ``closevariable`` ``}}`` + ``openbrace`` ``{`` + ``closebrace`` ``}`` + ``opencomment`` ``{#`` + ``closecomment`` ``#}`` + ================== ======= + +.. templatetag:: url + +url +~~~ + +Returns an absolute path reference (a URL without the domain name) matching a +given view function and optional parameters. This is a way to output links +without violating the DRY principle by having to hard-code URLs in your +templates:: + + {% url path.to.some_view v1 v2 %} + +The first argument is a path to a view function in the format +``package.package.module.function``. Additional arguments are optional and +should be space-separated values that will be used as arguments in the URL. +The example above shows passing positional arguments. Alternatively you may +use keyword syntax:: + + {% url path.to.some_view arg1=v1 arg2=v2 %} + +Do not mix both positional and keyword syntax in a single call. All arguments +required by the URLconf should be present. + +For example, suppose you have a view, ``app_views.client``, whose URLconf +takes a client ID (here, ``client()`` is a method inside the views file +``app_views.py``). The URLconf line might look like this: + +.. code-block:: python + + ('^client/(\d+)/$', 'app_views.client') + +If this app's URLconf is included into the project's URLconf under a path +such as this: + +.. code-block:: python + + ('^clients/', include('project_name.app_name.urls')) + +...then, in a template, you can create a link to this view like this:: + + {% url app_views.client client.id %} + +The template tag will output the string ``/clients/client/123/``. + +.. versionadded:: 1.0 + +If you're using :ref:`named URL patterns <naming-url-patterns>`, you can +refer to the name of the pattern in the ``url`` tag instead of using the +path to the view. + +Note that if the URL you're reversing doesn't exist, you'll get an +:exc:`NoReverseMatch` exception raised, which will cause your site to display an +error page. + +.. versionadded:: 1.0 + +If you'd like to retrieve a URL without displaying it, you can use a slightly +different call:: + + + {% url path.to.view arg arg2 as the_url %} + + <a href="{{ the_url }}">I'm linking to {{ the_url }}</a> + +This ``{% url ... as var %}`` syntax will *not* cause an error if the view is +missing. In practice you'll use this to link to views that are optional:: + + {% url path.to.view as the_url %} + {% if the_url %} + <a href="{{ the_url }}">Link to optional stuff</a> + {% endif %} + +.. versionadded:: 1.1 + +If you'd like to retrieve a namespaced URL, specify the fully qualified name:: + + {% url myapp:view-name %} + +This will follow the normal :ref:`namespaced URL resolution strategy +<topics-http-reversing-url-namespaces>`, including using any hints provided +by the context as to the current application. + +.. versionchanged:: 1.2 + +For backwards compatibility, the ``{% url %}`` tag also supports the +use of commas to separate arguments. You shouldn't use this in any new +projects, but for the sake of the people who are still using it, +here's what it looks like:: + + {% url path.to.view arg,arg2 %} + {% url path.to.view arg, arg2 %} + +This syntax doesn't support the use of literal commas, or or equals +signs. Did we mention you shouldn't use this syntax in any new +projects? + +.. templatetag:: widthratio + +widthratio +~~~~~~~~~~ + +For creating bar charts and such, this tag calculates the ratio of a given value +to a maximum value, and then applies that ratio to a constant. + +For example:: + + <img src="bar.gif" height="10" width="{% widthratio this_value max_value 100 %}" /> + +Above, if ``this_value`` is 175 and ``max_value`` is 200, the image in the +above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5 +which is rounded up to 88). + +.. templatetag:: with + +with +~~~~ + +.. versionadded:: 1.0 + +Caches a complex variable under a simpler name. This is useful when accessing +an "expensive" method (e.g., one that hits the database) multiple times. + +For example:: + + {% with business.employees.count as total %} + {{ total }} employee{{ total|pluralize }} + {% endwith %} + +The populated variable (in the example above, ``total``) is only available +between the ``{% with %}`` and ``{% endwith %}`` tags. + +.. _ref-templates-builtins-filters: + +Built-in filter reference +------------------------- + +.. templatefilter:: add + +add +~~~ + +Adds the argument to the value. + +For example:: + + {{ value|add:"2" }} + +If ``value`` is ``4``, then the output will be ``6``. + +.. versionchanged:: 1.2 + The following behavior didn't exist in previous Django versions. + +This filter will first try to coerce both values to integers. If this fails, +it'll attempt to add the values together anyway. This will work on some data +types (strings, list, etc.) and fail on others. If it fails, the result will +be an empty string. + +For example, if we have:: + + {{ first|add:second }} + +and ``first`` is ``[1, 2, 3]`` and ``second`` is ``[4, 5, 6]``, then the +output will be ``[1, 2, 3, 4, 5, 6]``. + +.. warning:: + + Strings that can be coerced to integers will be **summed**, not + concatenated, as in the first example above. + +.. templatefilter:: addslashes + +addslashes +~~~~~~~~~~ + +Adds slashes before quotes. Useful for escaping strings in CSV, for example. + +For example:: + + {{ value|addslashes }} + +If ``value`` is ``"I'm using Django"``, the output will be ``"I\'m using Django"``. + +.. templatefilter:: capfirst + +capfirst +~~~~~~~~ + +Capitalizes the first character of the value. + +For example:: + + {{ value|capfirst }} + +If ``value`` is ``"django"``, the output will be ``"Django"``. + +.. templatefilter:: center + +center +~~~~~~ + +Centers the value in a field of a given width. + +For example:: + + "{{ value|center:"15" }}" + +If ``value`` is ``"Django"``, the output will be ``" Django "``. + +.. templatefilter:: cut + +cut +~~~ + +Removes all values of arg from the given string. + +For example:: + + {{ value|cut:" "}} + +If ``value`` is ``"String with spaces"``, the output will be ``"Stringwithspaces"``. + +.. templatefilter:: date + +date +~~~~ + +Formats a date according to the given format. + +Uses the same format as PHP's ``date()`` function (http://php.net/date) +with some custom extensions. + +Available format strings: + + ================ ======================================== ===================== + Format character Description Example output + ================ ======================================== ===================== + a ``'a.m.'`` or ``'p.m.'`` (Note that ``'a.m.'`` + this is slightly different than PHP's + output, because this includes periods + to match Associated Press style.) + A ``'AM'`` or ``'PM'``. ``'AM'`` + b Month, textual, 3 letters, lowercase. ``'jan'`` + B Not implemented. + c ISO 8601 Format. ``2008-01-02T10:30:00.000123`` + d Day of the month, 2 digits with ``'01'`` to ``'31'`` + leading zeros. + D Day of the week, textual, 3 letters. ``'Fri'`` + f Time, in 12-hour hours and minutes, ``'1'``, ``'1:30'`` + with minutes left off if they're zero. + Proprietary extension. + F Month, textual, long. ``'January'`` + g Hour, 12-hour format without leading ``'1'`` to ``'12'`` + zeros. + G Hour, 24-hour format without leading ``'0'`` to ``'23'`` + zeros. + h Hour, 12-hour format. ``'01'`` to ``'12'`` + H Hour, 24-hour format. ``'00'`` to ``'23'`` + i Minutes. ``'00'`` to ``'59'`` + I Not implemented. + j Day of the month without leading ``'1'`` to ``'31'`` + zeros. + l Day of the week, textual, long. ``'Friday'`` + L Boolean for whether it's a leap year. ``True`` or ``False`` + m Month, 2 digits with leading zeros. ``'01'`` to ``'12'`` + M Month, textual, 3 letters. ``'Jan'`` + n Month without leading zeros. ``'1'`` to ``'12'`` + N Month abbreviation in Associated Press ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'`` + style. Proprietary extension. + O Difference to Greenwich time in hours. ``'+0200'`` + P Time, in 12-hour hours, minutes and ``'1 a.m.'``, ``'1:30 p.m.'``, ``'midnight'``, ``'noon'``, ``'12:30 p.m.'`` + 'a.m.'/'p.m.', with minutes left off + if they're zero and the special-case + strings 'midnight' and 'noon' if + appropriate. Proprietary extension. + r RFC 2822 formatted date. ``'Thu, 21 Dec 2000 16:01:07 +0200'`` + s Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'`` + S English ordinal suffix for day of the ``'st'``, ``'nd'``, ``'rd'`` or ``'th'`` + month, 2 characters. + t Number of days in the given month. ``28`` to ``31`` + T Time zone of this machine. ``'EST'``, ``'MDT'`` + u Microseconds. ``0`` to ``999999`` + U Seconds since the Unix Epoch + (January 1 1970 00:00:00 UTC). + w Day of the week, digits without ``'0'`` (Sunday) to ``'6'`` (Saturday) + leading zeros. + W ISO-8601 week number of year, with ``1``, ``53`` + weeks starting on Monday. + y Year, 2 digits. ``'99'`` + Y Year, 4 digits. ``'1999'`` + z Day of the year. ``0`` to ``365`` + Z Time zone offset in seconds. The ``-43200`` to ``43200`` + offset for timezones west of UTC is + always negative, and for those east of + UTC is always positive. + ================ ======================================== ===================== + +.. versionadded:: 1.2 + +The ``c`` and ``u`` format specification characters were added in Django 1.2. + +For example:: + + {{ value|date:"D d M Y" }} + +If ``value`` is a ``datetime`` object (e.g., the result of +``datetime.datetime.now()``), the output will be the string +``'Wed 09 Jan 2008'``. + +The format passed can be one of the predefined ones ``DATE_FORMAT``, +``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``, or a +custom format that uses the format specifiers shown in the table above. Note +that predefined formats may vary depending on the current locale. + +Assuming that :setting:`USE_L10N` is ``True`` and :setting:`LANGUAGE_CODE` is, +for example, ``"es"``, then for:: + + {{ value|date:"SHORT_DATE_FORMAT" }} + +the output would be the string ``"09/01/2008"`` (the ``"SHORT_DATE_FORMAT"`` +format specifier for the ``es`` locale as shipped with Django is ``"d/m/Y"``). + +When used without a format string:: + + {{ value|date }} + +...the formatting string defined in the :setting:`DATE_FORMAT` setting will be +used, without applying any localization. + +.. versionchanged:: 1.2 + Predefined formats can now be influenced by the current locale. + +.. templatefilter:: default + +default +~~~~~~~ + +If value evaluates to ``False``, use given default. Otherwise, use the value. + +For example:: + + {{ value|default:"nothing" }} + +If ``value`` is ``""`` (the empty string), the output will be ``nothing``. + +.. templatefilter:: default_if_none + +default_if_none +~~~~~~~~~~~~~~~ + +If (and only if) value is ``None``, use given default. Otherwise, use the +value. + +Note that if an empty string is given, the default value will *not* be used. +Use the ``default`` filter if you want to fallback for empty strings. + +For example:: + + {{ value|default_if_none:"nothing" }} + +If ``value`` is ``None``, the output will be the string ``"nothing"``. + +.. templatefilter:: dictsort + +dictsort +~~~~~~~~ + +Takes a list of dictionaries and returns that list sorted by the key given in +the argument. + +For example:: + + {{ value|dictsort:"name" }} + +If ``value`` is: + +.. code-block:: python + + [ + {'name': 'zed', 'age': 19}, + {'name': 'amy', 'age': 22}, + {'name': 'joe', 'age': 31}, + ] + +then the output would be: + +.. code-block:: python + + [ + {'name': 'amy', 'age': 22}, + {'name': 'joe', 'age': 31}, + {'name': 'zed', 'age': 19}, + ] + +.. templatefilter:: dictsortreversed + +dictsortreversed +~~~~~~~~~~~~~~~~ + +Takes a list of dictionaries and returns that list sorted in reverse order by +the key given in the argument. This works exactly the same as the above filter, +but the returned value will be in reverse order. + +.. templatefilter:: divisibleby + +divisibleby +~~~~~~~~~~~ + +Returns ``True`` if the value is divisible by the argument. + +For example:: + + {{ value|divisibleby:"3" }} + +If ``value`` is ``21``, the output would be ``True``. + +.. templatefilter:: escape + +escape +~~~~~~ + +Escapes a string's HTML. Specifically, it makes these replacements: + + * ``<`` is converted to ``<`` + * ``>`` is converted to ``>`` + * ``'`` (single quote) is converted to ``'`` + * ``"`` (double quote) is converted to ``"`` + * ``&`` is converted to ``&`` + +The escaping is only applied when the string is output, so it does not matter +where in a chained sequence of filters you put ``escape``: it will always be +applied as though it were the last filter. If you want escaping to be applied +immediately, use the ``force_escape`` filter. + +Applying ``escape`` to a variable that would normally have auto-escaping +applied to the result will only result in one round of escaping being done. So +it is safe to use this function even in auto-escaping environments. If you want +multiple escaping passes to be applied, use the ``force_escape`` filter. + +.. versionchanged:: 1.0 + Due to auto-escaping, the behavior of this filter has changed slightly. + The replacements are only made once, after + all other filters are applied -- including filters before and after it. + +.. templatefilter:: escapejs + +escapejs +~~~~~~~~ + +.. versionadded:: 1.0 + +Escapes characters for use in JavaScript strings. This does *not* make the +string safe for use in HTML, but does protect you from syntax errors when using +templates to generate JavaScript/JSON. + +For example:: + + {{ value|escapejs }} + +If ``value`` is ``"testing\r\njavascript \'string" <b>escaping</b>"``, +the output will be ``"testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u003Cb\\u003Eescaping\\u003C/b\\u003E"``. + +.. templatefilter:: filesizeformat + +filesizeformat +~~~~~~~~~~~~~~ + +Format the value like a 'human-readable' file size (i.e. ``'13 KB'``, +``'4.1 MB'``, ``'102 bytes'``, etc). + +For example:: + + {{ value|filesizeformat }} + +If ``value`` is 123456789, the output would be ``117.7 MB``. + +.. templatefilter:: first + +first +~~~~~ + +Returns the first item in a list. + +For example:: + + {{ value|first }} + +If ``value`` is the list ``['a', 'b', 'c']``, the output will be ``'a'``. + +.. templatefilter:: fix_ampersands + +fix_ampersands +~~~~~~~~~~~~~~ + +.. versionchanged:: 1.0 + This is rarely useful as ampersands are now automatically escaped. See escape_ for more information. + +Replaces ampersands with ``&`` entities. + +For example:: + + {{ value|fix_ampersands }} + +If ``value`` is ``Tom & Jerry``, the output will be ``Tom & Jerry``. + +.. templatefilter:: floatformat + +floatformat +~~~~~~~~~~~ + +When used without an argument, rounds a floating-point number to one decimal +place -- but only if there's a decimal part to be displayed. For example: + +============ =========================== ======== +``value`` Template Output +============ =========================== ======== +``34.23234`` ``{{ value|floatformat }}`` ``34.2`` +``34.00000`` ``{{ value|floatformat }}`` ``34`` +``34.26000`` ``{{ value|floatformat }}`` ``34.3`` +============ =========================== ======== + +If used with a numeric integer argument, ``floatformat`` rounds a number to +that many decimal places. For example: + +============ ============================= ========== +``value`` Template Output +============ ============================= ========== +``34.23234`` ``{{ value|floatformat:3 }}`` ``34.232`` +``34.00000`` ``{{ value|floatformat:3 }}`` ``34.000`` +``34.26000`` ``{{ value|floatformat:3 }}`` ``34.260`` +============ ============================= ========== + +If the argument passed to ``floatformat`` is negative, it will round a number +to that many decimal places -- but only if there's a decimal part to be +displayed. For example: + +============ ================================ ========== +``value`` Template Output +============ ================================ ========== +``34.23234`` ``{{ value|floatformat:"-3" }}`` ``34.232`` +``34.00000`` ``{{ value|floatformat:"-3" }}`` ``34`` +``34.26000`` ``{{ value|floatformat:"-3" }}`` ``34.260`` +============ ================================ ========== + +Using ``floatformat`` with no argument is equivalent to using ``floatformat`` +with an argument of ``-1``. + +.. templatefilter:: force_escape + +force_escape +~~~~~~~~~~~~ + +.. versionadded:: 1.0 + +Applies HTML escaping to a string (see the ``escape`` filter for details). +This filter is applied *immediately* and returns a new, escaped string. This +is useful in the rare cases where you need multiple escaping or want to apply +other filters to the escaped results. Normally, you want to use the ``escape`` +filter. + +.. templatefilter:: get_digit + +get_digit +~~~~~~~~~ + +Given a whole number, returns the requested digit, where 1 is the right-most +digit, 2 is the second-right-most digit, etc. Returns the original value for +invalid input (if input or argument is not an integer, or if argument is less +than 1). Otherwise, output is always an integer. + +For example:: + + {{ value|get_digit:"2" }} + +If ``value`` is ``123456789``, the output will be ``8``. + +.. templatefilter:: iriencode + +iriencode +~~~~~~~~~ + +Converts an IRI (Internationalized Resource Identifier) to a string that is +suitable for including in a URL. This is necessary if you're trying to use +strings containing non-ASCII characters in a URL. + +It's safe to use this filter on a string that has already gone through the +``urlencode`` filter. + +For example:: + + {{ value|iriencode }} + +If ``value`` is ``"?test=1&me=2"``, the output will be ``"?test=1&me=2"``. + +.. templatefilter:: join + +join +~~~~ + +Joins a list with a string, like Python's ``str.join(list)`` + +For example:: + + {{ value|join:" // " }} + +If ``value`` is the list ``['a', 'b', 'c']``, the output will be the string +``"a // b // c"``. + +.. templatefilter:: last + +last +~~~~ + +.. versionadded:: 1.0 + +Returns the last item in a list. + +For example:: + + {{ value|last }} + +If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output will be the string +``"d"``. + +.. templatefilter:: length + +length +~~~~~~ + +Returns the length of the value. This works for both strings and lists. + +For example:: + + {{ value|length }} + +If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``4``. + +.. templatefilter:: length_is + +length_is +~~~~~~~~~ + +Returns ``True`` if the value's length is the argument, or ``False`` otherwise. + +For example:: + + {{ value|length_is:"4" }} + +If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``True``. + +.. templatefilter:: linebreaks + +linebreaks +~~~~~~~~~~ + +Replaces line breaks in plain text with appropriate HTML; a single +newline becomes an HTML line break (``<br />``) and a new line +followed by a blank line becomes a paragraph break (``</p>``). + +For example:: + + {{ value|linebreaks }} + +If ``value`` is ``Joel\nis a slug``, the output will be ``<p>Joel<br />is a +slug</p>``. + +.. templatefilter:: linebreaksbr + +linebreaksbr +~~~~~~~~~~~~ + +Converts all newlines in a piece of plain text to HTML line breaks +(``<br />``). + +For example:: + + {{ value|linebreaksbr }} + +If ``value`` is ``Joel\nis a slug``, the output will be ``Joel<br />is a +slug``. + +.. templatefilter:: linenumbers + +linenumbers +~~~~~~~~~~~ + +Displays text with line numbers. + +For example:: + + {{ value|linenumbers }} + +If ``value`` is:: + + one + two + three + +the output will be:: + + 1. one + 2. two + 3. three + +.. templatefilter:: ljust + +ljust +~~~~~ + +Left-aligns the value in a field of a given width. + +**Argument:** field size + +For example:: + + "{{ value|ljust:"10" }}" + +If ``value`` is ``Django``, the output will be ``"Django "``. + +.. templatefilter:: lower + +lower +~~~~~ + +Converts a string into all lowercase. + +For example:: + + {{ value|lower }} + +If ``value`` is ``Still MAD At Yoko``, the output will be ``still mad at yoko``. + +.. templatefilter:: make_list + +make_list +~~~~~~~~~ + +Returns the value turned into a list. For an integer, it's a list of +digits. For a string, it's a list of characters. + +For example:: + + {{ value|make_list }} + +If ``value`` is the string ``"Joel"``, the output would be the list +``[u'J', u'o', u'e', u'l']``. If ``value`` is ``123``, the output will be the +list ``[1, 2, 3]``. + +.. templatefilter:: phone2numeric + +phone2numeric +~~~~~~~~~~~~~ + +Converts a phone number (possibly containing letters) to its numerical +equivalent. + +The input doesn't have to be a valid phone number. This will happily convert +any string. + +For example:: + + {{ value|phone2numeric }} + +If ``value`` is ``800-COLLECT``, the output will be ``800-2655328``. + +.. templatefilter:: pluralize + +pluralize +~~~~~~~~~ + +Returns a plural suffix if the value is not 1. By default, this suffix is ``'s'``. + +Example:: + + You have {{ num_messages }} message{{ num_messages|pluralize }}. + +If ``num_messages`` is ``1``, the output will be ``You have 1 message.`` +If ``num_messages`` is ``2`` the output will be ``You have 2 messages.`` + +For words that require a suffix other than ``'s'``, you can provide an alternate +suffix as a parameter to the filter. + +Example:: + + You have {{ num_walruses }} walrus{{ num_walruses|pluralize:"es" }}. + +For words that don't pluralize by simple suffix, you can specify both a +singular and plural suffix, separated by a comma. + +Example:: + + You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}. + +.. templatefilter:: pprint + +pprint +~~~~~~ + +A wrapper around `pprint.pprint`__ -- for debugging, really. + +__ http://docs.python.org/library/pprint.html + +.. templatefilter:: random + +random +~~~~~~ + +Returns a random item from the given list. + +For example:: + + {{ value|random }} + +If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output could be ``"b"``. + +.. templatefilter:: removetags + +removetags +~~~~~~~~~~ + +Removes a space-separated list of [X]HTML tags from the output. + +For example:: + + {{ value|removetags:"b span"|safe }} + +If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"`` the +output will be ``"Joel <button>is</button> a slug"``. + +Note that this filter is case-sensitive. + +If ``value`` is ``"<B>Joel</B> <button>is</button> a <span>slug</span>"`` the +output will be ``"<B>Joel</B> <button>is</button> a slug"``. + +.. templatefilter:: rjust + +rjust +~~~~~ + +Right-aligns the value in a field of a given width. + +**Argument:** field size + +For example:: + + "{{ value|rjust:"10" }}" + +If ``value`` is ``Django``, the output will be ``" Django"``. + +.. templatefilter:: safe + +safe +~~~~ + +Marks a string as not requiring further HTML escaping prior to output. When +autoescaping is off, this filter has no effect. + +.. note:: + + If you are chaining filters, a filter applied after ``safe`` can + make the contents unsafe again. For example, the following code + prints the variable as is, unescaped: + + .. code-block:: html+django + + {{ var|safe|escape }} + +.. templatefilter:: safeseq + +safeseq +~~~~~~~ + +Applies the :tfilter:`safe` filter to each element of a sequence. Useful in +conjunction with other filters that operate on sequences, such as +:tfilter:`join`. For example:: + + {{ some_list|safeseq|join:", " }} + +You couldn't use the :tfilter:`safe` filter directly in this case, as it would +first convert the variable into a string, rather than working with the +individual elements of the sequence. + +.. templatefilter:: slice + +slice +~~~~~ + +Returns a slice of the list. + +Uses the same syntax as Python's list slicing. See +http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice +for an introduction. + +Example:: + + {{ some_list|slice:":2" }} + +If ``some_list`` is ``['a', 'b', 'c']``, the output will be ``['a', 'b']``. + +.. templatefilter:: slugify + +slugify +~~~~~~~ + +Converts to lowercase, removes non-word characters (alphanumerics and +underscores) and converts spaces to hyphens. Also strips leading and trailing +whitespace. + +For example:: + + {{ value|slugify }} + +If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``. + +.. templatefilter:: stringformat + +stringformat +~~~~~~~~~~~~ + +Formats the variable according to the argument, a string formatting specifier. +This specifier uses Python string formatting syntax, with the exception that +the leading "%" is dropped. + +See http://docs.python.org/library/stdtypes.html#string-formatting-operations +for documentation of Python string formatting + +For example:: + + {{ value|stringformat:"s" }} + +If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is a slug"``. + +.. templatefilter:: striptags + +striptags +~~~~~~~~~ + +Strips all [X]HTML tags. + +For example:: + + {{ value|striptags }} + +If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"``, the +output will be ``"Joel is a slug"``. + +.. templatefilter:: time + +time +~~~~ + +Formats a time according to the given format. + +Given format can be the predefined one ``TIME_FORMAT``, or a custom format, +same as the :tfilter:`date` filter. Note that the predefined format is locale- +dependant. + +The time filter will only accept parameters in the format string that relate +to the time of day, not the date (for obvious reasons). If you need to +format a date, use the :tfilter:`date` filter. + +For example:: + + {{ value|time:"H:i" }} + +If ``value`` is equivalent to ``datetime.datetime.now()``, the output will be +the string ``"01:23"``. + +Another example: + +Assuming that :setting:`USE_L10N` is ``True`` and :setting:`LANGUAGE_CODE` is, +for example, ``"de"``, then for:: + + {{ value|time:"TIME_FORMAT" }} + +the output will be the string ``"01:23:00"`` (The ``"TIME_FORMAT"`` format +specifier for the ``de`` locale as shipped with Django is ``"H:i:s"``). + +When used without a format string:: + + {{ value|time }} + +...the formatting string defined in the :setting:`TIME_FORMAT` setting will be +used, without applying any localization. + +.. versionchanged:: 1.2 + Predefined formats can now be influenced by the current locale. + +.. templatefilter:: timesince + +timesince +~~~~~~~~~ + +Formats a date as the time since that date (e.g., "4 days, 6 hours"). + +Takes an optional argument that is a variable containing the date to use as +the comparison point (without the argument, the comparison point is *now*). +For example, if ``blog_date`` is a date instance representing midnight on 1 +June 2006, and ``comment_date`` is a date instance for 08:00 on 1 June 2006, +then ``{{ blog_date|timesince:comment_date }}`` would return "8 hours". + +Comparing offset-naive and offset-aware datetimes will return an empty string. + +Minutes is the smallest unit used, and "0 minutes" will be returned for any +date that is in the future relative to the comparison point. + +.. templatefilter:: timeuntil + +timeuntil +~~~~~~~~~ + +Similar to ``timesince``, except that it measures the time from now until the +given date or datetime. For example, if today is 1 June 2006 and +``conference_date`` is a date instance holding 29 June 2006, then +``{{ conference_date|timeuntil }}`` will return "4 weeks". + +Takes an optional argument that is a variable containing the date to use as +the comparison point (instead of *now*). If ``from_date`` contains 22 June +2006, then ``{{ conference_date|timeuntil:from_date }}`` will return "1 week". + +Comparing offset-naive and offset-aware datetimes will return an empty string. + +Minutes is the smallest unit used, and "0 minutes" will be returned for any +date that is in the past relative to the comparison point. + +.. templatefilter:: title + +title +~~~~~ + +Converts a string into titlecase. + +For example:: + + {{ value|title }} + +If ``value`` is ``"my first post"``, the output will be ``"My First Post"``. + +.. templatefilter:: truncatewords + +truncatewords +~~~~~~~~~~~~~ + +Truncates a string after a certain number of words. + +**Argument:** Number of words to truncate after + +For example:: + + {{ value|truncatewords:2 }} + +If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is ..."``. + +Newlines within the string will be removed. + +.. templatefilter:: truncatewords_html + +truncatewords_html +~~~~~~~~~~~~~~~~~~ + +Similar to ``truncatewords``, except that it is aware of HTML tags. Any tags +that are opened in the string and not closed before the truncation point, are +closed immediately after the truncation. + +This is less efficient than ``truncatewords``, so should only be used when it +is being passed HTML text. + +For example:: + + {{ value|truncatewords_html:2 }} + +If ``value`` is ``"<p>Joel is a slug</p>"``, the output will be +``"<p>Joel is ...</p>"``. + +Newlines in the HTML content will be preserved. + +.. templatefilter:: unordered_list + +unordered_list +~~~~~~~~~~~~~~ + +Recursively takes a self-nested list and returns an HTML unordered list -- +WITHOUT opening and closing <ul> tags. + +.. versionchanged:: 1.0 + The format accepted by ``unordered_list`` has changed to be easier to understand. + +The list is assumed to be in the proper format. For example, if ``var`` contains +``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then +``{{ var|unordered_list }}`` would return:: + + <li>States + <ul> + <li>Kansas + <ul> + <li>Lawrence</li> + <li>Topeka</li> + </ul> + </li> + <li>Illinois</li> + </ul> + </li> + +Note: the previous more restrictive and verbose format is still supported: +``['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]``, + +.. templatefilter:: upper + +upper +~~~~~ + +Converts a string into all uppercase. + +For example:: + + {{ value|upper }} + +If ``value`` is ``"Joel is a slug"``, the output will be ``"JOEL IS A SLUG"``. + +.. templatefilter:: urlencode + +urlencode +~~~~~~~~~ + +Escapes a value for use in a URL. + +For example:: + + {{ value|urlencode }} + +If ``value`` is ``"http://www.example.org/foo?a=b&c=d"``, the output will be +``"http%3A//www.example.org/foo%3Fa%3Db%26c%3Dd"``. + +.. templatefilter:: urlize + +urlize +~~~~~~ + +Converts URLs in plain text into clickable links. + +Note that if ``urlize`` is applied to text that already contains HTML markup, +things won't work as expected. Apply this filter only to *plain* text. + +For example:: + + {{ value|urlize }} + +If ``value`` is ``"Check out www.djangoproject.com"``, the output will be +``"Check out <a +href="http://www.djangoproject.com">www.djangoproject.com</a>"``. + +.. templatefilter:: urlizetrunc + +urlizetrunc +~~~~~~~~~~~ + +Converts URLs into clickable links, truncating URLs longer than the given +character limit. + +As with urlize_, this filter should only be applied to *plain* text. + +**Argument:** Length to truncate URLs to + +For example:: + + {{ value|urlizetrunc:15 }} + +If ``value`` is ``"Check out www.djangoproject.com"``, the output would be +``'Check out <a +href="http://www.djangoproject.com">www.djangopr...</a>'``. + +.. templatefilter:: wordcount + +wordcount +~~~~~~~~~ + +Returns the number of words. + +For example:: + + {{ value|wordcount }} + +If ``value`` is ``"Joel is a slug"``, the output will be ``4``. + +.. templatefilter:: wordwrap + +wordwrap +~~~~~~~~ + +Wraps words at specified line length. + +**Argument:** number of characters at which to wrap the text + +For example:: + + {{ value|wordwrap:5 }} + +If ``value`` is ``Joel is a slug``, the output would be:: + + Joel + is a + slug + +.. templatefilter:: yesno + +yesno +~~~~~ + +Given a string mapping values for true, false and (optionally) None, +returns one of those strings according to the value: + +For example:: + + {{ value|yesno:"yeah,no,maybe" }} + +========== ====================== ================================== +Value Argument Outputs +========== ====================== ================================== +``True`` ``"yeah,no,maybe"`` ``yeah`` +``False`` ``"yeah,no,maybe"`` ``no`` +``None`` ``"yeah,no,maybe"`` ``maybe`` +``None`` ``"yeah,no"`` ``"no"`` (converts None to False + if no mapping for None is given) +========== ====================== ================================== + +Other tags and filter libraries +------------------------------- + +Django comes with a couple of other template-tag libraries that you have to +enable explicitly in your ``INSTALLED_APPS`` setting and enable in your +template with the ``{% load %}`` tag. + +django.contrib.humanize +~~~~~~~~~~~~~~~~~~~~~~~ + +A set of Django template filters useful for adding a "human touch" to data. See +:doc:`/ref/contrib/humanize`. + +django.contrib.markup +~~~~~~~~~~~~~~~~~~~~~ + +A collection of template filters that implement these common markup languages: + + * Textile + * Markdown + * reST (reStructuredText) + +See the :doc:`markup documentation </ref/contrib/markup>`. + +django.contrib.webdesign +~~~~~~~~~~~~~~~~~~~~~~~~ + +A collection of template tags that can be useful while designing a Web site, +such as a generator of Lorem Ipsum text. See :doc:`/ref/contrib/webdesign`. + +i18n +~~~~ + +Provides a couple of templatetags that allow specifying translatable text in +Django templates. It is slightly different from the libraries described +above because you don't need to add any application to the ``INSTALLED_APPS`` +setting but rather set :setting:`USE_I18N` to True, then loading it with +``{% load i18n %}``. See :ref:`specifying-translation-strings-in-template-code`. diff --git a/parts/django/docs/ref/templates/index.txt b/parts/django/docs/ref/templates/index.txt new file mode 100644 index 0000000..0aa4798 --- /dev/null +++ b/parts/django/docs/ref/templates/index.txt @@ -0,0 +1,19 @@ +========= +Templates +========= + +Django's template engine provides a powerful mini-language for defining the +user-facing layer of your application, encouraging a clean separation of +application and presentation logic. Templates can be maintained by anyone with +an understanding of HTML; no knowledge of Python is required. + +.. toctree:: + :maxdepth: 2 + + builtins + api + +.. seealso:: + + For information on writing your own custom tags and filters, see + :doc:`/howto/custom-template-tags`. |