diff options
| -rw-r--r-- | docs/db-api.txt | 42 | ||||
| -rw-r--r-- | docs/faq.txt | 40 | ||||
| -rw-r--r-- | 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 f96b3ebca8..54a704d3f0 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 0afd3f52dc..0f2cbd0b42 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 d181bb868c..e4d059d1c1 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 |