From b3dc23a6d5c0057f738a2bdb00b033c6da07631b Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Sun, 19 May 2013 12:06:35 -0400 Subject: [PATCH] [1.5.x] Added some links in /docs/intro/overview.txt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Thanks Claes Ström for the patch. Backport of bdde7feb26 from master. --- docs/howto/custom-template-tags.txt | 2 ++ docs/intro/overview.txt | 40 ++++++++++++++++++----------- 2 files changed, 27 insertions(+), 15 deletions(-) diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt index e5644dd7a5..91541c7cce 100644 --- a/docs/howto/custom-template-tags.txt +++ b/docs/howto/custom-template-tags.txt @@ -72,6 +72,8 @@ following: For more information on the :ttag:`load` tag, read its documentation. +.. _howto-writing-custom-template-filters: + Writing custom template filters ------------------------------- diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt index 8753817256..77838ffcaa 100644 --- a/docs/intro/overview.txt +++ b/docs/intro/overview.txt @@ -16,14 +16,18 @@ Design your model ================= 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 ` 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) @@ -55,8 +59,9 @@ tables in your database for whichever tables don't already exist. Enjoy the free API ================== -With that, you've got a free, and rich, :doc:`Python API ` 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 ` +to access your data. The API is created on the fly, no code generation +necessary: .. code-block:: python @@ -133,9 +138,9 @@ A dynamic admin interface: it's not just scaffolding -- it's the whole house ============================================================================ Once your models are defined, Django can automatically create a professional, -production ready :doc:`administrative interface ` -- 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 ` -- +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... @@ -171,9 +176,9 @@ application. Django encourages beautiful URL design and doesn't put any cruft in URLs, like ``.php`` or ``.asp``. To design URLs for an app, you create a Python module called a :doc:`URLconf -`. 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. +`. 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:: @@ -186,7 +191,7 @@ 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 @@ -194,6 +199,8 @@ requested URL. (If none of them matches, Django calls a special-case 404 view.) 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. @@ -214,6 +221,8 @@ Generally, a view retrieves data according to the parameters, loads a template 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}) @@ -229,8 +238,8 @@ The code above loads the ``news/year_archive.html`` template. 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: @@ -261,9 +270,10 @@ character). This is called a template filter, and it's a way to filter the value 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 `. You can write +:doc:`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