diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/add_ons.txt | 23 | ||||
| -rw-r--r-- | docs/db-api.txt | 19 | ||||
| -rw-r--r-- | docs/django-admin.txt | 21 | ||||
| -rw-r--r-- | docs/faq.txt | 4 | ||||
| -rw-r--r-- | docs/model-api.txt | 2 | ||||
| -rw-r--r-- | docs/newforms.txt | 78 | ||||
| -rw-r--r-- | docs/settings.txt | 9 | ||||
| -rw-r--r-- | docs/testing.txt | 2 | ||||
| -rw-r--r-- | docs/tutorial01.txt | 33 |
9 files changed, 151 insertions, 40 deletions
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 |