From 604cd7fe14026da97f73fdb47dc48429b001290a Mon Sep 17 00:00:00 2001
From: Jacob Kaplan-Moss <jacob@jacobian.org>
Date: Fri, 15 Jul 2005 20:37:03 +0000
Subject: [PATCH] Yes yes yes -- more documentation improvements

git-svn-id: http://code.djangoproject.com/svn/django/trunk@67 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/db-api.txt    |  42 +++++++++++-
 docs/faq.txt       |  40 ++++++++---
 docs/model-api.txt | 168 +++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 223 insertions(+), 27 deletions(-)

diff --git a/docs/db-api.txt b/docs/db-api.txt
index f96b3ebca8b..54a704d3f07 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -305,4 +305,44 @@ objects fields, then call the object's ``save()`` method::
 Creating new objects
 ====================
 
-...
\ No newline at end of file
+Creating new objects (i.e. ``INSERT``) is done by creating new instances
+of objects then calling save() on them::
+
+    >>> p = polls.Poll(id=None, 
+    ...                slug="eggs",
+    ...                question="How do you like your eggs?",
+    ...                pub_date=datetime.datetime.now(),
+    ...                expire_date=some_future_date)
+    >>> p.save()
+    
+Calling ``save()`` on an object with an id if ``None`` signifies to
+Django that the object is new and should be inserted.
+
+Related objects (i.e. ``Choices``) are created using convience functions::
+
+    >>> p.add_choice(choice="Over easy", votes=0)
+    >>> p.add_choice(choice="Scrambled", votes=0)
+    >>> p.add_choice(choice="Fertilized", votes=0)
+    >>> p.add_choice(choice="Poached", votes=0)
+    >>> p.get_choice_count()
+    4
+    
+Each of those ``add_choice`` methods is equivilent to (except obviously much
+simpler than)::
+
+    >>> c = polls.Choice(id=None,
+    ...                  poll_id=p.id,
+    ...                  choice="Over easy",
+    ...                  votes=0)
+    >>> c.save()
+    
+Note that when using the `add_foo()`` methods, you do not give any value
+for the ``id`` field, nor do you give a value for the field that stores 
+the relation (``poll_id`` in this case).
+
+Deleting objects
+================
+
+Just cause we're crazy like that, the delete method is named ``delete()``.
+Yeah, you never know what we're going to do next.
+
diff --git a/docs/faq.txt b/docs/faq.txt
index 0afd3f52dcd..0f2cbd0b427 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -66,12 +66,12 @@ Lawrence, Kansas, USA.
     `chicagocrime.org`_.
 
 `Simon Willison`_
-    Simon is a well-respected Web developer from England. He had a one-year stint
-    at World Online, during which time he and Adrian developed Django from scratch.
-    He's enthusiastic, he's passionate about best practices in Web development, and
-    he really likes squirrels. Probably to a fault. He went back to England to
-    finish his degree and is poised to continue doing big, exciting things on the Web.
-    Read his weblog at `simon.incutio.com`_.
+    Simon is a well-respected Web developer from England. He had a one-year
+    stint at World Online, during which time he and Adrian developed Django from
+    scratch. He's enthusiastic, he's passionate about best practices in Web
+    development, and he really likes squirrels. Probably to a fault. He went
+    back to England to finish his degree and is poised to continue doing big,
+    exciting things on the Web. Read his weblog at `simon.incutio.com`_.
 
 `Jacob Kaplan-Moss`_
     Jacob is a whipper-snapper from California who spends equal time coding and
@@ -102,17 +102,35 @@ How do I get started?
 
 We're working on this documentation as you read this.
 
+What are Django's prerequisites?
+--------------------------------
+
+Django requires Python_ 2.3 or later, Apache2_, and mod_python_.  You'll
+also need a database engine; PostgreSQL_ is recommended, and MySQL_ is
+supported.
+
+We're currently working on expanding those options: WSGI_ support is in the
+works (which will allow Django to run under CGI, FCGI, etc.), as is support for
+a number of other database backends.
+
+.. _Python: http://www.python.org/
+.. _Apache2: http://httpd.apache.org/
+.. _mod_python: http://www.modpython.org/
+.. _PostgreSQL: http://www.postgresql.org/
+.. _MySQL: http://www.mysql.com/
+.. _WSGI: http://www.python.org/peps/pep-0333.html
+
 The admin interface
 ===================
 
 The dynamically-generated admin site is ugly! How can I change it?
 ------------------------------------------------------------------
 
-We think it's very purty, but if you don't agree, you can modify the admin site's
-presentation by editing the CSS stylesheet and/or associated image files. The
-site is built using semantic HTML, so any changes you'd like to make should be
-possible by editing the CSS stylesheet. We've got a `guide to the CSS used
-in the admin`_ to get you started.
+We think it's very purty, but if you don't agree, you can modify the admin
+site's presentation by editing the CSS stylesheet and/or associated image files.
+The site is built using semantic HTML, so any changes you'd like to make should
+be possible by editing the CSS stylesheet. We've got a `guide to the CSS used in
+the admin`_ to get you started.
 
 .. _`guide to the CSS used in the admin`: http://www.djangoproject.com/documentation/admin_css/
 
diff --git a/docs/model-api.txt b/docs/model-api.txt
index d181bb868c8..e4d059d1c14 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -180,8 +180,6 @@ options that are common to all field types.  These options are:
     
     ``null``                If ``True`` empty values in the field will be 
                             stored as ``NULL`` in the database.  
-                            
-                            XXX does null imply blank? XXX
         
     ``primary_key``         If ``True`` this field is the primary key for the
                             table.  You only need to use this if you don't want
@@ -302,8 +300,8 @@ Field Types
     
         meta.ForeignKey(Pizza)
                 
-    ``ForeignKey`` fields take a large number of options for defining how the 
-    relationship should work:
+    ``ForeignKey`` fields take a large number of extra options for defining how
+    the relationship should work:
     
     =======================  ============================================================
     Option                   Description
@@ -364,7 +362,7 @@ Field Types
                              
                              Not used with ``edit_inline``.
                              
-    ``rel_name``             The name of the relation.  In the above exmaple,
+    ``rel_name``             The name of the relation.  In the above example,
                              this would default to 'pizza' (so that the 
                              ``Toppings`` object would have a ``get_pizza()``
                              function; if you set ``rel_name`` to "pie", then
@@ -431,12 +429,60 @@ Field Types
     An IP address, in string format (i.e. "24.124.1.30").
     
 ``ManyToManyField``
-    XXX document once Adrian reworks this XXX
+    A many-to-many relation to another object.  For example (taken from the
+    ``core.flatfiles`` object::
     
+        class FlatFile(meta.Model):
+            fields = (
+                ...
+                meta.ManyToManyField(Site),
+            )
+    
+    Many-to-many relations are a bit different from other fields.  First, they
+    aren't actually a field per se since they use a intermediary join table.
+    Second, they don't take any of the same options as the rest of the fields,
+    the only options taken are:
+    
+    =======================  ============================================================
+    Option                   Description
+    =======================  ============================================================
+    ``related_name``         See the description of ``related_name`` in 
+                             ``ManyToOneField``, above.
+                             
+    ``filter_interface``     Use a nifty unobtrusive Javascript "filter" interface 
+                             instead of the usability-challenged ``<select multiple>``.
+                             The value should be ``meta.HORIZONTAL`` or ``meta.VERTICAL``
+                             (i.e. should the interface be stacked horizontally or
+                             vertically).
+                             
+    ``limit_choices_to``     See the description under ``ManyToOneField``, above.
+    =======================  ============================================================
+
 ``NullBooleanField``
     Like a ``BooleanField``, but allows ``NULL`` as one of the options.  Use this
     instead of a ``BooleanField`` with ``null=True`` .
     
+``OneToOneField``
+    Signifies a one-to-one relationship.  This is most useful on the primary key
+    of an object when that object "extends" another object in some way.  
+    
+    For example, if you are building a database of "places", you would build pretty
+    standard stuff like address, phone number, etc. in the database.  If you then
+    wanted to build a database of restaurants on top of the places, instead of
+    repeating yourself and replicating those fields in the restaurants object, you
+    could make ``Restaurant`` have a ``OneToOneField`` to ``Place`` (since
+    a restaurant "is-a" place).  This ``OneToOneField`` will actually replace
+    the primary key ``id`` field (since one-to-one relations share the same
+    primary key), and has a few in the admin interface:
+    
+        * No selection interface is displayed on ``Restaurant`` pages; there will
+          be one (and only one) ``Restaurant`` for each place.
+          
+        * On the ``Restaurant`` change list, every single ``Place`` -- weather it
+          has an associated ``Restaurant`` or not -- will be displayed.  Adding
+          a ``Restaurant`` to a ``Place`` just means filling out the required
+          ``Restaurant`` fields.
+
 ``PhoneNumberField``
     Validates that the value is a valid phone number.
     
@@ -573,21 +619,113 @@ object, which has the following options (of which only ``fields`` is required):
     (This example also has ``search_fields`` defined; see below).
     
 ``ordering``
-    An ordering tuple (see the `Options for models`_, above) that gives a 
-    different ordering for the admin change list.  If not given, the 
-    model's default ordering will be used.
+    An ordering tuple (see the `Options for models`_, above) that gives a
+    different ordering for the admin change list.  If not given, the model's
+    default ordering will be used.
     
 ``save_as``
-    Enables a "save as" feature on object pages.  Normally, objects have
-    three save options: "Save", "Save and continue editing", and "Save
-    and add another".   If ``save_as`` is ``True``, "Save and add another"
-    will be replaced by a "Save as" button.
+    Enables a "save as" feature on object pages.  Normally, objects have three
+    save options: "Save", "Save and continue editing", and "Save and add
+    another".   If ``save_as`` is ``True``, "Save and add another" will be
+    replaced by a "Save as" button.
     
 ``save_on_top``
-    If this option is ``True``, object pages will have the save buttons
-    across the top as well as at the bottom of the page.
+    If this option is ``True``, object pages will have the save buttons across
+    the top as well as at the bottom of the page.
     
 ``search_fields``
     A list of fields to provide a text search for.  These fields should,
     obviously, be some kind of text field.
     
+Model methods
+=============
+
+There are a number of methods you can define on model objects to control the
+object's behavior.  First, any methods you define will be available as methods
+of object instances.  For example::
+
+    class Pizza(meta.Model):
+        fields = (
+            ...
+        )  
+        
+        def is_disgusting(self):
+            return "anchovices" in [topping.name for topping in self.get_topping_list()]
+               
+Now, every ``Pizza`` object will have a ``is_disgusting()`` method.  
+
+There are a few object methods that have special meaning:
+
+``__repr__``
+    Django uses ``repr(obj)`` in a number of places, the most notable as the
+    value inserted into a template when it displays an object.  Thus, you should
+    return a nice, human-readable string for the object's ``__repr__``.
+    
+``get_absolute_url``
+    If an object defines a ``get_absolute_url`` method, it is used   to
+    associate a URL with an object.  For example:
+    
+        def get_absolute_url(self):
+            return "/pizzas/%i/" % self.id
+            
+    The most useful place this is used is in the admin interface; if an object
+    defines ``get_absolute_url`` then the object detail page will have a "View
+    on site" link that will jump you directly to the object's public view.
+    
+``_pre_save``
+    This method will be called just before the object is saved into the
+    database; you can use it to (for example) calculate aggregate values from
+    other fields before the object is saved.
+    
+``_post_save``
+    Called just after the object is saved to the database.  This could be used
+    to update other tables, update cached information, etc.
+    
+Module-level methods
+--------------------
+
+Since each data class in effect turns into a module, there are times you'll want
+to write methods that live in that module.  Any model method that begins with
+"_module_" is turned into a module-level method::
+
+    class Pizza(meta.Model):
+        fields = (
+            ...
+        )
+        
+        def _module_get_pizzas_to_deliver():
+            return get_list(delivered__exact=False)
+            
+This will make the top-level ``pizzas`` module have a ``get_pizzas_to_deliver()``
+method::
+
+    >>> from django.models.pizza_hut import pizzas
+    >>> pizzas.get_pizzas_to_deliver()
+    [ ... ]
+    
+Note that the scope of these methods is modified to be the same has the module
+scope (so that's how the raw ``get_list`` works).
+
+Manipulator methods
+-------------------
+
+Similarly, you can add methods to the object's manipulators (see the formfields
+documentation for more on manipulators) by defining methods that being with
+"_manipulator_".  This is most useful for providing custom validators for certain
+fields since manipulators automatically call any method that begins with
+"validate"::
+
+    class Pizza(meta.Model):
+        fields = (
+            ...
+        )
+        
+        def _manipulator_validate_customer_id(self, field_data, all_data):
+            from django.core import validators
+            from django.conf.settings import BAD_CUSTOMER_IDS
+            
+            if int(field_data) in BAD_CUSTOMER_IDS:
+                raise validators.ValidationError("We don't deliver to this customer")
+                
+
+    
\ No newline at end of file