From ed3d787edaecdaaece247d7b0f09b9ed6fe3be84 Mon Sep 17 00:00:00 2001 From: Malcolm Tredinnick Date: Sat, 17 Feb 2007 05:51:45 +0000 Subject: [PATCH] Fixed #2568 -- Added documentation for the permalink() decorator. Based on a patch from Joeboy. git-svn-id: http://code.djangoproject.com/svn/django/trunk@4535 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/model-api.txt | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/docs/model-api.txt b/docs/model-api.txt index 8abd88f7ec..26b7f6659e 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -1721,11 +1721,30 @@ But this template code is good:: {{ object.name }} -(Yes, we know ``get_absolute_url()`` couples URLs to models, which violates the -DRY principle, because URLs are defined both in a URLconf and in the model. -This is a rare case in which we've intentionally violated that principle for -the sake of convenience. With that said, we're working on an even cleaner way -of specifying URLs in a more DRY fashion.) +``permalink`` +------------- + +** New in Django development version. ** + +The problem with the way we wrote ``get_absolute_url()`` above is that it +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 URL configuration using the +``permalink`` function. This function acts as a decorator and 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 URL +configuration file. For example:: + + from django.db.models import permalink + + def get_absolute_url(self): + return ('people.views.details', str(self.id)) + get_absolute_url = permalink(get_absolute_url) + +In this way, you are tying the model's absolute URL to the view that is used +to display it, without repeating the URL information anywhere. You still use +the ``get_absolute_url`` method in templates, as before. Executing custom SQL --------------------