From 22e160945a38f82c7e30f7137b3fcac9dd778fba Mon Sep 17 00:00:00 2001
From: Adrian Holovaty <adrian@holovaty.com>
Date: Sat, 25 Aug 2007 23:31:05 +0000
Subject: newforms-admin: Merged to [6013]

git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@6014 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/add_ons.txt      | 23 +++++++++++++++
 docs/db-api.txt       | 19 +++++++++----
 docs/django-admin.txt | 21 +++++++++++---
 docs/faq.txt          |  4 ---
 docs/model-api.txt    |  2 +-
 docs/newforms.txt     | 78 +++++++++++++++++++++++++++++++++++++--------------
 docs/settings.txt     |  9 +++---
 docs/testing.txt      |  2 +-
 docs/tutorial01.txt   | 33 ++++++++++++++++++++++
 9 files changed, 151 insertions(+), 40 deletions(-)

(limited to 'docs')

diff --git a/docs/add_ons.txt b/docs/add_ons.txt
index 8682208970..a1d78b8685 100644
--- a/docs/add_ons.txt
+++ b/docs/add_ons.txt
@@ -138,6 +138,29 @@ Examples:
 
 You can pass in either an integer or a string representation of an integer.
 
+naturalday
+----------
+
+**New in Django development version**
+
+For dates that are the current day or within one day, return "today",
+"tomorrow" or "yesterday", as appropriate. Otherwise, format the date using
+the passed in format string.
+
+**Argument:** Date formatting string as described in default tag now_.
+
+.. _now: ../templates/#now
+
+Examples (when 'today' is 17 Feb 2007):
+
+    * ``16 Feb 2007`` becomes ``yesterday``.
+    * ``17 Feb 2007`` becomes ``today``.
+    * ``18 Feb 2007`` becomes ``tomorrow``.
+    * Any other day is formatted according to given argument or the
+      `DATE_FORMAT`_ setting if no argument is given.
+
+.. _DATE_FORMAT: ../settings/#date_format
+
 flatpages
 =========
 
diff --git a/docs/db-api.txt b/docs/db-api.txt
index 766a6ae519..3198f335c4 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -207,14 +207,23 @@ the database until you explicitly call ``save()``.
 
 The ``save()`` method has no return value.
 
-Updating ``ForeignKey`` fields works exactly the same way; simply assign an
-object of the right type to the field in question::
+Saving ForeignKey and ManyToManyField fields
+--------------------------------------------
+
+Updating ``ForeignKey`` fields works exactly the same way as saving a normal
+field; simply assign an object of the right type to the field in question:: 
+
+    cheese_blog = Blog.objects.get(name="Cheddar Talk") 
+    entry.blog = cheese_blog 
+    entry.save() 
+
+Updating a ``ManyToManyField`` works a little differently; use the ``add()``
+method on the field to add a record to the relation::
 
     joe = Author.objects.create(name="Joe")
-    entry.author = joe
-    entry.save()
+    entry.authors.add(joe)
 
-Django will complain if you try to assign an object of the wrong type.
+Django will complain if you try to assign or add an object of the wrong type.
 
 How Django knows to UPDATE vs. INSERT
 -------------------------------------
diff --git a/docs/django-admin.txt b/docs/django-admin.txt
index aea990c5dc..366483a47a 100644
--- a/docs/django-admin.txt
+++ b/docs/django-admin.txt
@@ -124,6 +124,13 @@ executed. This means that all data will be removed from the database, any
 post-synchronization handlers will be re-executed, and the ``initial_data``
 fixture will be re-installed.
 
+The behavior of this command has changed in the Django development version.
+Previously, this command cleared *every* table in the database, including any
+table that Django didn't know about (i.e., tables that didn't have associated
+models and/or weren't in ``INSTALLED_APPS``). Now, the command only clears
+tables that are represented by Django models and are activated in
+``INSTALLED_APPS``.
+
 inspectdb
 ---------
 
@@ -240,6 +247,7 @@ Executes the equivalent of ``sqlreset`` for the given appnames.
 
 runfcgi [options]
 -----------------
+
 Starts a set of FastCGI processes suitable for use with any web server
 which supports the FastCGI protocol. See the `FastCGI deployment
 documentation`_ for details. Requires the Python FastCGI module from
