1 .. _appextend: |
1 .. _appextend: |
2 |
2 |
3 How to create a new Portlet ? |
|
4 ----------------------------- |
|
5 |
3 |
6 **Portlets** are pluggable user interface software components that are managed and displayed in a web portal, |
4 Extending PyAMS |
7 for example an enterprise portal or a web CMS. A portlet can aggregate (integrate) and personalize content from |
5 =============== |
8 different sources within a web page. A portlet responds to requests from a web client and generates dynamic content |
|
9 (*reference:* `Wiki portlet`_). |
|
10 |
6 |
11 .. _`wiki portlet`: https://en.wikipedia.org/wiki/Portlet |
7 .. toctree:: |
|
8 :maxdepth: 1 |
12 |
9 |
13 |
10 howto-adapter |
14 **PyAMS Portal** provides the portal engine but only a very small set of predefined portlets that can be used to compose |
11 howto-portlet |
15 and organize the structure of a web page; additional portlets are provided by other packages, like |
|
16 :ref:`pyams_content`. |
|
17 |
|
18 |
|
19 1. Define portlet settings |
|
20 '''''''''''''''''''''''''' |
|
21 |
|
22 Portlet settings interface are defined in ``interfaces.py``, you can use :py:class:`pyams_portal.interfaces.IPortletSettings` |
|
23 or extend the interface by adding additional properties for example: |
|
24 |
|
25 .. code-block:: python |
|
26 |
|
27 from zope.schema import Text |
|
28 |
|
29 NEW_PORTLET_NAME = 'new.portlet' |
|
30 |
|
31 class INewPortletSettings(IPortletSettings): |
|
32 |
|
33 comment = Text(title=_("Comment"), |
|
34 required=True) |
|
35 |
|
36 |
|
37 A :py:class:`pyams_portal.portlet.PortletSettings` persistent subclass then implements what IPortletSettings describes: |
|
38 |
|
39 .. code-block:: python |
|
40 |
|
41 @implementer(INewPortletSettings) |
|
42 class NewPortletSettings(PortletSettings): |
|
43 """Portlet settings""" |
|
44 |
|
45 comment = FieldProperty(INewPortletSettings['comment']) |
|
46 |
|
47 |
|
48 2. Create Portlet |
|
49 ''''''''''''''''' |
|
50 |
|
51 The Portlet component is a utility, which implements the :py:class:`pyams_portal.interfaces.IPortlet` interface and is |
|
52 registered by the :py:func:`pyams_portal.portlet.portlet_config` decorator; |
|
53 |
|
54 .. code-block:: python |
|
55 |
|
56 @portlet_config(permission=VIEW_PERMISSION) |
|
57 class ImagePortlet(Portlet): |
|
58 """Image portlet""" |
|
59 |
|
60 name = NEW_PORTLET_NAME |
|
61 label = _("New portlet") |
|
62 |
|
63 toolbar_image = None |
|
64 toolbar_css_class = 'fa fa-fw fa-2x fa-picture-o' |
|
65 |
|
66 settings_class = NewPortletSettings |
|
67 |
|
68 |
|
69 Where: |
|
70 - **permission**: permission required to display this portlet content |
|
71 - **name**: internal name given to this portlet. This name must be unique between all portlets, so using your own |
|
72 namespace into this name is generally a good option! |
|
73 - **label**: user label given to this portlet |
|
74 - **toolbar_image**: URL of an image used to display portlet button into ZMI toolbar, if any |
|
75 - **toolbar_css_class**: CSS class used to display portlet button into ZMI toolbar, if any |
|
76 - **settings_class**: class used to store portlet settings. |
|
77 |
|
78 |
|
79 3. Create portlet settings edit form |
|
80 '''''''''''''''''''''''''''''''''''' |
|
81 |
|
82 Portlet settings have to be updated through management interface via a :py:class:`pyams_portal.zmi.portlet.PortletSettingsEditor` |
|
83 subform: |
|
84 |
|
85 .. code-block:: python |
|
86 |
|
87 @pagelet_config(name='properties.html', context=INewPortletSettings, layer=IPyAMSLayer, |
|
88 permission=VIEW_SYSTEM_PERMISSION) |
|
89 class NewPortletSettingsEditor(PortletSettingsEditor): |
|
90 """New portlet settings editor""" |
|
91 |
|
92 settings = INewPortletSettings |
|
93 |
|
94 |
|
95 @adapter_config(name='properties.json', context=(INewPortletSettings, IPyAMSLayer), provides=IPagelet) |
|
96 class NewPortletSettingsAJAXEditor(AJAXEditForm, NewPortletSettingsEditor): |
|
97 """New portlet settings editor, JSON renderer""" |
|
98 |
|
99 |
|
100 4. Previewing portlet content |
|
101 ''''''''''''''''''''''''''''' |
|
102 |
|
103 A *previewer* is used into ZMI to display portlet content into portal template definition page: |
|
104 |
|
105 .. code-block:: python |
|
106 |
|
107 @adapter_config(context=(Interface, IPyAMSLayer, Interface, INewPortletSettings), provides=IPortletPreviewer) |
|
108 @template_config(template='my-portlet-preview.pt', layer=IPyAMSLayer) |
|
109 class NewPortletPreviewer(PortletPreviewer): |
|
110 """New portlet previewer""" |
|
111 |
|
112 |
|
113 The previewer template is a Chameleon template: |
|
114 |
|
115 .. code-block:: genshi |
|
116 |
|
117 <tal:var define="settings view.settings"> |
|
118 <tal:if condition="settings.visible"> |
|
119 <div tal:content="settings.comment">Comment</div> |
|
120 </tal:if> |
|
121 <tal:if condition="not settings.visible"> |
|
122 <div class="text-center padding-y-5"> |
|
123 <span class="fa-stack fa-lg"> |
|
124 <i class="fa fa-eye fa-stack-1x"></i> |
|
125 <i class="fa fa-ban fa-stack-2x text-danger"></i> |
|
126 </span> |
|
127 </div> |
|
128 </tal:if> |
|
129 </tal:var> |
|
130 |
|
131 Here we check if portlet is visible or not to display a small icon when hidden; otherwise we display entered comment. |
|
132 |
|
133 |
|
134 5. Rendering portlet content |
|
135 '''''''''''''''''''''''''''' |
|
136 |
|
137 A *renderer* is used to display portlet content into rendered page content: |
|
138 |
|
139 .. code-block:: python |
|
140 |
|
141 @adapter_config(context=(IPortalContext, IPyAMSLayer, Interface, INewPortletSettings), provides=IPortletRenderer) |
|
142 @template_config(template='my-portlet-render.pt', layer=IPyAMSLayer) |
|
143 class NewPortletRenderer(PortletRenderer): |
|
144 """New portlet renderer""" |
|
145 |
|
146 label = _("Default comment renderer") |
|
147 |
|
148 |
|
149 Each renderer template is also a Chameleon template: |
|
150 |
|
151 .. code-block:: genshi |
|
152 |
|
153 <div class="comment" tal:content="view.settings.comment">Comment</div> |
|
154 |
|
155 |
|
156 This is the configuration of a *default* renderer defined for this portlet; you can provide several renderers for a |
|
157 given portlet by given distinct names to the adapters: |
|
158 |
|
159 .. code-block:: python |
|
160 |
|
161 @adapter_config(name='another-renderer', |
|
162 context=(IPortalContext, IPyAMSLayer, Interface, INewPortletSettings), provides=IPortletRenderer) |
|
163 @template_config(template='my-portlet-render-2.pt', layer=IPyAMSLayer) |
|
164 class AnotherNewPortletRenderer(PortletRenderer): |
|
165 """Another new portlet renderer""" |
|
166 |
|
167 label = _("Another comment renderer") |
|