1 .. _traverser:

     2 

     3 PyAMS namespace traverser

     4 =========================

     5 

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

     7 

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

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

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

    11 

    12 .. code-block:: none

    13 

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

    15 

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

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

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

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

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

    21 as second one.

    22 

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

    24 

    25 .. code-block:: python

    26 

    27     from pyams_utils.interfaces.site import ISiteRoot

    28     from zope.traversing.interfaces import ITraversable

    29 

    30     from pyams_utils.adapter import adapter_config, ContextAdapter

    31 

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

    33     class SiteRootEtcTraverser(ContextAdapter):

    34         """Site root ++etc++ namespace traverser"""

    35 

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

    37             if name == 'site':

    38                 return self.context.getSiteManager()

    39             raise NotFound

    40 

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

    42 

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

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

    45 

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

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