From f5f23793e34324552f323725fa25f09b34380acc Mon Sep 17 00:00:00 2001 From: Rudolf Olah Date: Thu, 27 Jun 2013 16:30:24 -0400 Subject: [PATCH 1/3] #955 updated documentation for overriding `routes` attribute in Router sub-classes --- docs/api-guide/routers.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md index b74b6e13b..feff0fbfe 100644 --- a/docs/api-guide/routers.md +++ b/docs/api-guide/routers.md @@ -98,7 +98,7 @@ As with `SimpleRouter` the trailing slashs on the URL routes can be removed by s Implementing a custom router isn't something you'd need to do very often, but it can be useful if you have specific requirements about how the your URLs for your API are strutured. Doing so allows you to encapsulate the URL structure in a reusable way that ensures you don't have to write your URL patterns explicitly for each new view. -The simplest way to implement a custom router is to subclass one of the existing router classes. The `.routes` attribute is used to template the URL patterns that will be mapped to each viewset. +The simplest way to implement a custom router is to subclass one of the existing router classes. The `.routes` attribute is used to template the URL patterns that will be mapped to each viewset. The `.routes` attribute is a list of `Route` named tuples. ## Example @@ -109,10 +109,18 @@ The following example will only route to the `list` and `retrieve` actions, and A router for read-only APIs, which doesn't use trailing suffixes. """ routes = [ - (r'^{prefix}$', {'get': 'list'}, '{basename}-list'), - (r'^{prefix}/{lookup}$', {'get': 'retrieve'}, '{basename}-detail') + Route(url=r'^{prefix}$', + mapping={'get': 'list'}, + name='{basename}-list', + initkwargs={}), + Route(url=r'^{prefix}/{lookup}$', + mapping={'get': 'retrieve'}, + name='{basename}-detail', + initkwargs={}) ] +The `SimpleRouter` class provides another example of setting the `.routes` attribute. + ## Advanced custom routers If you want to provide totally custom behavior, you can override `BaseRouter` and override the `get_urls(self)` method. The method should insect the registered viewsets and return a list of URL patterns. The registered prefix, viewset and basename tuples may be inspected by accessing the `self.registry` attribute. From e460180a4dd86ff74cc786aabfeeba1c31d17413 Mon Sep 17 00:00:00 2001 From: Rudolf Olah Date: Tue, 2 Jul 2013 13:20:25 -0400 Subject: [PATCH 2/3] #955 updated router docs with more information on the `Route` named tuple and its parameters. --- docs/api-guide/routers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md index feff0fbfe..1fb15fae3 100644 --- a/docs/api-guide/routers.md +++ b/docs/api-guide/routers.md @@ -100,6 +100,18 @@ Implementing a custom router isn't something you'd need to do very often, but it The simplest way to implement a custom router is to subclass one of the existing router classes. The `.routes` attribute is used to template the URL patterns that will be mapped to each viewset. The `.routes` attribute is a list of `Route` named tuples. +The arguments to the `Route` named tuple are: + +* `url`: The URL to be routed. There are format arguments available, defined in `SimpleRouter.get_urls`: + * `prefix` - The URL prefix to use for this set of routes. + * `lookup` - The lookup field used to match against a single instance. + * `trailing_slash` - the value of `.trailing_slash`. +* `mapping`: Mapping of HTTP method names to the object's methods +* `name`: The name of the URL as used in `reverse` calls. There are format arguments available, defined in `SimpleRouter.get_urls`: + * `basename` - The base to use for the URL names that are created. +* `initkwargs`: Any additional arguments to the view. + * `suffix` - reserved for identifying the viewset type, used when generating the breadcrumb links, e.g. `AccountViewSet` becomes `Account List` when `suffix='List'`. + ## Example The following example will only route to the `list` and `retrieve` actions, and does not use the trailing slash convention. From e969c96aa020047becd7a759a80e2fdc46b21170 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 2 Jul 2013 22:08:40 +0100 Subject: [PATCH 3/3] Added @omouse for work on #955 - thanks! :) --- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 94760c74b..e6fb9134e 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -144,6 +144,7 @@ The following people have helped make REST framework great. * David Sanders - [davesque] * Philip Douglas - [freakydug] * Igor Kalat - [trwired] +* Rudolf Olah - [omouse] Many thanks to everyone who's contributed to the project. @@ -324,3 +325,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [davesque]: https://github.com/davesque [freakydug]: https://github.com/freakydug [trwired]: https://github.com/trwired +[omouse]: https://github.com/omouse