diff -r 949d496c4e96 -r 60a1fbdbbed3 src/source/appextend.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/source/appextend.rst	Tue May 15 18:31:37 2018 +0200
@@ -0,0 +1,115 @@
+.. _appextend:
+
+How to create a new Portlet ?
+-----------------------------
+
+**Portlets** are pluggable user interface software components that are managed and displayed in a web portal,
+for example an enterprise portal or a web CMS. A portlet can aggregate (integrate) and personalize content from
+different sources within a web page. A portlet responds to requests from a web client with and generates dynamic content.
+(*reference:* `Wiki portlet`_)
+
+.. _`wiki portlet`: https://en.wikipedia.org/wiki/Portlet
+
+
+**Pyams Portal** provides predefined portlets that to compose and organize the structure of a website.
+
+1. Define a Portlet setting
+'''''''''''''''''''''''''''
+
+Portlet setting interface are defined in ``interfaces.py``, you can use IPortletSettings or extend the interface
+by adding an additional properties for example:
+
+.. code-block:: python
+
+    from zope.schema import Text
+
+    class INewPortletSettings(IPortletSettings):
+
+        comment = Text(title=_("Comment"),
+                   required=True,
+                   default=True)
+
+PortletSetting component does what IPortletSettings describes. This is usually referred to as the implementation
+of IPortletSettings.
+
+.. code-block:: python
+
+    @implementer(IPortletSettings)
+    class ImagePortletSettings(PortletSettings):
+        """Image portlet settings"""
+
+        _image = FileProperty(IImagePortletSettings['image'])
+
+        @property
+        def image(self):
+            return self._image
+
+        @image.setter
+        def image(self, value):
+            self._image = value
+            if (value is not None) and (value is not DELETED_FILE):
+                alsoProvides(self._image, IResponsiveImage)
+
+
+
+2. Create Portlet
+'''''''''''''''''
+
+The Porltet component is a utility, it implement the IPortlet interface and it registered by the portlet_config adapter
+
+To register a new portlet you must specify the settings_class associated
+
+.. code-block:: python
+
+    @portlet_config(permission=VIEW_PERMISSION)
+    class ImagePortlet(Portlet):
+        """Image portlet"""
+
+        name = IMAGE_PORTLET_NAME
+        label = _("Image")
+
+        toolbar_image = None
+        toolbar_css_class = 'fa fa-fw fa-2x fa-picture-o'
+
+        settings_class = ImagePortletSettings
+
+
+
+4. Create HTML template
+'''''''''''''''''''''''
+
+
+.. code-block:: genshi
+
+    <span>${view.settings.comment}</span>
+
+
+
+5. Renderer
+'''''''''''
+
+.. code-block:: python
+
+    @adapter_config(context=(IPortalContext, IPyAMSLayer, Interface, IImagePortletSettings), provides=IPortletRenderer)
+    @template_config(template='image.pt', layer=IPyAMSLayer)
+    class ImagePortletRenderer(PortletRenderer):
+        """Image portlet renderer"""
+
+        label = _("Responsive image renderer")
+
+
+
+6. Zmi integration module
+'''''''''''''''''''''''''
+
+.. code-block:: python
+
+    @pagelet_config(name='properties.html', context=IImagePortletSettings, request_type=IPyAMSLayer,
+                    permission=VIEW_SYSTEM_PERMISSION)
+    class ImagePortletSettingsEditor(PortletSettingsEditor):
+        """Image portlet settings editor"""
+
+        settings = IImagePortletSettings
+
+
+