15 **PyAMS Portal** provides the portal engine but only a very small set of predefined portlets that can be used to compose |
15 **PyAMS Portal** provides the portal engine but only a very small set of predefined portlets that can be used to compose |
16 and organize the structure of a web page; additional portlets are provided by other packages, like |
16 and organize the structure of a web page; additional portlets are provided by other packages, like |
17 :ref:`pyams_content`. |
17 :ref:`pyams_content`. |
18 |
18 |
19 |
19 |
20 1. Define portlet settings |
20 Create Portlet |
21 '''''''''''''''''''''''''' |
21 --------------- |
22 |
|
23 Portlet settings interface are defined in ``interfaces.py``, you can use :py:class:`pyams_portal.interfaces.IPortletSettings` |
|
24 or extend the interface by adding additional properties for example: |
|
25 |
|
26 .. code-block:: python |
|
27 |
|
28 from zope.schema import Text |
|
29 |
|
30 NEW_PORTLET_NAME = 'new.portlet' |
|
31 |
|
32 class INewPortletSettings(IPortletSettings): |
|
33 |
|
34 comment = Text(title=_("Comment"), |
|
35 required=True) |
|
36 |
|
37 |
|
38 A :py:class:`pyams_portal.portlet.PortletSettings` persistent subclass then implements what IPortletSettings describes: |
|
39 |
|
40 .. code-block:: python |
|
41 |
|
42 @implementer(INewPortletSettings) |
|
43 class NewPortletSettings(PortletSettings): |
|
44 """Portlet settings""" |
|
45 |
|
46 comment = FieldProperty(INewPortletSettings['comment']) |
|
47 |
|
48 |
|
49 2. Create Portlet |
|
50 ''''''''''''''''' |
|
51 |
22 |
52 The Portlet component is a utility, which implements the :py:class:`pyams_portal.interfaces.IPortlet` interface and is |
23 The Portlet component is a utility, which implements the :py:class:`pyams_portal.interfaces.IPortlet` interface and is |
53 registered by the :py:func:`pyams_portal.portlet.portlet_config` decorator; |
24 registered by the :py:func:`pyams_portal.portlet.portlet_config` decorator; |
54 |
25 |
55 .. code-block:: python |
26 .. code-block:: python |
61 name = NEW_PORTLET_NAME |
32 name = NEW_PORTLET_NAME |
62 label = _("New portlet") |
33 label = _("New portlet") |
63 |
34 |
64 toolbar_image = None |
35 toolbar_image = None |
65 toolbar_css_class = 'fa fa-fw fa-2x fa-picture-o' |
36 toolbar_css_class = 'fa fa-fw fa-2x fa-picture-o' |
66 |
|
67 settings_class = NewPortletSettings |
|
68 |
37 |
69 |
38 |
70 Where: |
39 Where: |
71 - **permission**: permission required to display this portlet content |
40 - **permission**: permission required to display this portlet content |
72 - **name**: internal name given to this portlet. This name must be unique between all portlets, so using your own |
41 - **name**: internal name given to this portlet. This name must be unique between all portlets, so using your own |
73 namespace into this name is generally a good option! |
42 namespace into this name is generally a good option! |
74 - **label**: user label given to this portlet |
43 - **label**: user label given to this portlet |
75 - **toolbar_image**: URL of an image used to display portlet button into ZMI toolbar, if any |
44 - **toolbar_image**: URL of an image used to display portlet button into ZMI toolbar, if any |
76 - **toolbar_css_class**: CSS class used to display portlet button into ZMI toolbar, if any |
45 - **toolbar_css_class**: CSS class used to display portlet button into ZMI toolbar, if any |
77 - **settings_class**: class used to store portlet settings. |
46 |
78 |
47 NB: the argument **settings_class** could be set to add a portlet settings (see below). |
79 |
48 |
80 3. Create portlet settings edit form |
49 |
81 '''''''''''''''''''''''''''''''''''' |
50 Portlet settings |
82 |
51 ---------------- |
83 Portlet settings have to be updated through management interface via a :py:class:`pyams_portal.zmi.portlet.PortletSettingsEditor` |
52 |
|
53 Portlet settings interface are defined in ``interfaces.py``, you can use :py:class:`pyams_portal.interfaces.IPortletSettings` |
|
54 or extend the interface by adding additional properties for example: |
|
55 |
|
56 1) create portlet settings |
|
57 ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
58 |
|
59 .. code-block:: python |
|
60 |
|
61 from zope.schema import Text |
|
62 |
|
63 NEW_PORTLET_NAME = 'new.portlet' |
|
64 |
|
65 class INewPortletSettings(IPortletSettings): |
|
66 |
|
67 comment = Text(title=_("Comment"), |
|
68 required=True) |
|
69 |
|
70 |
|
71 A :py:class:`pyams_portal.portlet.PortletSettings` persistent subclass then implements what IPortletSettings describes: |
|
72 |
|
73 .. code-block:: python |
|
74 |
|
75 @implementer(INewPortletSettings) |
|
76 class NewPortletSettings(PortletSettings): |
|
77 """Portlet settings""" |
|
78 |
|
79 comment = FieldProperty(INewPortletSettings['comment']) |
|
80 |
|
81 |
|
82 2. declare the settings portlet |
|
83 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
84 |
|
85 Add the settings portlet class inside the portlet |
|
86 |
|
87 .. code-block:: python |
|
88 |
|
89 @portlet_config(permission=VIEW_PERMISSION) |
|
90 class ImagePortlet(Portlet): |
|
91 """Image portlet""" |
|
92 |
|
93 name = NEW_PORTLET_NAME |
|
94 label = _("New portlet") |
|
95 |
|
96 toolbar_image = None |
|
97 toolbar_css_class = 'fa fa-fw fa-2x fa-picture-o' |
|
98 settings_class = NewPortletSettings |
|
99 |
|
100 |
|
101 |
|
102 3. portlet settings edit form |
|
103 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
104 |
|
105 Portlet settings have to be updated through management interface (ZMI) via a :py:class:`pyams_portal.zmi.portlet.PortletSettingsEditor` |
84 subform: |
106 subform: |
85 |
107 |
86 .. code-block:: python |
108 .. code-block:: python |
87 |
109 |
88 @pagelet_config(name='properties.html', context=INewPortletSettings, layer=IPyAMSLayer, |
110 @pagelet_config(name='properties.html', context=INewPortletSettings, layer=IPyAMSLayer, |
96 @adapter_config(name='properties.json', context=(INewPortletSettings, IPyAMSLayer), provides=IPagelet) |
118 @adapter_config(name='properties.json', context=(INewPortletSettings, IPyAMSLayer), provides=IPagelet) |
97 class NewPortletSettingsAJAXEditor(AJAXEditForm, NewPortletSettingsEditor): |
119 class NewPortletSettingsAJAXEditor(AJAXEditForm, NewPortletSettingsEditor): |
98 """New portlet settings editor, JSON renderer""" |
120 """New portlet settings editor, JSON renderer""" |
99 |
121 |
100 |
122 |
101 4. Previewing portlet content |
123 Previewing portlet content |
102 ''''''''''''''''''''''''''''' |
124 -------------------------- |
103 |
125 |
104 A *previewer* is used into ZMI to display portlet content into portal template definition page: |
126 A *previewer* is used into ZMI to display portlet content into portal template definition page: |
105 |
127 |
106 .. code-block:: python |
128 .. code-block:: python |
107 |
129 |