From 0a6a26ca36f6aff7d03b438eef57f6b8d17123e9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 17 Feb 2012 08:55:45 -0500 Subject: docs fixes --- docs/narr/resources.rst | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) (limited to 'docs/narr/resources.rst') diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 83734be9f..a24c44f29 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -303,13 +303,22 @@ The ``__resource_url__`` hook is passed two arguments: ``request`` and two keys: ``physical_path`` - The "physical path" computed for the resource, as defined by - ``pyramid.traversal.resource_path(resource)``. + A string representing the "physical path" computed for the resource, as + defined by ``pyramid.traversal.resource_path(resource)``. It will begin + and end with a slash. ``virtual_path`` - The "virtual path" computed for the resource, as defined by - :ref:`virtual_root_support`. This will be identical to the physical path - if virtual rooting is not enabled. + A string representing the "virtual path" computed for the resource, as + defined by :ref:`virtual_root_support`. This will be identical to the + physical path if virtual rooting is not enabled. It will begin and end + with a slash. + +``app_url`` + A string representing the application URL generated during + ``request.resource_url``. It will not end with a slash. It represents a + potentially customized URL prefix, containing potentially custom scheme, + host and port information passed by the user to ``request.resource_url``. + It should be preferred over use of ``request.application_url``. The ``__resource_url__`` method of a resource should return a string representing a URL. If it cannot override the default, it should return @@ -322,16 +331,16 @@ Here's an example ``__resource_url__`` method. class Resource(object): def __resource_url__(self, request, info): - return request.application_url + info['virtual_path'] + return info['app_url'] + info['virtual_path'] The above example actually just generates and returns the default URL, which -would have been what was returned anyway, but your code can perform arbitrary -logic as necessary. For example, your code may wish to override the hostname -or port number of the generated URL. +would have been what was generated by the default ``resource_url`` machinery, +but your code can perform arbitrary logic as necessary. For example, your +code may wish to override the hostname or port number of the generated URL. Note that the URL generated by ``__resource_url__`` should be fully qualified, should end in a slash, and should not contain any query string or -anchor elements (only path elements) to work best with +anchor elements (only path elements) to work with :meth:`~pyramid.request.Request.resource_url`. .. index:: -- cgit v1.2.3