1 .. _appextend:

     2 

     3 How to create a new Portlet ?

     4 -----------------------------

     5 

     6 **Portlets** are pluggable user interface software components that are managed and displayed in a web portal,

     7 for example an enterprise portal or a web CMS. A portlet can aggregate (integrate) and personalize content from

     8 different sources within a web page. A portlet responds to requests from a web client with and generates dynamic content.

     9 (*reference:* `Wiki portlet`_)

    10 

    11 .. _`wiki portlet`: https://en.wikipedia.org/wiki/Portlet

    12 

    13 

    14 **Pyams Portal** provides predefined portlets that to compose and organize the structure of a website.

    15 

    16 1. Define a Portlet setting

    17 '''''''''''''''''''''''''''

    18 

    19 Portlet setting interface are defined in ``interfaces.py``, you can use IPortletSettings or extend the interface

    20 by adding an additional properties for example:

    21 

    22 .. code-block:: python

    23 

    24     from zope.schema import Text

    25 

    26     class INewPortletSettings(IPortletSettings):

    27 

    28         comment = Text(title=_("Comment"),

    29                    required=True,

    30                    default=True)

    31 

    32 PortletSetting component does what IPortletSettings describes. This is usually referred to as the implementation

    33 of IPortletSettings.

    34 

    35 .. code-block:: python

    36 

    37     @implementer(IPortletSettings)

    38     class ImagePortletSettings(PortletSettings):

    39         """Image portlet settings"""

    40 

    41         _image = FileProperty(IImagePortletSettings['image'])

    42 

    43         @property

    44         def image(self):

    45             return self._image

    46 

    47         @image.setter

    48         def image(self, value):

    49             self._image = value

    50             if (value is not None) and (value is not DELETED_FILE):

    51                 alsoProvides(self._image, IResponsiveImage)

    52 

    53 

    54 

    55 2. Create Portlet

    56 '''''''''''''''''

    57 

    58 The Porltet component is a utility, it implement the IPortlet interface and it registered by the portlet_config adapter

    59 

    60 To register a new portlet you must specify the settings_class associated

    61 

    62 .. code-block:: python

    63 

    64     @portlet_config(permission=VIEW_PERMISSION)

    65     class ImagePortlet(Portlet):

    66         """Image portlet"""

    67 

    68         name = IMAGE_PORTLET_NAME

    69         label = _("Image")

    70 

    71         toolbar_image = None

    72         toolbar_css_class = 'fa fa-fw fa-2x fa-picture-o'

    73 

    74         settings_class = ImagePortletSettings

    75 

    76 

    77 

    78 4. Create HTML template

    79 '''''''''''''''''''''''

    80 

    81 

    82 .. code-block:: genshi

    83 

    84     <span>${view.settings.comment}</span>

    85 

    86 

    87 

    88 5. Renderer

    89 '''''''''''

    90 

    91 .. code-block:: python

    92 

    93     @adapter_config(context=(IPortalContext, IPyAMSLayer, Interface, IImagePortletSettings), provides=IPortletRenderer)

    94     @template_config(template='image.pt', layer=IPyAMSLayer)

    95     class ImagePortletRenderer(PortletRenderer):

    96         """Image portlet renderer"""

    97 

    98         label = _("Responsive image renderer")

    99 

   100 

   101 

   102 6. Zmi integration module

   103 '''''''''''''''''''''''''

   104 

   105 .. code-block:: python

   106 

   107     @pagelet_config(name='properties.html', context=IImagePortletSettings, request_type=IPyAMSLayer,

   108                     permission=VIEW_SYSTEM_PERMISSION)

   109     class ImagePortletSettingsEditor(PortletSettingsEditor):

   110         """Image portlet settings editor"""

   111 

   112         settings = IImagePortletSettings

   113 

   114 

   115