Changeset 67

Timestamp:

07/15/05 15:37:03 (3 years ago)

Author:

jacob

Message:

Yes yes yes -- more documentation improvements

Files:

• django/trunk/docs/db-api.txt (modified) (1 diff)
• django/trunk/docs/faq.txt (modified) (3 diffs)
• django/trunk/docs/model-api.txt (modified) (6 diffs)

django/trunk/docs/db-api.txt

@@ -306 +306 @@
-====================
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

django/trunk/docs/faq.txt

@@ -67 +67 @@
-
-`Simon Willison`_
- 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.
-
+
+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. 
-
-`Jacob Kaplan-Moss`_
@@ -103 +103 @@
-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
-===================
@@ -109 +127 @@
-------------------------------------------------------------------
-
- site's
-
-
-
-in 
+
+
+
+
+
-
-.. _`guide to the CSS used in the admin`: http://www.djangoproject.com/documentation/admin_css/

django/trunk/docs/model-api.txt

@@ -181 +181 @@
-    ``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
@@ -303 +301 @@
-        meta.ForeignKey(Pizza)
-                
-options for defining how the 
-
+extra options for defining how
+the 
-    
-    =======================  ============================================================
@@ -365 +363 @@
-                             Not used with ``edit_inline``.
-                             
-ma
+am
-                             this would default to 'pizza' (so that the 
-                             ``Toppings`` object would have a ``get_pizza()``
@@ -432 +430 @@
-    
-``ManyToManyField``
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-``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.
@@ -574 +620 @@
-    
-``ordering``
- 
-
-model's 
+
+model's
+
-    
-``save_as``
-
-three save options: "Save", "Save and continue editing", and "Save
-d add another".   If ``save_as`` is ``True``, "Save and add another"
-will be 
+ three
+save options: "Save", "Save and continue editing", and "Save and add
+other".   If ``save_as`` is ``True``, "Save and add another" will be
+
-    
-``save_on_top``
-
-across 
+ across
+
-    
-``search_fields``
@@ -592 +638 @@
-    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")
+                
+
+