--- 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