15 

    16 .. _traverser:

    17 

    18 PyAMS namespace traverser

    19 -------------------------

    20 

    21 

    22 PyAMS_utils provide a custom URL traverser, defined in package :py:mod:`pyams_utils.traversing`.

    23 

    24 The :py:class:`NamespaceTraverser <pyams_utils.traversing.NamespaceTraverser>` is a custom traverser based on default

    25 Pyramid's *ResourceTreeAdapter*, but it adds the ability to use *namespaces*. Inherited from *Zope3* concept, a

    26 namespace is a resource path element starting with the « *++* » characters, like this:

    27 

    28 .. code-block:: none

    29 

    30     http://localhost:5432/folder/content/++ns++argument/@@view.html

    31 

    32 In this sample, *ns* is the namespace name. When the traverser detects a namespace, it looks for several named

    33 adapters (or multi-adapters) to the :py:class:`ITraversable <zope.traversing.interfaces.ITraversable>` interface

    34 defined in *zope.traversing* package. Adapters lookup with name *ns* is done for the current *context* and *request*,

    35 then only for the context and finally for the request, in this order. If a traversing adapter is found, it's

    36 :py:func:`traverse` method is called, with the *attr* value as first argument, and the rest of the traversal stack

    37 as second one.

    38 

    39 This is for example how a custom *etc* namespace traverser is defined:

    40 

    41 .. code-block:: python

    42 

    43     from pyams_utils.interfaces.site import ISiteRoot

    44     from zope.traversing.interfaces import ITraversable

    45 

    46     from pyams_utils.adapter import adapter_config, ContextAdapter

    47 

    48     @adapter_config(name='etc', context=ISiteRoot, provides=ITraversable)

    49     class SiteRootEtcTraverser(ContextAdapter):

    50         """Site root ++etc++ namespace traverser"""

    51 

    52         def traverse(self, name, furtherpath=None):

    53             if name == 'site':

    54                 return self.context.getSiteManager()

    55             raise NotFound

    56 

    57 By using an URL like '++etc++site' on your site root, you can then get access to your local site manager.

    58 

    59 *argument* is not mandatory for the namespace traverser. If it is not provided, the *traverse* method is called with

    60 an empty string (with is a default adapter name) as first argument.

    61 

    62 Several PyAMS components use custom traversal adapters. For example, getting thumbnails from an image is done

    63 through a traversing adapter, which results in nicer URLs than when using classic URLs with arguments...

    64