From fcec755f01cfaba2a85bfc9511876debbce98631 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Fri, 17 Aug 2007 15:05:54 +0000 Subject: newforms-admin: Merged from trunk up to [5916] git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@5918 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/authentication.txt | 7 +- docs/contributing.txt | 7 + docs/csrf.txt | 10 +- docs/databrowse.txt | 1 + docs/django-admin.txt | 42 +- docs/generic_views.txt | 10 +- docs/middleware.txt | 6 + docs/model-api.txt | 3 +- docs/modpython.txt | 24 + docs/newforms.txt | 179 +++++++- docs/request_response.txt | 24 +- docs/sessions.txt | 6 + docs/testing.txt | 1078 ++++++++++++++++++++++++++++----------------- docs/tutorial01.txt | 6 +- 14 files changed, 974 insertions(+), 429 deletions(-) (limited to 'docs') diff --git a/docs/authentication.txt b/docs/authentication.txt index 589e8c9f1b..7860b59d7d 100644 --- a/docs/authentication.txt +++ b/docs/authentication.txt @@ -436,7 +436,10 @@ template context variables: * ``next``: The URL to redirect to after successful login. This may contain a query string, too. * ``site_name``: The name of the current ``Site``, according to the - ``SITE_ID`` setting. See the `site framework docs`_. + ``SITE_ID`` setting. If you're using the Django development version and + you don't have the site framework installed, this will be set to the + value of ``request.META['SERVER_NAME']``. For more on sites, see the + `site framework docs`_. If you'd prefer not to call the template ``registration/login.html``, you can pass the ``template_name`` parameter via the extra arguments to the view in @@ -675,8 +678,6 @@ Example in Python 2.4 syntax:: The permission_required decorator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**New in Django development version** - It's a relatively common task to check whether a user has a particular permission. For that reason, Django provides a shortcut for that case: the ``permission_required()`` decorator. Using this decorator, the earlier example diff --git a/docs/contributing.txt b/docs/contributing.txt index 61c368d32a..cce54fa485 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -67,6 +67,13 @@ particular: likely to get lost. If a particular ticket is controversial, please move discussion to `django-developers`_. + * **Don't** post to django-developers just to announce that you have filed + a bug report. All the tickets are mailed to another list + (`django-updates`_), which is tracked by developers and triagers, so we + see them as they are filed. + +.. _django-updates: http://groups.google.com/group/django-updates + Reporting security issues ========================= diff --git a/docs/csrf.txt b/docs/csrf.txt index c12dd1d116..7d79e39502 100644 --- a/docs/csrf.txt +++ b/docs/csrf.txt @@ -41,10 +41,10 @@ CsrfMiddleware does two things: This ensures that only forms that have originated from your web site can be used to POST data back. -It deliberately only targets HTTP POST requests (and the corresponding -POST forms). GET requests ought never to have side effects (if you are -using HTTP GET and POST correctly), and so a CSRF attack with a GET -request will always be harmless. +It deliberately only targets HTTP POST requests (and the corresponding POST +forms). GET requests ought never to have any potentially dangerous side +effects (see `9.1.1 Safe Methods, HTTP 1.1, RFC 2616`_), and so a +CSRF attack with a GET request ought to be harmless. POST requests that are not accompanied by a session cookie are not protected, but they do not need to be protected, since the 'attacking' web site @@ -54,6 +54,8 @@ The Content-Type is checked before modifying the response, and only pages that are served as 'text/html' or 'application/xml+xhtml' are modified. +.. _9.1.1 Safe Methods, HTTP 1.1, RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html + Limitations =========== diff --git a/docs/databrowse.txt b/docs/databrowse.txt index 9c03e7e4ea..81e9e8e83b 100644 --- a/docs/databrowse.txt +++ b/docs/databrowse.txt @@ -35,6 +35,7 @@ How to use Databrowse 2. Register a number of models with the Databrowse site:: from django.contrib import databrowse + from myapp.models import SomeModel, SomeOtherModel databrowse.site.register(SomeModel) databrowse.site.register(SomeOtherModel) diff --git a/docs/django-admin.txt b/docs/django-admin.txt index ad17907b5e..aea990c5dc 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -235,6 +235,7 @@ The ``dumpdata`` command can be used to generate input for ``loaddata``. reset [appname appname ...] --------------------------- + Executes the equivalent of ``sqlreset`` for the given appnames. runfcgi [options] @@ -426,7 +427,46 @@ test Discover and run tests for all installed models. See `Testing Django applications`_ for more information. -.. _testing django applications: ../testing/ +.. _testing Django applications: ../testing/ + +testserver [fixture fixture ...] +-------------------------------- + +**New in Django development version** + +Runs a Django development server (as in ``runserver``) using data from the +given fixture(s). + +For example, this command:: + + django-admin.py testserver mydata.json + +...would perform the following steps: + + 1. Create a test database, as described in `testing Django applications`_. + 2. Populate the test database with fixture data from the given fixtures. + (For more on fixtures, see the documentation for ``loaddata`` above.) + 3. Runs the Django development server (as in ``runserver``), pointed at + this newly created test database instead of your production database. + +This is useful in a number of ways: + + * When you're writing `unit tests`_ of how your views act with certain + fixture data, you can use ``testserver`` to interact with the views in + a Web browser, manually. + + * Let's say you're developing your Django application and have a "pristine" + copy of a database that you'd like to interact with. You can dump your + database to a fixture (using the ``dumpdata`` command, explained above), + then use ``testserver`` to run your Web application with that data. With + this arrangement, you have the flexibility of messing up your data + in any way, knowing that whatever data changes you're making are only + being made to a test database. + +Note that this server can only run on the default port on localhost; it does +not yet accept a ``host`` or ``port`` parameter. + +.. _unit tests: ../testing/ validate -------- diff --git a/docs/generic_views.txt b/docs/generic_views.txt index 2b80348903..0601aead11 100644 --- a/docs/generic_views.txt +++ b/docs/generic_views.txt @@ -40,7 +40,7 @@ simple weblog app that drives the blog on djangoproject.com:: } urlpatterns = patterns('django.views.generic.date_based', - (r'^(?P\d{4})/(?P[a-z]{3})/(?P\w{1,2})/(?P[-\w]+)/$', 'object_detail', dict(info_dict, slug_field='slug')), + (r'^(?P\d{4})/(?P[a-z]{3})/(?P\w{1,2})/(?P[-\w]+)/$', 'object_detail', info_dict), (r'^(?P\d{4})/(?P[a-z]{3})/(?P\w{1,2})/$', 'archive_day', info_dict), (r'^(?P\d{4})/(?P[a-z]{3})/$', 'archive_month', info_dict), (r'^(?P\d{4})/$', 'archive_year', info_dict), @@ -603,7 +603,7 @@ future, the view will throw a 404 error by default, unless you set Otherwise, ``slug`` should be the slug of the given object, and ``slug_field`` should be the name of the slug field in the ``QuerySet``'s - model. + model. By default, ``slug_field`` is ``'slug'``. **Optional arguments:** @@ -804,7 +804,7 @@ A page representing an individual object. Otherwise, ``slug`` should be the slug of the given object, and ``slug_field`` should be the name of the slug field in the ``QuerySet``'s - model. + model. By default, ``slug_field`` is ``'slug'``. **Optional arguments:** @@ -948,7 +948,7 @@ object. This uses the automatic manipulators that come with Django models. Otherwise, ``slug`` should be the slug of the given object, and ``slug_field`` should be the name of the slug field in the ``QuerySet``'s - model. + model. By default, ``slug_field`` is ``'slug'``. **Optional arguments:** @@ -1033,7 +1033,7 @@ contain a form that POSTs to the same URL. Otherwise, ``slug`` should be the slug of the given object, and ``slug_field`` should be the name of the slug field in the ``QuerySet``'s - model. + model. By default, ``slug_field`` is ``'slug'``. * ``post_delete_redirect``: A URL to which the view will redirect after deleting the object. diff --git a/docs/middleware.txt b/docs/middleware.txt index 533f1ccede..63ba8c6999 100644 --- a/docs/middleware.txt +++ b/docs/middleware.txt @@ -91,6 +91,12 @@ django.middleware.gzip.GZipMiddleware Compresses content for browsers that understand gzip compression (all modern browsers). +It is suggested to place this first in the middleware list, so that the +compression of the response content is the last thing that happens. Will not +compress content bodies less than 200 bytes long, when the response code is +something other than 200, Javascript files (for IE compatibitility), or +responses that have the ``Content-Encoding`` header already specified. + django.middleware.http.ConditionalGetMiddleware ----------------------------------------------- diff --git a/docs/model-api.txt b/docs/model-api.txt index ddeb481206..0f872c3097 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -415,7 +415,8 @@ form:: models.SlugField(prepopulate_from=("pre_name", "name")) -``prepopulate_from`` doesn't accept DateTimeFields. +``prepopulate_from`` doesn't accept DateTimeFields, ForeignKeys nor +ManyToManyFields. The admin represents ``SlugField`` as an ```` (a single-line input). diff --git a/docs/modpython.txt b/docs/modpython.txt index 676aab19ac..c90296bd9a 100644 --- a/docs/modpython.txt +++ b/docs/modpython.txt @@ -63,6 +63,30 @@ computer, you'll have to tell mod_python where your project can be found: **PythonPath "['/path/to/project'] + sys.path"** +The value you use for ``PythonPath`` should include the parent directories of +all the modules you are going to import in your application. It should also +include the parent directory of the ``DJANGO_SETTINGS_MODULE`` location. This +is exactly the same situation as setting the Python path for interactive +usage. Whenever you try to import something, Python will run through all the +directories in ``sys.path`` in turn, from first to last, and try to import +from each directory until one succeeds. + +An example might make this clearer. Suppose +you have some applications under ``/usr/local/django-apps/`` (for example, +``/usr/local/django-apps/weblog/`` and so forth), your settings file is at +``/var/www/mysite/settings.py`` and you have specified +``DJANGO_SETTINGS_MODULE`` as in the above example. In this case, you would +need to write your ``PythonPath`` directive as:: + + PythonPath "['/var/production/django-apps/', '/var/www'] + sys.path" + +With this path, ``import weblog`` and ``import mysite.settings`` will both +work. If you had ``import blogroll`` in your code somewhere and ``blogroll`` +lived under the ``weblog/`` directory, you would *also* need to add +``/var/production/django-apps/weblog/`` to your ``PythonPath``. Remember: the +**parent directories** of anything you import directly must be on the Python +path. + .. caution:: If you're using Windows, remember that the path will contain backslashes. diff --git a/docs/newforms.txt b/docs/newforms.txt index acc28604df..803dc6458a 100644 --- a/docs/newforms.txt +++ b/docs/newforms.txt @@ -678,7 +678,7 @@ The easiest way is to iterate over the form's fields, with
{% for field in form %} -
{{ field.label }}
+
{{ field.label_tag }}
{{ field }}
{% if field.help_text %}
{{ field.help_text }}
{% endif %} {% if field.errors %}
{{ field.errors }}
{% endif %} @@ -698,11 +698,11 @@ For example::
    -
  • {{ form.sender.label }} {{ form.sender }}
    • +
  • {{ form.sender.label_tag }} {{ form.sender }}
  • {{ form.sender.help_text }}
    • {% if form.sender.errors %}
      {{ form.sender.errors }}
    {% endif %} -
  • {{ form.subject.label }} {{ form.subject }}
    • +
  • {{ form.subject.label_tag }} {{ form.subject }}
  • {{ form.subject.help_text }}
    • {% if form.subject.errors %}
      {{ form.subject.errors }}
    {% endif %} @@ -962,7 +962,7 @@ validation if a particular field's value is not given. ``initial`` values are ~~~~~~~~~~ The ``widget`` argument lets you specify a ``Widget`` class to use when -rendering this ``Field``. See "Widgets" below for more information. +rendering this ``Field``. See "Widgets"_ below for more information. ``help_text`` ~~~~~~~~~~~~~ @@ -1129,6 +1129,24 @@ If no ``input_formats`` argument is provided, the default input formats are:: '%m/%d/%y %H:%M', # '10/25/06 14:30' '%m/%d/%y', # '10/25/06' +``DecimalField`` +~~~~~~~~~~~~~~~~ + +**New in Django development version** + + * Default widget: ``TextInput`` + * Empty value: ``None`` + * Normalizes to: A Python ``decimal``. + * Validates that the given value is a decimal. Leading and trailing + whitespace is ignored. + +Takes four optional arguments: ``max_value``, ``min_value``, ``max_digits``, +and ``decimal_places``. The first two define the limits for the fields value. +``max_digits`` is the maximum number of digits (those before the decimal +point plus those after the decimal point, with leading zeros stripped) +permitted in the value, whilst ``decimal_places`` is the maximum number of +decimal places permitted. + ``EmailField`` ~~~~~~~~~~~~~~ @@ -1199,6 +1217,9 @@ When you use a ``FileField`` on a form, you must also remember to * Validates that the given value is an integer. Leading and trailing whitespace is allowed, as in Python's ``int()`` function. +Takes two optional arguments for validation, ``max_value`` and ``min_value``. +These control the range of values permitted in the field. + ``MultipleChoiceField`` ~~~~~~~~~~~~~~~~~~~~~~~ @@ -1416,6 +1437,156 @@ like so:: senders = MultiEmailField() cc_myself = forms.BooleanField() +Widgets +======= + +A widget is Django's representation of a HTML input element. The widget +handles the rendering of the HTML, and the extraction of data from a GET/POST +dictionary that corresponds to the widget. + +Django provides a representation of all the basic HTML widgets, plus some +commonly used groups of widgets: + + ============================ =========================================== + Widget HTML Equivalent + ============================ =========================================== + ``TextInput`` ``...`` + ``CheckboxInput`` ``