# HG changeset patch # User Damien Correia # Date 1527870429 -7200 # Node ID efe71f19939cca812c6599c72d4fa855a66f17b7 # Parent a3a8642a31b2a213524d9b55c232df085c993966 Updated Renderer doc diff -r a3a8642a31b2 -r efe71f19939c src/source/howto-renderer.rst --- 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