@@ -337,7 +345,7 @@ Refer to the description of ``sqlcustom`` for an explanation of how to
 specify initial data.
 
 sqlclear [appname appname ...]
---------------------------------------
+------------------------------
 
 Prints the DROP TABLE SQL statements for the given appnames.
 
@@ -360,18 +368,23 @@ table modifications, or insert any SQL functions into the database.
 
 Note that the order in which the SQL files are processed is undefined.
 
+sqlflush
+--------
+
+Prints the SQL statements that would be executed for the `flush`_ command.
+
 sqlindexes [appname appname ...]
-----------------------------------------
+--------------------------------
 
 Prints the CREATE INDEX SQL statements for the given appnames.
 
 sqlreset [appname appname ...]
---------------------------------------
+------------------------------
 
 Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given appnames.
 
 sqlsequencereset [appname appname ...]
-----------------------------------------------
+--------------------------------------
 
 Prints the SQL statements for resetting sequences for the given
 appnames.
diff --git a/docs/faq.txt b/docs/faq.txt
index 844ea77809..cef0508562 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -204,10 +204,6 @@ out a few points, we want to make sure they reflect the final state of things
 at Django 1.0, not some intermediary step. In other words, we don't want to
 spend a lot of energy creating screencasts yet, because Django APIs will shift.
 
-In the meantime, though, check out this `unofficial Django screencast`_.
-
-.. _unofficial Django screencast: http://www.throwingbeans.org/django_screencasts.html
-
 Is Django a content-management-system (CMS)?
 --------------------------------------------
 
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 0f872c3097..7dac54992f 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -344,7 +344,7 @@ development version. See the `Django 0.96 documentation`_ for the old behavior.
 ``ImageField``
 ~~~~~~~~~~~~~~
 
-Like ``FileField``, but validates that the uploaded object is a valid
+Like `FileField`_, but validates that the uploaded object is a valid
 image. Has two extra optional arguments, ``height_field`` and
 ``width_field``, which, if set, will be auto-populated with the height and
 width of the image each time a model instance is saved.
diff --git a/docs/newforms.txt b/docs/newforms.txt
index 503bd6634f..499892234c 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -1462,10 +1462,10 @@ commonly used groups of widgets:
     ``Textarea``                  ``<textarea>...</textarea>``
     ``CheckboxInput``             ``<input type='checkbox' ...``
     ``Select``                    ``<select><option ...``
-    ``NullBooleanSelect``         Select widget with options 'Unknown', 
+    ``NullBooleanSelect``         Select widget with options 'Unknown',
                                   'Yes' and 'No'
     ``SelectMultiple``            ``<select multiple='multiple'><option ...``
-    ``RadioSelect``               ``<ul><li><input type='radio' ...`` 
+    ``RadioSelect``               ``<ul><li><input type='radio' ...``
     ``CheckboxSelectMultiple``    ``<ul><li><input type='checkbox' ...``
     ``MultiWidget``               Wrapper around multiple other widgets
     ``SplitDateTimeWidget``       Wrapper around two ``TextInput`` widgets:
@@ -1476,19 +1476,19 @@ Specifying widgets
 ------------------
 
 Whenever you specify a field on a form, Django will use a default widget
-that is appropriate to the type of data that is to be displayed. To find 
+that is appropriate to the type of data that is to be displayed. To find
 which widget is used on which field, see the documentation for the
 built-in Field classes.
 
-However, if you want to use a different widget for a field, you can - 
+However, if you want to use a different widget for a field, you can -
 just use the 'widget' argument on the field definition. For example::
 
     class CommentForm(forms.Form):
         name = forms.CharField()
         url = forms.URLField()
         comment = forms.CharField(widget=forms.Textarea)
-        
-This would specify a form with a comment that uses a larger Textarea widget, 
+
+This would specify a form with a comment that uses a larger Textarea widget,
 rather than the default TextInput widget.
 
 Customizing widget instances
@@ -1499,8 +1499,8 @@ HTML - Django doesn't add a class definition, or any other widget-specific
 attributes. This means that all 'TextInput' widgets will appear the same
 on your web page.
 
