Ticket #907: 907.diff

docs/forms.txt

@@ -340 +340 @@
       ``FormWrapper`` does not modify ``new_data`` in any way, and templates
       cannot, so this is perfectly safe.
 
+      If your object has a ``ManyToManyField``, you'll need to manually 
+      update ``new_data`` with details of the related objects. Let's say 
+      you're tagging your Places. In your model, that might looks like 
+      this::
+
+          from django.models.tags import tags
+          
+          class Place(meta.Model):
+              # ... all the other fields 
+              tags = ManyToManyField(tags.Tag, blank=True)
+
+      Details of a ``ManyToManyField``, however, won't be present in the 
+      ``__dict__`` of your instance; they're stored in a separate table 
+      and fetched and manipulated with ``get_*_list``, ``get_*_count``, and 
+      ``set_*`` methods on your object (see the 
+      `Many-to-one relationship model example`_ for a full example). So, 
+      you have to add a little more code to make these details available 
+      to the ``ChangeManipulator``. Continuing our example from above, 
+      all we need is one extra line in ``edit_place``::
+
+          # This makes sure the form accurate represents the fields of the place.
+          new_data = place.__dict__
+          # ... and this handles the ManyToManyField for place's tags. 
+          new_data['tags'] = [t.id for t in place.get_tag_list()]
+
     * The above example uses a different template, so create and edit can be
       "skinned" differently if needed, but the form chunk itself is completely
       identical to the one in the create form above.
 
+.. _Many-to-one relationship model example: http://www.djangoproject.com/documentation/models/many_to_one/
+
 The astute programmer will notice the add and create functions are nearly
 identical and could in fact be collapsed into a single view. This is left as an
 exercise for said programmer.