[1.5.x] Added some links in /docs/intro/overview.txt

    For more information on the :ttag:`load` tag, read its documentation.

.. _howto-writing-custom-template-filters:

Writing custom template filters

-------------------------------

=================

Although you can use Django without a database, it comes with an

object-relational mapper in which you describe your database layout in Python

`object-relational mapper`_ in which you describe your database layout in Python

code.

.. _object-relational mapper: http://en.wikipedia.org/wiki/Object-relational_mapping

The :doc:`data-model syntax </topics/db/models>` offers many rich ways of

representing your models -- so far, it's been solving two years' worth of

database-schema problems. Here's a quick example, which might be saved in

the file ``mysite/news/models.py``::

    from django.db import models

    class Reporter(models.Model):

        full_name = models.CharField(max_length=70)

Enjoy the free API

==================

With that, you've got a free, and rich, :doc:`Python API </topics/db/queries>` to

access your data. The API is created on the fly, no code generation necessary:

With that, you've got a free, and rich, :doc:`Python API </topics/db/queries>`

to access your data. The API is created on the fly, no code generation

necessary:

.. code-block:: python

============================================================================

Once your models are defined, Django can automatically create a professional,

production ready :doc:`administrative interface </ref/contrib/admin/index>` -- a Web

site that lets authenticated users add, change and delete objects. It's as easy

as registering your model in the admin site::

production ready :doc:`administrative interface </ref/contrib/admin/index>` --

a Web site that lets authenticated users add, change and delete objects. It's

as easy as registering your model in the admin site::

    # In models.py...

in URLs, like ``.php`` or ``.asp``.

To design URLs for an app, you create a Python module called a :doc:`URLconf

</topics/http/urls>`. A table of contents for your app, it contains a simple mapping

between URL patterns and Python callback functions. URLconfs also serve to

decouple URLs from Python code.

</topics/http/urls>`. A table of contents for your app, it contains a simple

mapping between URL patterns and Python callback functions. URLconfs also serve

to decouple URLs from Python code.

Here's what a URLconf might look like for the ``Reporter``/``Article``

example above::

        (r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'news.views.article_detail'),

    )

The code above maps URLs, as simple regular expressions, to the location of

The code above maps URLs, as simple `regular expressions`_, to the location of

Python callback functions ("views"). The regular expressions use parenthesis to

"capture" values from the URLs. When a user requests a page, Django runs

through each pattern, in order, and stops at the first one that matches the

This is blazingly fast, because the regular expressions are compiled at load

time.

.. _regular expressions: http://docs.python.org/2/howto/regex.html

Once one of the regexes matches, Django imports and calls the given view, which

is a simple Python function. Each view gets passed a request object --

which contains request metadata -- and the values captured in the regex.

and renders the template with the retrieved data. Here's an example view for

``year_archive`` from above::

    from django.shortcuts import render_to_response

    def year_archive(request, year):

        a_list = Article.objects.filter(pub_date__year=year)

        return render_to_response('news/year_archive.html', {'year': year, 'article_list': a_list})

Django has a template search path, which allows you to minimize redundancy among

templates. In your Django settings, you specify a list of directories to check

for templates. If a template doesn't exist in the first directory, it checks the

second, and so on.

for templates with :setting:`TEMPLATE_DIRS`. If a template doesn't exist in the

first directory, it checks the second, and so on.

Let's say the ``news/year_archive.html`` template was found. Here's what that

might look like:

of a variable. In this case, the date filter formats a Python datetime object in

the given format (as found in PHP's date function).

You can chain together as many filters as you'd like. You can write custom

filters. You can write custom template tags, which run custom Python code behind

the scenes.

You can chain together as many filters as you'd like. You can write :ref:`custom

template filters <howto-writing-custom-template-filters>`. You can write

:doc:`custom template tags </howto/custom-template-tags>`, which run custom

Python code behind the scenes.

Finally, Django uses the concept of "template inheritance": That's what the

``{% extends "base.html" %}`` does. It means "First load the template called