From 4e4c10bc6155d4a0eab117ad4c8afdf53853f5e0 Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Thu, 10 Jul 2014 17:30:39 -0400 Subject: [PATCH] Removed docs for @permalink decorator. It's been marked as "not recommended" since 1.6. Anyone still using it may refer to older versions of the docs. --- docs/ref/models/instances.txt | 87 ----------------------------------- 1 file changed, 87 deletions(-) diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index c04f1a44b0..f5147090b4 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -690,93 +690,6 @@ in ``get_absolute_url()`` and have all your other code call that one place. are using unicode strings containing characters outside the ASCII range at all. -The ``permalink`` decorator -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. warning:: - - The ``permalink`` decorator is no longer recommended. You should use - :func:`~django.core.urlresolvers.reverse` in the body of your - ``get_absolute_url`` method instead. - -In early versions of Django, there wasn't an easy way to use URLs defined in -URLconf file inside :meth:`~django.db.models.Model.get_absolute_url`. That -meant you would need to define the URL both in URLConf and -:meth:`~django.db.models.Model.get_absolute_url`. The ``permalink`` decorator -was added to overcome this DRY principle violation. However, since the -introduction of :func:`~django.core.urlresolvers.reverse` there is no -reason to use ``permalink`` any more. - -.. function:: permalink() - -This decorator takes the name of a URL pattern (either a view name or a URL -pattern name) and a list of position or keyword arguments and uses the URLconf -patterns to construct the correct, full URL. It returns a string for the -correct URL, with all parameters substituted in the correct positions. - -The ``permalink`` decorator is a Python-level equivalent to the :ttag:`url` -template tag and a high-level wrapper for the -:func:`~django.core.urlresolvers.reverse` function. - -An example should make it clear how to use ``permalink()``. Suppose your URLconf -contains a line such as:: - - (r'^people/([0-9]+)/$', 'people.views.details'), - -...your model could have a :meth:`~django.db.models.Model.get_absolute_url` -method that looked like this:: - - from django.db import models - - @models.permalink - def get_absolute_url(self): - return ('people.views.details', [str(self.id)]) - -Similarly, if you had a URLconf entry that looked like:: - - (r'/archive/(?P[0-9]{4})/(?P[0-9]{2})/(?P[0-9]{2})/$', archive_view) - -...you could reference this using ``permalink()`` as follows:: - - @models.permalink - def get_absolute_url(self): - return ('archive_view', (), { - 'year': self.created.year, - 'month': self.created.strftime('%m'), - 'day': self.created.strftime('%d')}) - -Notice that we specify an empty sequence for the second parameter in this case, -because we only want to pass keyword parameters, not positional ones. - -In this way, you're associating the model's absolute path with the view that is -used to display it, without repeating the view's URL information anywhere. You -can still use the :meth:`~django.db.models.Model.get_absolute_url()` method in -templates, as before. - -In some cases, such as the use of generic views or the re-use of custom views -for multiple models, specifying the view function may confuse the reverse URL -matcher (because multiple patterns point to the same view). For that case, -Django has :ref:`named URL patterns `. Using a named URL -pattern, it's possible to give a name to a pattern, and then reference the name -rather than the view function. A named URL pattern is defined by replacing the -pattern tuple by a call to the ``url`` function):: - - from django.conf.urls import url - - url(r'^people/([0-9]+)/$', 'blog_views.generic_detail', name='people_view'), - -...and then using that name to perform the reverse URL resolution instead -of the view name:: - - from django.db import models - - @models.permalink - def get_absolute_url(self): - return ('people_view', [str(self.id)]) - -More details on named URL patterns are in the :doc:`URL dispatch documentation -`. - Extra instance methods ======================