boulder-oracle-sprint: Merged to [4905].

git-svn-id: http://code.djangoproject.com/svn/django/branches/boulder-oracle-sprint@4906 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 30 insertions, 8 deletions

diff --git a/docs/model-api.txt b/docs/model-api.txt
index 155ef63271..a03ed09eb2 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -1307,13 +1307,13 @@ A few special cases to note about ``list_display``:
     * Usually, elements of ``list_display`` that aren't actual database fields
       can't be used in sorting (because Django does all the sorting at the
       database level).
-      
+
       However, if an element of ``list_display`` represents a certain database
       field, you can indicate this fact by setting the ``admin_order_field``
       attribute of the item.
-      
+
       For example::
-      
+
         class Person(models.Model):
             first_name = models.CharField(maxlength=50)
             color_code = models.CharField(maxlength=6)
@@ -1325,7 +1325,7 @@ A few special cases to note about ``list_display``:
                 return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name)
             colored_first_name.allow_tags = True
             colored_first_name.admin_order_field = 'first_name'
-    
+
       The above will tell Django to order by the ``first_name`` field when
       trying to sort by ``colored_first_name`` in the admin.
 
@@ -1758,16 +1758,38 @@ slightly violates the DRY principle: the URL for this object is defined both
 in the URLConf file and in the model.
 
 You can further decouple your models from the URLconf using the ``permalink``
-decorator. This decorator is passed the view function and any parameters you
-would use for accessing this instance directly. Django then works out the
-correct full URL path using the URLconf. For example::
+decorator. This decorator is passed the view function, a list of positional
+parameters and (optionally) a dictionary of named parameters. Django then
+works out the correct full URL path using the URLconf, substituting the
+parameters you have given into the URL. For example, if your URLconf
+contained a line such as::
+
+    (r'^/people/(\d+)/$', 'people.views.details'),
+
+...your model could have a ``get_absolute_url`` method that looked like this::
 
     from django.db.models import permalink
 
     def get_absolute_url(self):
-        return ('people.views.details', str(self.id))
+        return ('people.views.details', [str(self.id)])
     get_absolute_url = permalink(get_absolute_url)
 
+Similarly, if you had a URLconf entry that looked like::
+
+    (r'/archive/(?P<year>\d{4})/(?P<month>\d{1,2})/(?P<day>\d{1,2})/$', archive_view)
+
+...you could reference this using ``permalink()`` as follows::
+
+    def get_absolute_url(self):
+        return ('archive_view', (), {
+            'year': self.created.year,
+            'month': self.created.month,
+            'day': self.created.day})
+    get_absolute_url = permalink(get_absolute_url)
+
+Notice that we specify an empty sequence for the second argument in this case,
+because we only want to pass keyword arguments, not named arguments.
+
 In this way, you're tying the model's absolute URL to the view that is used
 to display it, without repeating the URL information anywhere. You can still
 use the ``get_absolute_url`` method in templates, as before.