mirror of
https://github.com/django/django.git
synced 2025-08-04 02:48:35 +00:00
Fixed many more ReST indentation errors, somehow accidentally missed from [16955]
git-svn-id: http://code.djangoproject.com/svn/django/trunk@16983 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Luke Plant
parent
5109ac3709
commit
d1e5c55258
129 changed files with 5708 additions and 5740 deletions
|
|
@ -57,17 +57,17 @@ Install Django
|
|||
|
||||
You've got three easy options to install Django:
|
||||
|
||||
* Install a version of Django :doc:`provided by your operating system
|
||||
distribution </misc/distributions>`. This is the quickest option for those
|
||||
who have operating systems that distribute Django.
|
||||
* Install a version of Django :doc:`provided by your operating system
|
||||
distribution </misc/distributions>`. This is the quickest option for those
|
||||
who have operating systems that distribute Django.
|
||||
|
||||
* :ref:`Install an official release <installing-official-release>`. This
|
||||
is the best approach for users who want a stable version number and aren't
|
||||
concerned about running a slightly older version of Django.
|
||||
* :ref:`Install an official release <installing-official-release>`. This
|
||||
is the best approach for users who want a stable version number and aren't
|
||||
concerned about running a slightly older version of Django.
|
||||
|
||||
* :ref:`Install the latest development version
|
||||
<installing-development-version>`. This is best for users who want the
|
||||
latest-and-greatest features and aren't afraid of running brand-new code.
|
||||
* :ref:`Install the latest development version
|
||||
<installing-development-version>`. This is best for users who want the
|
||||
latest-and-greatest features and aren't afraid of running brand-new code.
|
||||
|
||||
.. admonition:: Always refer to the documentation that corresponds to the
|
||||
version of Django you're using!
|
||||
|
|
|
|||
|
|
@ -307,14 +307,14 @@ This is just the surface
|
|||
This has been only a quick overview of Django's functionality. Some more useful
|
||||
features:
|
||||
|
||||
* A :doc:`caching framework </topics/cache>` that integrates with memcached
|
||||
or other backends.
|
||||
* A :doc:`caching framework </topics/cache>` that integrates with memcached
|
||||
or other backends.
|
||||
|
||||
* A :doc:`syndication framework </ref/contrib/syndication>` that makes
|
||||
creating RSS and Atom feeds as easy as writing a small Python class.
|
||||
* A :doc:`syndication framework </ref/contrib/syndication>` that makes
|
||||
creating RSS and Atom feeds as easy as writing a small Python class.
|
||||
|
||||
* More sexy automatically-generated admin features -- this overview barely
|
||||
scratched the surface.
|
||||
* More sexy automatically-generated admin features -- this overview barely
|
||||
scratched the surface.
|
||||
|
||||
The next obvious steps are for you to `download Django`_, read :doc:`the
|
||||
tutorial </intro/tutorial01>` and join `the community`_. Thanks for your
|
||||
|
|
|
|||
|
|
@ -9,8 +9,8 @@ poll application.
|
|||
|
||||
It'll consist of two parts:
|
||||
|
||||
* A public site that lets people view polls and vote in them.
|
||||
* An admin site that lets you add, change and delete polls.
|
||||
* A public site that lets people view polls and vote in them.
|
||||
* An admin site that lets you add, change and delete polls.
|
||||
|
||||
We'll assume you have :doc:`Django installed </intro/install>` already. You can
|
||||
tell Django is installed by running the Python interactive interpreter and
|
||||
|
|
@ -190,30 +190,30 @@ module-level variables representing Django settings. Change the
|
|||
following keys in the :setting:`DATABASES` ``'default'`` item to match
|
||||
your databases connection settings.
|
||||
|
||||
* :setting:`ENGINE <DATABASE-ENGINE>` -- Either
|
||||
``'django.db.backends.postgresql_psycopg2'``,
|
||||
``'django.db.backends.mysql'`` or
|
||||
``'django.db.backends.sqlite3'``. Other backends are
|
||||
:setting:`also available <DATABASE-ENGINE>`.
|
||||
* :setting:`ENGINE <DATABASE-ENGINE>` -- Either
|
||||
``'django.db.backends.postgresql_psycopg2'``,
|
||||
``'django.db.backends.mysql'`` or
|
||||
``'django.db.backends.sqlite3'``. Other backends are
|
||||
:setting:`also available <DATABASE-ENGINE>`.
|
||||
|
||||
* :setting:`NAME` -- The name of your database. If you're using
|
||||
SQLite, the database will be a file on your computer; in that
|
||||
case, :setting:`NAME` should be the full absolute path,
|
||||
including filename, of that file. If the file doesn't exist, it
|
||||
will automatically be created when you synchronize the database
|
||||
for the first time (see below).
|
||||
* :setting:`NAME` -- The name of your database. If you're using
|
||||
SQLite, the database will be a file on your computer; in that
|
||||
case, :setting:`NAME` should be the full absolute path,
|
||||
including filename, of that file. If the file doesn't exist, it
|
||||
will automatically be created when you synchronize the database
|
||||
for the first time (see below).
|
||||
|
||||
When specifying the path, always use forward slashes, even on
|
||||
Windows (e.g. ``C:/homes/user/mysite/sqlite3.db``).
|
||||
When specifying the path, always use forward slashes, even on
|
||||
Windows (e.g. ``C:/homes/user/mysite/sqlite3.db``).
|
||||
|
||||
* :setting:`USER` -- Your database username (not used for SQLite).
|
||||
* :setting:`USER` -- Your database username (not used for SQLite).
|
||||
|
||||
* :setting:`PASSWORD` -- Your database password (not used for
|
||||
SQLite).
|
||||
* :setting:`PASSWORD` -- Your database password (not used for
|
||||
SQLite).
|
||||
|
||||
* :setting:`HOST` -- The host your database is on. Leave this as
|
||||
an empty string if your database server is on the same physical
|
||||
machine (not used for SQLite).
|
||||
* :setting:`HOST` -- The host your database is on. Leave this as
|
||||
an empty string if your database server is on the same physical
|
||||
machine (not used for SQLite).
|
||||
|
||||
If you're new to databases, we recommend simply using SQLite (by
|
||||
setting :setting:`ENGINE` to ``'django.db.backends.sqlite3'``). SQLite
|
||||
|
|
@ -238,19 +238,19 @@ distribute them for use by others in their projects.
|
|||
By default, :setting:`INSTALLED_APPS` contains the following apps, all of which
|
||||
come with Django:
|
||||
|
||||
* :mod:`django.contrib.auth` -- An authentication system.
|
||||
* :mod:`django.contrib.auth` -- An authentication system.
|
||||
|
||||
* :mod:`django.contrib.contenttypes` -- A framework for content types.
|
||||
* :mod:`django.contrib.contenttypes` -- A framework for content types.
|
||||
|
||||
* :mod:`django.contrib.sessions` -- A session framework.
|
||||
* :mod:`django.contrib.sessions` -- A session framework.
|
||||
|
||||
* :mod:`django.contrib.sites` -- A framework for managing multiple sites
|
||||
with one Django installation.
|
||||
* :mod:`django.contrib.sites` -- A framework for managing multiple sites
|
||||
with one Django installation.
|
||||
|
||||
* :mod:`django.contrib.messages` -- A messaging framework.
|
||||
* :mod:`django.contrib.messages` -- A messaging framework.
|
||||
|
||||
* :mod:`django.contrib.staticfiles` -- A framework for managing
|
||||
static files.
|
||||
* :mod:`django.contrib.staticfiles` -- A framework for managing
|
||||
static files.
|
||||
|
||||
These applications are included by default as a convenience for the common case.
|
||||
|
||||
|
|
@ -390,8 +390,8 @@ Activating models
|
|||
That small bit of model code gives Django a lot of information. With it, Django
|
||||
is able to:
|
||||
|
||||
* Create a database schema (``CREATE TABLE`` statements) for this app.
|
||||
* Create a Python database-access API for accessing Poll and Choice objects.
|
||||
* Create a database schema (``CREATE TABLE`` statements) for this app.
|
||||
* Create a Python database-access API for accessing Poll and Choice objects.
|
||||
|
||||
But first we need to tell our project that the ``polls`` app is installed.
|
||||
|
||||
|
|
@ -441,52 +441,52 @@ statements for the polls app):
|
|||
|
||||
Note the following:
|
||||
|
||||
* The exact output will vary depending on the database you are using.
|
||||
* The exact output will vary depending on the database you are using.
|
||||
|
||||
* Table names are automatically generated by combining the name of the app
|
||||
(``polls``) and the lowercase name of the model -- ``poll`` and
|
||||
``choice``. (You can override this behavior.)
|
||||
* Table names are automatically generated by combining the name of the app
|
||||
(``polls``) and the lowercase name of the model -- ``poll`` and
|
||||
``choice``. (You can override this behavior.)
|
||||
|
||||
* Primary keys (IDs) are added automatically. (You can override this, too.)
|
||||
* Primary keys (IDs) are added automatically. (You can override this, too.)
|
||||
|
||||
* By convention, Django appends ``"_id"`` to the foreign key field name.
|
||||
Yes, you can override this, as well.
|
||||
* By convention, Django appends ``"_id"`` to the foreign key field name.
|
||||
Yes, you can override this, as well.
|
||||
|
||||
* The foreign key relationship is made explicit by a ``REFERENCES``
|
||||
statement.
|
||||
* The foreign key relationship is made explicit by a ``REFERENCES``
|
||||
statement.
|
||||
|
||||
* It's tailored to the database you're using, so database-specific field
|
||||
types such as ``auto_increment`` (MySQL), ``serial`` (PostgreSQL), or
|
||||
``integer primary key`` (SQLite) are handled for you automatically. Same
|
||||
goes for quoting of field names -- e.g., using double quotes or single
|
||||
quotes. The author of this tutorial runs PostgreSQL, so the example
|
||||
output is in PostgreSQL syntax.
|
||||
* It's tailored to the database you're using, so database-specific field
|
||||
types such as ``auto_increment`` (MySQL), ``serial`` (PostgreSQL), or
|
||||
``integer primary key`` (SQLite) are handled for you automatically. Same
|
||||
goes for quoting of field names -- e.g., using double quotes or single
|
||||
quotes. The author of this tutorial runs PostgreSQL, so the example
|
||||
output is in PostgreSQL syntax.
|
||||
|
||||
* The :djadmin:`sql` command doesn't actually run the SQL in your database -
|
||||
it just prints it to the screen so that you can see what SQL Django thinks
|
||||
is required. If you wanted to, you could copy and paste this SQL into your
|
||||
database prompt. However, as we will see shortly, Django provides an
|
||||
easier way of committing the SQL to the database.
|
||||
* The :djadmin:`sql` command doesn't actually run the SQL in your database -
|
||||
it just prints it to the screen so that you can see what SQL Django thinks
|
||||
is required. If you wanted to, you could copy and paste this SQL into your
|
||||
database prompt. However, as we will see shortly, Django provides an
|
||||
easier way of committing the SQL to the database.
|
||||
|
||||
If you're interested, also run the following commands:
|
||||
|
||||
* :djadmin:`python manage.py validate <validate>` -- Checks for any errors
|
||||
in the construction of your models.
|
||||
* :djadmin:`python manage.py validate <validate>` -- Checks for any errors
|
||||
in the construction of your models.
|
||||
|
||||
* :djadmin:`python manage.py sqlcustom polls <sqlcustom>` -- Outputs any
|
||||
:ref:`custom SQL statements <initial-sql>` (such as table modifications or
|
||||
constraints) that are defined for the application.
|
||||
* :djadmin:`python manage.py sqlcustom polls <sqlcustom>` -- Outputs any
|
||||
:ref:`custom SQL statements <initial-sql>` (such as table modifications or
|
||||
constraints) that are defined for the application.
|
||||
|
||||
* :djadmin:`python manage.py sqlclear polls <sqlclear>` -- Outputs the
|
||||
necessary ``DROP TABLE`` statements for this app, according to which
|
||||
tables already exist in your database (if any).
|
||||
* :djadmin:`python manage.py sqlclear polls <sqlclear>` -- Outputs the
|
||||
necessary ``DROP TABLE`` statements for this app, according to which
|
||||
tables already exist in your database (if any).
|
||||
|
||||
* :djadmin:`python manage.py sqlindexes polls <sqlindexes>` -- Outputs the
|
||||
``CREATE INDEX`` statements for this app.
|
||||
* :djadmin:`python manage.py sqlindexes polls <sqlindexes>` -- Outputs the
|
||||
``CREATE INDEX`` statements for this app.
|
||||
|
||||
* :djadmin:`python manage.py sqlall polls <sqlall>` -- A combination of all
|
||||
the SQL from the :djadmin:`sql`, :djadmin:`sqlcustom`, and
|
||||
:djadmin:`sqlindexes` commands.
|
||||
* :djadmin:`python manage.py sqlall polls <sqlall>` -- A combination of all
|
||||
the SQL from the :djadmin:`sql`, :djadmin:`sqlcustom`, and
|
||||
:djadmin:`sqlindexes` commands.
|
||||
|
||||
Looking at the output of those commands can help you understand what's actually
|
||||
happening under the hood.
|
||||
|
|
|
|||
|
|
@ -27,38 +27,38 @@ Activate the admin site
|
|||
The Django admin site is not activated by default -- it's an opt-in thing. To
|
||||
activate the admin site for your installation, do these three things:
|
||||
|
||||
* Add ``"django.contrib.admin"`` to your :setting:`INSTALLED_APPS` setting.
|
||||
* Add ``"django.contrib.admin"`` to your :setting:`INSTALLED_APPS` setting.
|
||||
|
||||
* Run ``python manage.py syncdb``. Since you have added a new application
|
||||
to :setting:`INSTALLED_APPS`, the database tables need to be updated.
|
||||
* Run ``python manage.py syncdb``. Since you have added a new application
|
||||
to :setting:`INSTALLED_APPS`, the database tables need to be updated.
|
||||
|
||||
* Edit your ``mysite/urls.py`` file and uncomment the lines that reference
|
||||
the admin -- there are three lines in total to uncomment. This file is a
|
||||
URLconf; we'll dig into URLconfs in the next tutorial. For now, all you
|
||||
need to know is that it maps URL roots to applications. In the end, you
|
||||
should have a ``urls.py`` file that looks like this:
|
||||
* Edit your ``mysite/urls.py`` file and uncomment the lines that reference
|
||||
the admin -- there are three lines in total to uncomment. This file is a
|
||||
URLconf; we'll dig into URLconfs in the next tutorial. For now, all you
|
||||
need to know is that it maps URL roots to applications. In the end, you
|
||||
should have a ``urls.py`` file that looks like this:
|
||||
|
||||
.. parsed-literal::
|
||||
.. parsed-literal::
|
||||
|
||||
from django.conf.urls import patterns, include, url
|
||||
from django.conf.urls import patterns, include, url
|
||||
|
||||
# Uncomment the next two lines to enable the admin:
|
||||
**from django.contrib import admin**
|
||||
**admin.autodiscover()**
|
||||
# Uncomment the next two lines to enable the admin:
|
||||
**from django.contrib import admin**
|
||||
**admin.autodiscover()**
|
||||
|
||||
urlpatterns = patterns('',
|
||||
# Examples:
|
||||
# url(r'^$', '{{ project_name }}.views.home', name='home'),
|
||||
# url(r'^{{ project_name }}/', include('{{ project_name }}.foo.urls')),
|
||||
urlpatterns = patterns('',
|
||||
# Examples:
|
||||
# url(r'^$', '{{ project_name }}.views.home', name='home'),
|
||||
# url(r'^{{ project_name }}/', include('{{ project_name }}.foo.urls')),
|
||||
|
||||
# Uncomment the admin/doc line below to enable admin documentation:
|
||||
# url(r'^admin/doc/', include('django.contrib.admindocs.urls')),
|
||||
# Uncomment the admin/doc line below to enable admin documentation:
|
||||
# url(r'^admin/doc/', include('django.contrib.admindocs.urls')),
|
||||
|
||||
# Uncomment the next line to enable the admin:
|
||||
**url(r'^admin/', include(admin.site.urls)),**
|
||||
)
|
||||
# Uncomment the next line to enable the admin:
|
||||
**url(r'^admin/', include(admin.site.urls)),**
|
||||
)
|
||||
|
||||
(The bold lines are the ones that needed to be uncommented.)
|
||||
(The bold lines are the ones that needed to be uncommented.)
|
||||
|
||||
Start the development server
|
||||
============================
|
||||
|
|
@ -145,29 +145,29 @@ Click the "What's up?" poll to edit it:
|
|||
|
||||
Things to note here:
|
||||
|
||||
* The form is automatically generated from the Poll model.
|
||||
* The form is automatically generated from the Poll model.
|
||||
|
||||
* The different model field types (:class:`~django.db.models.DateTimeField`,
|
||||
:class:`~django.db.models.CharField`) correspond to the appropriate HTML
|
||||
input widget. Each type of field knows how to display itself in the Django
|
||||
admin.
|
||||
* The different model field types (:class:`~django.db.models.DateTimeField`,
|
||||
:class:`~django.db.models.CharField`) correspond to the appropriate HTML
|
||||
input widget. Each type of field knows how to display itself in the Django
|
||||
admin.
|
||||
|
||||
* Each :class:`~django.db.models.DateTimeField` gets free JavaScript
|
||||
shortcuts. Dates get a "Today" shortcut and calendar popup, and times get
|
||||
a "Now" shortcut and a convenient popup that lists commonly entered times.
|
||||
* Each :class:`~django.db.models.DateTimeField` gets free JavaScript
|
||||
shortcuts. Dates get a "Today" shortcut and calendar popup, and times get
|
||||
a "Now" shortcut and a convenient popup that lists commonly entered times.
|
||||
|
||||
The bottom part of the page gives you a couple of options:
|
||||
|
||||
* Save -- Saves changes and returns to the change-list page for this type of
|
||||
object.
|
||||
* Save -- Saves changes and returns to the change-list page for this type of
|
||||
object.
|
||||
|
||||
* Save and continue editing -- Saves changes and reloads the admin page for
|
||||
this object.
|
||||
* Save and continue editing -- Saves changes and reloads the admin page for
|
||||
this object.
|
||||
|
||||
* Save and add another -- Saves changes and loads a new, blank form for this
|
||||
type of object.
|
||||
* Save and add another -- Saves changes and loads a new, blank form for this
|
||||
type of object.
|
||||
|
||||
* Delete -- Displays a delete confirmation page.
|
||||
* Delete -- Displays a delete confirmation page.
|
||||
|
||||
Change the "Date published" by clicking the "Today" and "Now" shortcuts. Then
|
||||
click "Save and continue editing." Then click "History" in the upper right.
|
||||
|
|
|
|||
|
|
@ -13,31 +13,31 @@ A view is a "type" of Web page in your Django application that generally serves
|
|||
a specific function and has a specific template. For example, in a Weblog
|
||||
application, you might have the following views:
|
||||
|
||||
* Blog homepage -- displays the latest few entries.
|
||||
* Blog homepage -- displays the latest few entries.
|
||||
|
||||
* Entry "detail" page -- permalink page for a single entry.
|
||||
* Entry "detail" page -- permalink page for a single entry.
|
||||
|
||||
* Year-based archive page -- displays all months with entries in the
|
||||
given year.
|
||||
* Year-based archive page -- displays all months with entries in the
|
||||
given year.
|
||||
|
||||
* Month-based archive page -- displays all days with entries in the
|
||||
given month.
|
||||
* Month-based archive page -- displays all days with entries in the
|
||||
given month.
|
||||
|
||||
* Day-based archive page -- displays all entries in the given day.
|
||||
* Day-based archive page -- displays all entries in the given day.
|
||||
|
||||
* Comment action -- handles posting comments to a given entry.
|
||||
* Comment action -- handles posting comments to a given entry.
|
||||
|
||||
In our poll application, we'll have the following four views:
|
||||
|
||||
* Poll "index" page -- displays the latest few polls.
|
||||
* Poll "index" page -- displays the latest few polls.
|
||||
|
||||
* Poll "detail" page -- displays a poll question, with no results but
|
||||
with a form to vote.
|
||||
* Poll "detail" page -- displays a poll question, with no results but
|
||||
with a form to vote.
|
||||
|
||||
* Poll "results" page -- displays results for a particular poll.
|
||||
* Poll "results" page -- displays results for a particular poll.
|
||||
|
||||
* Vote action -- handles voting for a particular choice in a particular
|
||||
poll.
|
||||
* Vote action -- handles voting for a particular choice in a particular
|
||||
poll.
|
||||
|
||||
In Django, each view is represented by a simple Python function.
|
||||
|
||||
|
|
@ -375,21 +375,21 @@ in ``django/conf/urls/defaults.py``, ``handler404`` is set to
|
|||
|
||||
Four more things to note about 404 views:
|
||||
|
||||
* If :setting:`DEBUG` is set to ``True`` (in your settings module) then your
|
||||
404 view will never be used (and thus the ``404.html`` template will never
|
||||
be rendered) because the traceback will be displayed instead.
|
||||
* If :setting:`DEBUG` is set to ``True`` (in your settings module) then your
|
||||
404 view will never be used (and thus the ``404.html`` template will never
|
||||
be rendered) because the traceback will be displayed instead.
|
||||
|
||||
* The 404 view is also called if Django doesn't find a match after checking
|
||||
every regular expression in the URLconf.
|
||||
* The 404 view is also called if Django doesn't find a match after checking
|
||||
every regular expression in the URLconf.
|
||||
|
||||
* If you don't define your own 404 view -- and simply use the default, which
|
||||
is recommended -- you still have one obligation: To create a ``404.html``
|
||||
template in the root of your template directory. The default 404 view will
|
||||
use that template for all 404 errors.
|
||||
* If you don't define your own 404 view -- and simply use the default, which
|
||||
is recommended -- you still have one obligation: To create a ``404.html``
|
||||
template in the root of your template directory. The default 404 view will
|
||||
use that template for all 404 errors.
|
||||
|
||||
* If :setting:`DEBUG` is set to ``False`` (in your settings module) and if
|
||||
you didn't create a ``404.html`` file, an ``Http500`` is raised instead.
|
||||
So remember to create a ``404.html``.
|
||||
* If :setting:`DEBUG` is set to ``False`` (in your settings module) and if
|
||||
you didn't create a ``404.html`` file, an ``Http500`` is raised instead.
|
||||
So remember to create a ``404.html``.
|
||||
|
||||
Write a 500 (server error) view
|
||||
===============================
|
||||
|
|
@ -517,11 +517,11 @@ URLconf for further processing.
|
|||
|
||||
Here's what happens if a user goes to "/polls/34/" in this system:
|
||||
|
||||
* Django will find the match at ``'^polls/'``
|
||||
* Django will find the match at ``'^polls/'``
|
||||
|
||||
* Then, Django will strip off the matching text (``"polls/"``) and send the
|
||||
remaining text -- ``"34/"`` -- to the 'polls.urls' URLconf for
|
||||
further processing.
|
||||
* Then, Django will strip off the matching text (``"polls/"``) and send the
|
||||
remaining text -- ``"34/"`` -- to the 'polls.urls' URLconf for
|
||||
further processing.
|
||||
|
||||
Now that we've decoupled that, we need to decouple the ``polls.urls``
|
||||
URLconf by removing the leading "polls/" from each line, and removing the
|
||||
|
|
|
|||
|
|
@ -29,28 +29,28 @@ tutorial, so that the template contains an HTML ``<form>`` element:
|
|||
|
||||
A quick rundown:
|
||||
|
||||
* The above template displays a radio button for each poll choice. The
|
||||
``value`` of each radio button is the associated poll choice's ID. The
|
||||
``name`` of each radio button is ``"choice"``. That means, when somebody
|
||||
selects one of the radio buttons and submits the form, it'll send the
|
||||
POST data ``choice=3``. This is HTML Forms 101.
|
||||
* The above template displays a radio button for each poll choice. The
|
||||
``value`` of each radio button is the associated poll choice's ID. The
|
||||
``name`` of each radio button is ``"choice"``. That means, when somebody
|
||||
selects one of the radio buttons and submits the form, it'll send the
|
||||
POST data ``choice=3``. This is HTML Forms 101.
|
||||
|
||||
* We set the form's ``action`` to ``/polls/{{ poll.id }}/vote/``, and we
|
||||
set ``method="post"``. Using ``method="post"`` (as opposed to
|
||||
``method="get"``) is very important, because the act of submitting this
|
||||
form will alter data server-side. Whenever you create a form that alters
|
||||
data server-side, use ``method="post"``. This tip isn't specific to
|
||||
Django; it's just good Web development practice.
|
||||
* We set the form's ``action`` to ``/polls/{{ poll.id }}/vote/``, and we
|
||||
set ``method="post"``. Using ``method="post"`` (as opposed to
|
||||
``method="get"``) is very important, because the act of submitting this
|
||||
form will alter data server-side. Whenever you create a form that alters
|
||||
data server-side, use ``method="post"``. This tip isn't specific to
|
||||
Django; it's just good Web development practice.
|
||||
|
||||
* ``forloop.counter`` indicates how many times the :ttag:`for` tag has gone
|
||||
through its loop
|
||||
* ``forloop.counter`` indicates how many times the :ttag:`for` tag has gone
|
||||
through its loop
|
||||
|
||||
* Since we're creating a POST form (which can have the effect of modifying
|
||||
data), we need to worry about Cross Site Request Forgeries.
|
||||
Thankfully, you don't have to worry too hard, because Django comes with
|
||||
a very easy-to-use system for protecting against it. In short, all POST
|
||||
forms that are targeted at internal URLs should use the
|
||||
:ttag:`{% csrf_token %}<csrf_token>` template tag.
|
||||
* Since we're creating a POST form (which can have the effect of modifying
|
||||
data), we need to worry about Cross Site Request Forgeries.
|
||||
Thankfully, you don't have to worry too hard, because Django comes with
|
||||
a very easy-to-use system for protecting against it. In short, all POST
|
||||
forms that are targeted at internal URLs should use the
|
||||
:ttag:`{% csrf_token %}<csrf_token>` template tag.
|
||||
|
||||
The :ttag:`{% csrf_token %}<csrf_token>` tag requires information from the
|
||||
request object, which is not normally accessible from within the template
|
||||
|
|
@ -102,48 +102,48 @@ create a real version. Add the following to ``polls/views.py``::
|
|||
|
||||
This code includes a few things we haven't covered yet in this tutorial:
|
||||
|
||||
* :attr:`request.POST <django.http.HttpRequest.POST>` is a dictionary-like
|
||||
object that lets you access submitted data by key name. In this case,
|
||||
``request.POST['choice']`` returns the ID of the selected choice, as a
|
||||
string. :attr:`request.POST <django.http.HttpRequest.POST>` values are
|
||||
always strings.
|
||||
* :attr:`request.POST <django.http.HttpRequest.POST>` is a dictionary-like
|
||||
object that lets you access submitted data by key name. In this case,
|
||||
``request.POST['choice']`` returns the ID of the selected choice, as a
|
||||
string. :attr:`request.POST <django.http.HttpRequest.POST>` values are
|
||||
always strings.
|
||||
|
||||
Note that Django also provides :attr:`request.GET
|
||||
<django.http.HttpRequest.GET>` for accessing GET data in the same way --
|
||||
but we're explicitly using :attr:`request.POST
|
||||
<django.http.HttpRequest.POST>` in our code, to ensure that data is only
|
||||
altered via a POST call.
|
||||
Note that Django also provides :attr:`request.GET
|
||||
<django.http.HttpRequest.GET>` for accessing GET data in the same way --
|
||||
but we're explicitly using :attr:`request.POST
|
||||
<django.http.HttpRequest.POST>` in our code, to ensure that data is only
|
||||
altered via a POST call.
|
||||
|
||||
* ``request.POST['choice']`` will raise :exc:`KeyError` if ``choice`` wasn't
|
||||
provided in POST data. The above code checks for :exc:`KeyError` and
|
||||
redisplays the poll form with an error message if ``choice`` isn't given.
|
||||
* ``request.POST['choice']`` will raise :exc:`KeyError` if ``choice`` wasn't
|
||||
provided in POST data. The above code checks for :exc:`KeyError` and
|
||||
redisplays the poll form with an error message if ``choice`` isn't given.
|
||||
|
||||
* After incrementing the choice count, the code returns an
|
||||
:class:`~django.http.HttpResponseRedirect` rather than a normal
|
||||
:class:`~django.http.HttpResponse`.
|
||||
:class:`~django.http.HttpResponseRedirect` takes a single argument: the
|
||||
URL to which the user will be redirected (see the following point for how
|
||||
we construct the URL in this case).
|
||||
* After incrementing the choice count, the code returns an
|
||||
:class:`~django.http.HttpResponseRedirect` rather than a normal
|
||||
:class:`~django.http.HttpResponse`.
|
||||
:class:`~django.http.HttpResponseRedirect` takes a single argument: the
|
||||
URL to which the user will be redirected (see the following point for how
|
||||
we construct the URL in this case).
|
||||
|
||||
As the Python comment above points out, you should always return an
|
||||
:class:`~django.http.HttpResponseRedirect` after successfully dealing with
|
||||
POST data. This tip isn't specific to Django; it's just good Web
|
||||
development practice.
|
||||
As the Python comment above points out, you should always return an
|
||||
:class:`~django.http.HttpResponseRedirect` after successfully dealing with
|
||||
POST data. This tip isn't specific to Django; it's just good Web
|
||||
development practice.
|
||||
|
||||
* We are using the :func:`~django.core.urlresolvers.reverse` function in the
|
||||
:class:`~django.http.HttpResponseRedirect` constructor in this example.
|
||||
This function helps avoid having to hardcode a URL in the view function.
|
||||
It is given the name of the view that we want to pass control to and the
|
||||
variable portion of the URL pattern that points to that view. In this
|
||||
case, using the URLconf we set up in Tutorial 3, this
|
||||
:func:`~django.core.urlresolvers.reverse` call will return a string like
|
||||
::
|
||||
* We are using the :func:`~django.core.urlresolvers.reverse` function in the
|
||||
:class:`~django.http.HttpResponseRedirect` constructor in this example.
|
||||
This function helps avoid having to hardcode a URL in the view function.
|
||||
It is given the name of the view that we want to pass control to and the
|
||||
variable portion of the URL pattern that points to that view. In this
|
||||
case, using the URLconf we set up in Tutorial 3, this
|
||||
:func:`~django.core.urlresolvers.reverse` call will return a string like
|
||||
::
|
||||
|
||||
'/polls/3/results/'
|
||||
'/polls/3/results/'
|
||||
|
||||
... where the ``3`` is the value of ``p.id``. This redirected URL will
|
||||
then call the ``'results'`` view to display the final page. Note that you
|
||||
need to use the full name of the view here (including the prefix).
|
||||
... where the ``3`` is the value of ``p.id``. This redirected URL will
|
||||
then call the ``'results'`` view to display the final page. Note that you
|
||||
need to use the full name of the view here (including the prefix).
|
||||
|
||||
As mentioned in Tutorial 3, ``request`` is a :class:`~django.http.HttpRequest`
|
||||
object. For more on :class:`~django.http.HttpRequest` objects, see the
|
||||
|
|
@ -197,11 +197,11 @@ Let's convert our poll app to use the generic views system, so we can delete a
|
|||
bunch of our own code. We'll just have to take a few steps to make the
|
||||
conversion. We will:
|
||||
|
||||
1. Convert the URLconf.
|
||||
1. Convert the URLconf.
|
||||
|
||||
2. Delete some of the old, unneeded views.
|
||||
2. Delete some of the old, unneeded views.
|
||||
|
||||
3. Fix up URL handling for the new views.
|
||||
3. Fix up URL handling for the new views.
|
||||
|
||||
Read on for details.
|
||||
|
||||
|
|
@ -257,22 +257,22 @@ We're using two generic views here:
|
|||
two views abstract the concepts of "display a list of objects" and
|
||||
"display a detail page for a particular type of object."
|
||||
|
||||
* Each generic view needs to know what model it will be acting
|
||||
upon. This is provided using the ``model`` parameter.
|
||||
* Each generic view needs to know what model it will be acting
|
||||
upon. This is provided using the ``model`` parameter.
|
||||
|
||||
* The :class:`~django.views.generic.list.DetailView` generic view
|
||||
expects the primary key value captured from the URL to be called
|
||||
``"pk"``, so we've changed ``poll_id`` to ``pk`` for the generic
|
||||
views.
|
||||
* The :class:`~django.views.generic.list.DetailView` generic view
|
||||
expects the primary key value captured from the URL to be called
|
||||
``"pk"``, so we've changed ``poll_id`` to ``pk`` for the generic
|
||||
views.
|
||||
|
||||
* We've added a name, ``poll_results``, to the results view so
|
||||
that we have a way to refer to its URL later on (see the
|
||||
documentation about :ref:`naming URL patterns
|
||||
<naming-url-patterns>` for information). We're also using the
|
||||
:func:`~django.conf.urls.url` function from
|
||||
:mod:`django.conf.urls` here. It's a good habit to use
|
||||
:func:`~django.conf.urls.url` when you are providing a
|
||||
pattern name like this.
|
||||
* We've added a name, ``poll_results``, to the results view so
|
||||
that we have a way to refer to its URL later on (see the
|
||||
documentation about :ref:`naming URL patterns
|
||||
<naming-url-patterns>` for information). We're also using the
|
||||
:func:`~django.conf.urls.url` function from
|
||||
:mod:`django.conf.urls` here. It's a good habit to use
|
||||
:func:`~django.conf.urls.url` when you are providing a
|
||||
pattern name like this.
|
||||
|
||||
By default, the :class:`~django.views.generic.list.DetailView` generic
|
||||
view uses a template called ``<app name>/<model name>_detail.html``.
|
||||
|
|
@ -328,12 +328,12 @@ Coming soon
|
|||
The tutorial ends here for the time being. Future installments of the tutorial
|
||||
will cover:
|
||||
|
||||
* Advanced form processing
|
||||
* Using the RSS framework
|
||||
* Using the cache framework
|
||||
* Using the comments framework
|
||||
* Advanced admin features: Permissions
|
||||
* Advanced admin features: Custom JavaScript
|
||||
* Advanced form processing
|
||||
* Using the RSS framework
|
||||
* Using the cache framework
|
||||
* Using the comments framework
|
||||
* Advanced admin features: Permissions
|
||||
* Advanced admin features: Custom JavaScript
|
||||
|
||||
In the meantime, you might want to check out some pointers on :doc:`where to go
|
||||
from here </intro/whatsnext>`
|
||||
|
|
|
|||
|
|
@ -35,43 +35,43 @@ How the documentation is organized
|
|||
Django's main documentation is broken up into "chunks" designed to fill
|
||||
different needs:
|
||||
|
||||
* The :doc:`introductory material </intro/index>` is designed for people new
|
||||
to Django -- or to Web development in general. It doesn't cover anything
|
||||
in depth, but instead gives a high-level overview of how developing in
|
||||
Django "feels".
|
||||
* The :doc:`introductory material </intro/index>` is designed for people new
|
||||
to Django -- or to Web development in general. It doesn't cover anything
|
||||
in depth, but instead gives a high-level overview of how developing in
|
||||
Django "feels".
|
||||
|
||||
* The :doc:`topic guides </topics/index>`, on the other hand, dive deep into
|
||||
individual parts of Django. There are complete guides to Django's
|
||||
:doc:`model system </topics/db/index>`, :doc:`template engine
|
||||
</topics/templates>`, :doc:`forms framework </topics/forms/index>`, and much
|
||||
more.
|
||||
* The :doc:`topic guides </topics/index>`, on the other hand, dive deep into
|
||||
individual parts of Django. There are complete guides to Django's
|
||||
:doc:`model system </topics/db/index>`, :doc:`template engine
|
||||
</topics/templates>`, :doc:`forms framework </topics/forms/index>`, and much
|
||||
more.
|
||||
|
||||
This is probably where you'll want to spend most of your time; if you work
|
||||
your way through these guides you should come out knowing pretty much
|
||||
everything there is to know about Django.
|
||||
This is probably where you'll want to spend most of your time; if you work
|
||||
your way through these guides you should come out knowing pretty much
|
||||
everything there is to know about Django.
|
||||
|
||||
* Web development is often broad, not deep -- problems span many domains.
|
||||
We've written a set of :doc:`how-to guides </howto/index>` that answer
|
||||
common "How do I ...?" questions. Here you'll find information about
|
||||
:doc:`generating PDFs with Django </howto/outputting-pdf>`, :doc:`writing
|
||||
custom template tags </howto/custom-template-tags>`, and more.
|
||||
* Web development is often broad, not deep -- problems span many domains.
|
||||
We've written a set of :doc:`how-to guides </howto/index>` that answer
|
||||
common "How do I ...?" questions. Here you'll find information about
|
||||
:doc:`generating PDFs with Django </howto/outputting-pdf>`, :doc:`writing
|
||||
custom template tags </howto/custom-template-tags>`, and more.
|
||||
|
||||
Answers to really common questions can also be found in the :doc:`FAQ
|
||||
</faq/index>`.
|
||||
Answers to really common questions can also be found in the :doc:`FAQ
|
||||
</faq/index>`.
|
||||
|
||||
* The guides and how-to's don't cover every single class, function, and
|
||||
method available in Django -- that would be overwhelming when you're
|
||||
trying to learn. Instead, details about individual classes, functions,
|
||||
methods, and modules are kept in the :doc:`reference </ref/index>`. This is
|
||||
where you'll turn to find the details of a particular function or
|
||||
whathaveyou.
|
||||
* The guides and how-to's don't cover every single class, function, and
|
||||
method available in Django -- that would be overwhelming when you're
|
||||
trying to learn. Instead, details about individual classes, functions,
|
||||
methods, and modules are kept in the :doc:`reference </ref/index>`. This is
|
||||
where you'll turn to find the details of a particular function or
|
||||
whathaveyou.
|
||||
|
||||
* Finally, there's some "specialized" documentation not usually relevant to
|
||||
most developers. This includes the :doc:`release notes </releases/index>`,
|
||||
:doc:`documentation of obsolete features </obsolete/index>`,
|
||||
:doc:`internals documentation </internals/index>` for those who want to add
|
||||
code to Django itself, and a :doc:`few other things that simply don't fit
|
||||
elsewhere </misc/index>`.
|
||||
* Finally, there's some "specialized" documentation not usually relevant to
|
||||
most developers. This includes the :doc:`release notes </releases/index>`,
|
||||
:doc:`documentation of obsolete features </obsolete/index>`,
|
||||
:doc:`internals documentation </internals/index>` for those who want to add
|
||||
code to Django itself, and a :doc:`few other things that simply don't fit
|
||||
elsewhere </misc/index>`.
|
||||
|
||||
|
||||
How documentation is updated
|
||||
|
|
@ -81,16 +81,16 @@ Just as the Django code base is developed and improved on a daily basis, our
|
|||
documentation is consistently improving. We improve documentation for several
|
||||
reasons:
|
||||
|
||||
* To make content fixes, such as grammar/typo corrections.
|
||||
* To make content fixes, such as grammar/typo corrections.
|
||||
|
||||
* To add information and/or examples to existing sections that need to be
|
||||
expanded.
|
||||
* To add information and/or examples to existing sections that need to be
|
||||
expanded.
|
||||
|
||||
* To document Django features that aren't yet documented. (The list of
|
||||
such features is shrinking but exists nonetheless.)
|
||||
* To document Django features that aren't yet documented. (The list of
|
||||
such features is shrinking but exists nonetheless.)
|
||||
|
||||
* To add documentation for new features as new features get added, or as
|
||||
Django APIs or behaviors change.
|
||||
* To add documentation for new features as new features get added, or as
|
||||
Django APIs or behaviors change.
|
||||
|
||||
Django's documentation is kept in the same source control system as its code. It
|
||||
lives in the `django/trunk/docs`_ directory of our Subversion repository. Each
|
||||
|
|
@ -164,33 +164,33 @@ As HTML, locally
|
|||
|
||||
You can get a local copy of the HTML documentation following a few easy steps:
|
||||
|
||||
* Django's documentation uses a system called Sphinx__ to convert from
|
||||
plain text to HTML. You'll need to install Sphinx by either downloading
|
||||
and installing the package from the Sphinx Web site, or by Python's
|
||||
``easy_install``:
|
||||
* Django's documentation uses a system called Sphinx__ to convert from
|
||||
plain text to HTML. You'll need to install Sphinx by either downloading
|
||||
and installing the package from the Sphinx Web site, or by Python's
|
||||
``easy_install``:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
$ easy_install Sphinx
|
||||
$ easy_install Sphinx
|
||||
|
||||
* Then, just use the included ``Makefile`` to turn the documentation into
|
||||
HTML:
|
||||
* Then, just use the included ``Makefile`` to turn the documentation into
|
||||
HTML:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
$ cd path/to/django/docs
|
||||
$ make html
|
||||
$ cd path/to/django/docs
|
||||
$ make html
|
||||
|
||||
You'll need `GNU Make`__ installed for this.
|
||||
You'll need `GNU Make`__ installed for this.
|
||||
|
||||
If you're on Windows you can alternatively use the included batch file:
|
||||
If you're on Windows you can alternatively use the included batch file:
|
||||
|
||||
.. code-block:: bat
|
||||
.. code-block:: bat
|
||||
|
||||
cd path\to\django\docs
|
||||
make.bat html
|
||||
cd path\to\django\docs
|
||||
make.bat html
|
||||
|
||||
* The HTML documentation will be placed in ``docs/_build/html``.
|
||||
* The HTML documentation will be placed in ``docs/_build/html``.
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -212,27 +212,27 @@ versions of the framework.
|
|||
|
||||
We follow this policy:
|
||||
|
||||
* The primary documentation on djangoproject.com is an HTML version of the
|
||||
latest docs in Subversion. These docs always correspond to the latest
|
||||
official Django release, plus whatever features we've added/changed in
|
||||
the framework *since* the latest release.
|
||||
* The primary documentation on djangoproject.com is an HTML version of the
|
||||
latest docs in Subversion. These docs always correspond to the latest
|
||||
official Django release, plus whatever features we've added/changed in
|
||||
the framework *since* the latest release.
|
||||
|
||||
* As we add features to Django's development version, we try to update the
|
||||
documentation in the same Subversion commit transaction.
|
||||
* As we add features to Django's development version, we try to update the
|
||||
documentation in the same Subversion commit transaction.
|
||||
|
||||
* To distinguish feature changes/additions in the docs, we use the phrase:
|
||||
"New in version X.Y", being X.Y the next release version (hence, the one
|
||||
being developed).
|
||||
* To distinguish feature changes/additions in the docs, we use the phrase:
|
||||
"New in version X.Y", being X.Y the next release version (hence, the one
|
||||
being developed).
|
||||
|
||||
* Documentation for a particular Django release is frozen once the version
|
||||
has been released officially. It remains a snapshot of the docs as of the
|
||||
moment of the release. We will make exceptions to this rule in
|
||||
the case of retroactive security updates or other such retroactive
|
||||
changes. Once documentation is frozen, we add a note to the top of each
|
||||
frozen document that says "These docs are frozen for Django version XXX"
|
||||
and links to the current version of that document.
|
||||
* Documentation for a particular Django release is frozen once the version
|
||||
has been released officially. It remains a snapshot of the docs as of the
|
||||
moment of the release. We will make exceptions to this rule in
|
||||
the case of retroactive security updates or other such retroactive
|
||||
changes. Once documentation is frozen, we add a note to the top of each
|
||||
frozen document that says "These docs are frozen for Django version XXX"
|
||||
and links to the current version of that document.
|
||||
|
||||
* The `main documentation Web page`_ includes links to documentation for
|
||||
all previous versions.
|
||||
* The `main documentation Web page`_ includes links to documentation for
|
||||
all previous versions.
|
||||
|
||||
.. _main documentation Web page: http://docs.djangoproject.com/en/dev/
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue