Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Yes yes yes -- more documentation improvements

git-svn-id: http://code.djangoproject.com/svn/django/trunk@67 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 604cd7fe14026da97f73fdb47dc48429b001290a 1 parent 05c5dab
Jacob Kaplan-Moss jacobian authored
Showing with 223 additions and 27 deletions.
  1. +41 −1 docs/db-api.txt
  2. +29 −11 docs/faq.txt
  3. +153 −15 docs/model-api.txt
42 docs/db-api.txt
View
@@ -305,4 +305,44 @@ objects fields, then call the object's ``save()`` method::
Creating new objects
====================
-...
+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.
+
40 docs/faq.txt
View
@@ -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/
168 docs/model-api.txt
View
@@ -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")
+
+
+
Please sign in to comment.
Something went wrong with that request. Please try again.