--- a/src/source/dev_guide/howto-adapter.rst Fri Dec 21 15:52:29 2018 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,180 +0,0 @@
-.. _adapterhowto:
-
-
-How to define an annotations adapter?
-=====================================
-
-Adapters are important concepts of ZCA and PyAMS framework. If you don't know what are adapters, see :ref:`zca`.
-
-
-What are annotations?
-+++++++++++++++++++++
-
-When an adapter have to add persistent attributes to a persistent class, it can add these attributes directly into
-persistent instances. But this way can lead to conflicts when several adapters want to use the same attribute name for
-different kinds of information.
-
-Annotations are an elegant way to handle this use case: they are based on a BTree which is stored into a
-specific instance attribute (*__annotations__*). Any adapter can then use this dictionary to store it's own
-informations, using it's own namespace as dictionary key.
-
-ZODB browser allows you to display existing annotations:
-
-.. image:: ../_static/annotations-1.png
-
-This example displays several annotations, each using it's own namespace:
-
-.. image:: ../_static/annotations-2.png
-
-
-Designing interfaces
-++++++++++++++++++++
-
-The first step with ZCA is to design your interfaces.
-
-The are going to base our example on PyAMS_content 'paragraphs' component: a content class is marked as a
-*paragraphs container target*, a class that can store paragraphs. But the real storage of paragraphs is done by
-another *container* class:
-
-.. code-block:: python
- :linenos:
-
- from zope.annotation.interfaces import IAttributeAnnotatable
- from zope.containers.constraints import containers, contains
-
-
- class IBaseParagraph(Interface):
- """Base paragraph interface"""
-
- containers('.IParagraphContainer')
-
-
- class IParagraphContainer(IOrderedContainer):
- """Paragraphs container"""
-
- contains(IBaseParagraph)
-
-
- class IParagraphContainerTarget(IAttributeAnnotatable):
- """Paragraphs container marker interface"""
-
-
- PARAGRAPH_CONTAINER_KEY = 'pyams_content.paragraph'
-
-
-- line 5 to 8: :class:`IBaseParagraph` is the base interface for all paragraphs; constraint implies that paragraphs
- can only be stored in a container implementing :class:`IParagraphContainer` interface.
-- line 11 to 14: :class:`IParagraphContainer` is the base interface for paragraphs containers; constraint implies that
- such a container can only contain objects implementing :class:`IBaseParagraph` interface.
-- line 17 to 18: :class:`IParagraphContainerTarget` is only a *marker* interface which doesn't provide any method or
- attribute; it only inherits from :class:`IAttributeAnnotatable`, which implies that classes implementing this
- interface allows other classes to add informations as annotations through a dedicated *__annotations__* attribute.
-- line 21: this is the key which will be used to store our annotation.
-
-
-Creating persistent classes
-+++++++++++++++++++++++++++
-
-The first step is to declare that a given content class can store paragraphs:
-
-.. code-block:: python
- :linenos:
-
- from pyams_content.component.paragraph.interfaces import IParagraphContainerTarget
- from zope.interface import implementer
-
- @implementer(IParagraphContainerTarget)
- class WfNewsEvent(WfSharedContent):
- """News event class"""
-
-Here we just say "Well, I'm a shared content, and I'm OK to store paragraphs!".
-
-So we can design the paragraphs container class. It's this class which will *really* store the paragraphs:
-
-.. code-block:: python
- :linenos:
-
- @implementer(IParagraphContainer)
- class ParagraphContainer(BTreeOrderedContainer):
- """Paragraphs container"""
-
-The paragraphs container class inherits from a :class:`BTreeOrderedContainer` and implements
-:class:`IParagraphContainer`.
-
-The last operation is to create the adapter, which is the *glue* between the *target* class and the paragraphs
-container:
-
-.. code-block:: python
- :linenos:
-
- from pyams_utils.adapter import adapter_config, get_annotation_adapter
-
- @adapter_config(context=IParagraphContainerTarget, provides=IParagraphContainer)
- def paragraph_container_factory(target):
- """Paragraphs container factory"""
- return get_annotation_adapter(target,
- PARAGRAPH_CONTAINER_KEY,
- ParagraphContainer,
- name='++paras++')
-
-PyAMS provides a shortcut to create an annotation adapter in :func:`pyams_utils.adapter.get_annotation_adapter`.
-It's mandatory arguments are:
-
-- **context** (line 6): the context to which the adapter is applied
-- **key** (line 7): the string key used to access and store context's annotations
-- **factory** (line 8): if the requested annotation is missing, a new one is created using this factory (which can be a class or
- a function)
-
-Optional arguments are:
-
-- **markers** (None by default): if set, should be a list of marker interfaces which will be assigned to object
- created by the factory
-- **notify**: if *True* (default), an :class:`ObjectCreatedEvent` event is notified on object creation
-- **locate**: if *True* (default), context is set as *parent* of created object
-- **parent**: if *locate* is True and if *parent* is set, this is the object to which the new object should be *parented*
- instead of initial context
-- **name** (None by default): some objects need to be traversed, especially when you have to be able to access them through an URL; this
- is the name given to created object.
-
-
-Using your adapter
-++++++++++++++++++
-
-Starting from your *content* object, it's then very simple to access to the paragraphs container:
-
-.. code-block:: python
- :linenos:
-
- event = WfNewsEvent()
- paragraphs_container = IParagraphContainer(event, None)
-
-And that's it! From now I can get access to all paragraphs associated with my initial content!!
-
-
-Managing traversal
-++++++++++++++++++
-
-As said before, sometimes you have to be able to *traverse* from an initial content to a given sub-content
-managed by an adapter.
-
-PyAMS defines a custom :class:`pyams_utils.traversing.NamespaceTraverser`: when a request traversing subpath is
-starting with '++' characters, it is looking for a named traverser providing :class:`ITraversable` interface
-to the last traversed object.
-
-.. code-block:: python
- :linenos:
-
- @adapter_config(name='paras', context=IParagraphContainerTarget, provides=ITraversable)
- class ParagraphContainerNamespace(ContextAdapter):
- """++paras++ namespace adapter"""
-
- def traverse(self, name, furtherpath=None):
- return IParagraphContainer(self.context)
-
-- line 1: the adapter is named "paras"; this is matching the *++paras++* name which was given to our annotation adapter
-- line 2: the adapter is just a simple context adapter, so inheriting from :class:`pyams_utils.adapter.ContextAdapter`
-- lines 5 to 6: the *traverse* method is used to access the adapted content; if a name like "++ns++value" is given
- to an adapted object, the "value" part is given as *name" argument.
-
-From now, as soon as an URL like "/mycontent/++paras++/" will be used, you will get access to the paragraphs container.
-This is a standard BTree container, so will get access to it's sub-objects by key.