-If you want to make one widget look different to another, you need to 
-specify additional attributes for each widget. When you specify a 
+If you want to make one widget look different to another, you need to
+specify additional attributes for each widget. When you specify a
 widget, you can provide a list of attributes that will be added to the
 rendered HTML for the widget.
 
@@ -1522,13 +1522,13 @@ each widget will be rendered exactly the same::
     <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
 
 On a real web page, you probably don't want every widget to look the same. You
-might want a larger input element for the comment, and you might want the 
-'name' widget to have some special CSS class. To do this, you specify a 
-custom widget for your fields, and specify some attributes to use 
+might want a larger input element for the comment, and you might want the
+'name' widget to have some special CSS class. To do this, you specify a
+custom widget for your fields, and specify some attributes to use
 when rendering those widgets::
 
     class CommentForm(forms.Form):
-        name = forms.CharField(                   
+        name = forms.CharField(
                     widget=forms.TextInput(attrs={'class':'special'}))
         url = forms.URLField()
         comment = forms.CharField(
@@ -1546,19 +1546,19 @@ Custom Widgets
 --------------
 
 When you start to write a lot of forms, you will probably find that you will
-reuse certain sets of widget attributes over and over again. Rather than 
-repeat these attribute definitions every time you need them, Django allows 
+reuse certain sets of widget attributes over and over again. Rather than
+repeat these attribute definitions every time you need them, Django allows
 you to capture those definitions as a custom widget.
 
 For example, if you find that you are including a lot of comment fields on forms,
-you could capture the idea of a ``TextInput`` with a specific ``size`` attribute 
+you could capture the idea of a ``TextInput`` with a specific ``size`` attribute
 as a custom extension to the ``TextInput`` widget::
 
     class CommentWidget(forms.TextInput):
         def __init__(self, *args, **kwargs):
             kwargs.setdefault('attrs',{}).update({'size': '40'})
-            super(forms.TextInput, self).__init__(*args, **kwargs)
-            
+            super(CommentWidget, self).__init__(*args, **kwargs)
+
 Then you can use this widget in your forms::
 
     class CommentForm(forms.Form):
@@ -1566,8 +1566,8 @@ Then you can use this widget in your forms::
         url = forms.URLField()
         comment = forms.CharField(widget=CommentWidget)
 
-You can even customize your custom widget, in the same way as you would 
-any other widget. Adding a once-off class to your ``CommentWidget`` is as 
+You can even customize your custom widget, in the same way as you would
+any other widget. Adding a once-off class to your ``CommentWidget`` is as
 simple as adding an attribute definition::
 
     class CommentForm(forms.Form):
@@ -1582,14 +1582,14 @@ by defining::
 
     class CommentInput(forms.CharField):
         widget = CommentWidget
-        
+
 You can then use this field whenever you have a form that requires a comment::
 
     class CommentForm(forms.Form):
         name = forms.CharField()
         url = forms.URLField()
         comment = CommentInput()
-        
+
 Generating forms for models
 ===========================
 
@@ -1934,6 +1934,42 @@ will raise ``ValueError`` if the data doesn't validate.
 ``form_for_instance()`` has ``form``, ``fields`` and ``formfield_callback``
 arguments that behave the same way as they do for ``form_for_model()``.
 
+Let's modify the earlier `contact form`_ view example a little bit. Suppose we
+have a ``Message`` model that holds each contact submission. Something like::
+
+    class Message(models.Model):
+        subject = models.CharField(max_length=100)
+        message = models.TextField()
+        sender = models.EmailField()
+        cc_myself = models.BooleanField()
+
+You could use this model to create a form (using ``form_for_model()``). You
+could also use existing ``Message`` instances to create a form for editing
+messages. The earlier_ view can be changed slightly to accept the ``id`` value
+of an existing ``Message`` and present it for editing::
+
+    def contact_edit(request, msg_id):
+        # Create the form from the message id.
+        message = get_object_or_404(Message, id=msg_id)
+        ContactForm = form_for_instance(message)
+
+        if request.method == 'POST':
+            form = ContactForm(request.POST)
+            if form.is_valid():
+                form.save()
+                return HttpResponseRedirect('/url/on_success/')
+        else:
+            form = ContactForm()
+        return render_to_response('contact.html', {'form': form})
+
+Aside from how we create the ``ContactForm`` class here, the main point to
+note is that the form display in the ``GET`` branch of the function
+will use the values from the ``message`` instance as initial values for the
+form field.
+
+.. _contact form: `Simple view example`_
+.. _earlier: `Simple view example`_
+
 When should you use ``form_for_model()`` and ``form_for_instance()``?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/settings.txt b/docs/settings.txt
index 050e377713..3f98296778 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -1101,10 +1101,11 @@ To disable this behavior, just remove all entries from the ``ADMINS`` setting.
 404 errors
 ----------
 
-When ``DEBUG`` is ``False`` and your ``MIDDLEWARE_CLASSES`` setting includes
-``CommonMiddleware``, Django will e-mail the users listed in the ``MANAGERS``
-setting whenever your code raises a 404 and the request has a referer.
-(It doesn't bother to e-mail for 404s that don't have a referer.)
+When ``DEBUG`` is ``False``, ``SEND_BROKEN_LINK_EMAILS`` is ``True`` and your
+``MIDDLEWARE_CLASSES`` setting includes ``CommonMiddleware``, Django will
+e-mail the users listed in the ``MANAGERS`` setting whenever your code raises
+a 404 and the request has a referer. (It doesn't bother to e-mail for 404s
+that don't have a referer.)
 
 You can tell Django to stop reporting particular 404s by tweaking the
 ``IGNORABLE_404_ENDS`` and ``IGNORABLE_404_STARTS`` settings. Both should be a
diff --git a/docs/testing.txt b/docs/testing.txt
index f189aa4578..e27479cc34 100644
--- a/docs/testing.txt
+++ b/docs/testing.txt
@@ -473,7 +473,7 @@ Once you have a ``Client`` instance, you can call any of the following methods:
     data. For example::
 
         >>> c = Client()
-        >>> c.get('/login/', {'name': 'fred', 'passwd': 'secret'})
+        >>> c.post('/login/', {'name': 'fred', 'passwd': 'secret'})
 
     ...will result in the evaluation of a POST request to this URL::
 
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index cf2b76e9be..65ea7503d7 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -259,6 +259,22 @@ These concepts are represented by simple Python classes. Edit the
         choice = models.CharField(max_length=200)
         votes = models.IntegerField()
 
+.. adminition:: Errors about ``max_length``
+
+   If Django gives you an error message saying that ``max_length`` is
+   not a valid argument, you're most likely using an old version of
+   Django. (This version of the tutorial is written for the latest
+   development version of Django.) If you're using a Subversion checkout
+   of Django's development version (see `the installation docs`_ for
+   more information), you shouldn't have any problems.
+
+   If you want to stick with an older version of Django, you'll want to
+   switch to `the Django 0.96 tutorial`_, because this tutorial covers
+   several features that only exist in the Django development version.
+
+.. _the installation docs: ../install/
+.. _the Django 0.96 tutorial: ../0.96/tutorial01/
+
 The code is straightforward. Each model is represented by a class that
 subclasses ``django.db.models.Model``. Each model has a number of class
 variables, each of which represents a database field in the model.
@@ -487,6 +503,23 @@ the ``polls/models.py`` file) and adding a ``__unicode__()`` method to both
         def __unicode__(self):
             return self.choice
 
+.. admonition:: If ``__unicode__()`` doesn't seem to work
+
+   If you add the ``__unicode__()`` method to your models and don't
+   see any change in how they're represented, you're most likely using
+   an old version of Django. (This version of the tutorial is written
+   for the latest development version of Django.) If you're using a
+   Subversion checkout of of Django's development version (see `the
+   installation docs`_ for more information), you shouldn't have any
+   problems.
+
+   If you want to stick with an older version of Django, you'll want to
+   switch to `the Django 0.96 tutorial`_, because this tutorial covers
+   several features that only exist in the Django development version.
+
+.. _the installation docs: ../install/
+.. _the Django 0.96 tutorial: ../0.96/tutorial01/
+
 It's important to add ``__unicode__()`` methods to your models, not only for
 your own sanity when dealing with the interactive prompt, but also because
 objects' representations are used throughout Django's automatically-generated
-- 
cgit v1.3