docs/source/traverser.rst
changeset 125 985534bc6ab9
parent 124 53dc81f933ed
child 126 e2aeba0dd99c
equal deleted inserted replaced
124:53dc81f933ed 125:985534bc6ab9
     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...