src/source/howto-renderer.rst
branchdoc-dc
changeset 74 efe71f19939c
parent 72 3f403b9c4220
child 83 ee94d17857a4
--- a/src/source/howto-renderer.rst	Mon May 28 13:45:30 2018 +0200
+++ b/src/source/howto-renderer.rst	Fri Jun 01 18:27:09 2018 +0200
@@ -4,15 +4,18 @@
 How to create a new Renderer?
 =============================
 
-**Renderer** are the layout of the utility data content
+**Renderer** are the layout of the utility data content. A renderer combine un context, a skin and
+ a template to produce the front office html
+
+ To create new renderer you can override an already exist renderer or create a new one from scratch. Steps below
+ we will create a renderer for a `IContact` paragraph
 
 
-1. Create a Renderer
-''''''''''''''''''''
+1. Override 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.
-
+The simplest is to create a new class that inherits from the existing **Renderer**  and modify this template.
+After that all you have to define a new adapter name and a new label.
 
 
 .. code-block:: python
@@ -28,28 +31,33 @@
         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)
+
+In this example, we have defined an adapter named 'custom' with :py:class:`IContactParagraph`,
+:py:class:`IPyAMSLayer` as context and provides :py:class:`IContentRenderer` interface.
+
+Using ``@template_config()`` decorator, the renderer will be displayed in html container according to the template
 
-We have declared this adapter with 'custom' name, it takes :py:class:`IContactParagraph`, :py:class:`IPyAMSLayer` as context
-and provides :py:class:`IContentRenderer` interface.
+The new renderer inherit of :py:class:`ContactParagraphDefaultRenderer`, have a new **label** (line 8)
+and is associated an **settings_interface** (line 9)
 
-Using ``@template_config()`` decorator, the renderer can be displayed in html container according to the template
+.. tip::
+
+    You can override the template of a renderer easily with the function :py:func:`pyams_template.template.override_template`
+    It's takes the context and the new template path as params.
 
 
-2. Define a Renderer settings
-'''''''''''''''''''''''''''''
+2. Create a new Renderer from scratch
+-------------------------------------
 
-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
+We can define a new settings interface for the renderer, to do that we start by creating an interface
+
 
-a) Create setting interface
-"""""""""""""""""""""""""""
-
+a) Create setting interface for the renderer
+""""""""""""""""""""""""""""""""""""""""""""
 
 .. code-block:: python
 
-    class ICustomRendererSettings(Interface):
+    class IPhotoRendererSettings(Interface):
         """Custom renderer settings interface"""
 
 
@@ -58,27 +66,19 @@
                              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) Create an implemantation of the interface
-""""""""""""""""""""""""""""""""""""""""""""
+We have created an interface with two attributes *display_photo* and *can_display_photo*
+Then we create an implemantation of the interface
 
 .. code-block:: python
 
-
-    @implementer(ICustomRendererSettings)
-    class CustomRendererSettings(Persistent, Location):
+    @implementer(IPhotoRendererSettings)
+    class PhotoRendererSettings(Persistent, Location):
         """Custom renderer settings"""
 
-        display_photo = FieldProperty(ICustomRendererSettings['display_photo'])
-        display_phone_number = FieldProperty(ICustomRendererSettings['display_phone_number'])
+        display_photo = FieldProperty(IPhotoRendererSettings['display_photo'])
 
         @property
         def can_display_photo(self):
@@ -89,33 +89,44 @@
 
 
 
-c) Create an adapter for the render setting interface
+b) Create an adapter for the render setting interface
 """""""""""""""""""""""""""""""""""""""""""""""""""""
 
-With the wrapper :py:func:`@adapter_config()` we declare a new adapter.
+With :py:func:`@adapter_config()` we declare a new adapter that applies to a context and provide the interface of
+ renderer settings
 
 .. code-block:: python
 
-    CUSTOM_RENDERER_SETTINGS_KEY = 'pyams_content.contact.renderer:custom'
+    PHOTO_RENDERER_SETTINGS_KEY = 'pyams_content.contact.renderer:photo'
 
-    @adapter_config(context=IContactParagraph, provides=ICustomRendererSettings)
+    @adapter_config(context=IContactParagraph, provides=IPhotoRendererSettings)
     def custom_renderer_settings_factory(context):
         """Contact paragraph default renderer settings factory"""
-        return get_annotation_adapter(context, CUSTOM_RENDERER_SETTINGS_KEY,
+        return get_annotation_adapter(context, PHOTO_RENDERER_SETTINGS_KEY,
                                       CustomRendererSettings)
 
+
 In this example the settings interface adapter is defined with `IContactParagraph` as context
-and provide `ICustomRendererSettings`.
+and provide `IPhotoRendererSettings`.
+
 
-d) Add settings interface renderer
-""""""""""""""""""""""""""""""""""
 
-In the renderer definition:
+c) Create an adapter for the render interface
+"""""""""""""""""""""""""""""""""""""""""""""
 
 .. code-block:: python
-        settings_interface = ICustomRendererSettings
+
+    @adapter_config(context=(IContactParagraph, IPyAMSLayer), provides=IContentRenderer)
+    @template_config(template='templates/contact-custom.pt', layer=IPyAMSLayer)
+    class PhotoRenderer(BaseContentRenderer):
+        """Context paragraph custom renderer"""
+
+        label = _("Custom contact renderer")
+        settings_interface = IPhotoRendererSettings
 
 
+Add settings interface to the renderer `settings_interface = IPhotoRendererSettings`
+
 .. tip::
-    When a setting_interface is associated to a renderer, you can acces to `settings` attributs through the template
+    When a setting_interface is associated to a renderer, you can access to `settings` attributes through the template