From 013c4bc7b3337bc50794300d7cb8502d191f4490 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 30 Apr 2009 03:57:57 +0000 Subject: Make ModelGraphTraverser assume that all traversed objects provide ILocation. Make WrappingModelGraphTraverser assume that *no* traversed objects provide ILocation. This makes it unnecessary to explain why the root object in a WrappingModelGraphTraverser setup needs to supply the ILocation interface. Now it doesn't. --- docs/narr/models.rst | 87 +++++++++++++++++++++++++++++----------------------- 1 file changed, 48 insertions(+), 39 deletions(-) (limited to 'docs') diff --git a/docs/narr/models.rst b/docs/narr/models.rst index e9eddf39b..624a29002 100644 --- a/docs/narr/models.rst +++ b/docs/narr/models.rst @@ -92,29 +92,49 @@ instance nodes in the graph: Location-Aware Model Instances ------------------------------ -For :mod:`repoze.bfg` security and convenience URL-generation -functions to work properly against a model instance graph, all nodes -in the graph should have two attributes:: ``__parent__`` and -``__name__``. The ``__parent__`` attribute should be a reference to -the node's parent model instance in the graph. The ``__name__`` -attribute should be the name that a node's parent refers to the node -by via ``__getitem__``. - -If you choose not to manage the ``__name__`` and ``__parent__`` -attributes of your models "by hand", :mod:`repoze.bfg`` is willing to -help you do this. If your "root" node claims it implements the -interface ``repoze.bfg.interfaces.ILocation``, you don't need to -manage these attributes by hand. During :term:`traversal`, if the -root node says it implements the ``ILocation`` :term:`interface`, -:mod:`repoze.bfg` will wrap each child in a ``LocationProxy`` which -will dynamically assign a ``__name__`` and a ``__parent__`` to it, -recursively. +In order for :mod:`repoze.bfg` location, security, URL-generation, and +traversal functions (such as the functions exposed in +:ref:`location_module`, :ref:`traversal_module`, and :ref:`url_module` +as well as certain functions in :ref:`security_module` ) to work +properly against a instances in a model graph, all nodes in the graph +must be "location-aware". This means they must have two attributes: +``__parent__`` and ``__name__``. The ``__parent__`` attribute should +be a reference to the node's parent model instance in the graph. The +``__name__`` attribute should be the name that a node's parent refers +to the node via ``__getitem__``. The ``__parent__`` of the root +object should be ``None`` and its ``__name__`` should be the empty +string. For instance: + +.. code-block:: python + + class MyRootObject(object): + __name__ = '' + __parent__ = None + +A node returned from the root item's ``__getitem__`` method should +have a ``__parent__`` attribute that is a reference to the root +object, and its ``__name__`` attribute should match the name by which +it is are reachable via the root object's ``__getitem__``. *That* +object's ``__getitem__`` should return objects that have a +``__parent__`` attribute that points at that object, and +``__getitem__``-returned objects should have a ``__name__`` attribute +that matches the name by which they are retrieved via ``__getitem__``, +and so on. .. note:: - In order to use this feature, you must register the - ``WrappingModelGraphTraverser`` as the traversal policy, rather - than the standard ``ModelGraphTraverser``. E.g., your application - will need to have the following in its ``configure.zcml``:: + + If you'd rather not manage the ``__name__`` and ``__parent__`` + attributes of your models "by hand", :mod:`repoze.bfg`` can help you + do this. + + In order to use this helper feature, you must first register the + ``WrappingModelGraphTraverser`` as the traversal policy, rather than + the default ``ModelGraphTraverser``. To register the + ``WrappingModelGraphTraverser`` as the traversal policy, your + application will need to have the following in its + ``configure.zcml`` file: + + .. code-block:: xml - -If you choose to make use of the location-based dynamic assignment of -``__parent__`` and ``__name__``, the root node must have a -``__parent__`` that is ``None``, a ``__name__`` with any value, and it -must provide the ``repoze.bfg.interfaces.ILocation`` interface. The -easiest way to do this is to claim that the class representing the -root node ``implements(ILocation)``: - -.. code-block:: python - :linenos: - - from repoze.bfg.interfaces import ILocation - from zope.interface import implements - - class MyRootObject(object): - implements(ILocation) - __parent__ = None - __name__ = '' + If this statement is made in ZCML, you don't need to manage the + ``__parent__`` and ``__name__`` attributes on graph objects "by + hand". Instead, as necessary, during traversal :mod:`repoze.bfg` + will wrap each object in a ``LocationProxy`` which will dynamically + assign a ``__name__`` and a ``__parent__`` to the traversed object + (based on the last traversed object and the name supplied to + ``__getitem__``). :mod:`repoze.bfg` API Functions That Act Against Models ------------------------------------------------------- -- cgit v1.2.3