diff -r de025ff8ba30 -r 92e33e6b9e92 src/source/howto-renderer.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/source/howto-renderer.rst	Wed May 23 14:24:30 2018 +0200
@@ -0,0 +1,114 @@
+.. _rendererhowto:
+
+
+How to create a new Renderer?
+=============================
+
+**Renderer** are the layout of the utility data content
+
+
+1. Create a Renderer
+''''''''''''''''''''
+
+The simplest is to create a new class that inherits from the existing **Renderer**, to modify this template and
+to define a new adapter name. You must also override the label to distinguish rendering modes in the ZMI.
+
+
+
+.. code-block:: python
+    :linenos:
+
+    # New custom contact paragraph renderer
+
+    @adapter_config(name='custom', context=(IContactParagraph, IPyAMSLayer), provides=IContentRenderer)
+    @template_config(template='templates/contact-custom.pt', layer=IPyAMSLayer)
+    class ContactParagraphCustomRenderer(ContactParagraphDefaultRenderer):
+        """Context paragraph custom renderer"""
+
+        label = _("Custom contact renderer")
+        settings_interface = IContactParagraphDefaultRendererSettings
+
+In this example the new renderer inherit of :py:class:`ContactParagraphDefaultRenderer`, we have defined a **label** (line 8)
+and associated an **settings_interface** (line 9)
+
+We have declared this adapter with 'custom' name, it takes :py:class:`IContactParagraph`, :py:class:`IPyAMSLayer` as context
+and provides :py:class:`IContentRenderer` interface.
+
+Using ``@template_config()`` decorator, the renderer can be displayed in html container according to the template
+
+
+2. Define a Renderer settings
+'''''''''''''''''''''''''''''
+
+In the previous point, we did not change the settings interface of the renderer.
+However, we can define a new settings interface for the new renderer, for that we start by creating an interface
+
+a) Create interface
+"""""""""""""""""""
+
+
+.. code-block:: python
+
+
+    class ICustomRendererSettings(Interface):
+        """Custom renderer settings interface"""
+
+
+        display_photo = Bool(title=_("Show photo?"),
+                             description=_("Display contact photo"),
+                             required=True,
+                             default=True)
+
+        display_phone_number = Bool(title=_("Show phone number?"),
+                             description=_("Display the phone number of the contact?"),
+                             required=True,
+                             default=True)
+
+        can_display_photo = Attribute("Check if photo can be displayed")
+
+
+
+b) Implement interface
+""""""""""""""""""""""
+
+.. code-block:: python
+
+
+    @implementer(ICustomRendererSettings)
+    class CustomRendererSettings(Persistent, Location):
+        """Custom renderer settings"""
+
+        display_photo = FieldProperty(ICustomRendererSettings['display_photo'])
+        display_phone_number = FieldProperty(ICustomRendererSettings['display_phone_number'])
+
+        @property
+        def can_display_photo(self):
+            contact = IContactParagraph(self.__parent__)
+            if not contact.photo:
+                return False
+            return self.display_photo
+
+
+
+c) Create the adapter
+"""""""""""""""""""""
+
+.. code-block:: python
+
+    CUSTOM_RENDERER_SETTINGS_KEY = 'pyams_content.contact.renderer:custom'
+
+    @adapter_config(context=IContactParagraph, provides=ICustomRendererSettings)
+    def custom_renderer_settings_factory(context):
+        """Contact paragraph default renderer settings factory"""
+        return get_annotation_adapter(context, CUSTOM_RENDERER_SETTINGS_KEY,
+                                      CustomRendererSettings)
+
+
+d) Add settings interface renderer
+""""""""""""""""""""""""""""""""""
+
+.. code-block:: python
+        settings_interface = ICustomRendererSettings
+
+By linking a setting_interface with renderer you can use directly in the template, setting attributs
+