Skip to content

Commit d3e2a00

Browse files
stevepiercystevepiercy
authored
Merge pull request plone#1369 from plone/portlets
Add simple first portlets section.
2 parents 27d2168 + 26c92f0 commit d3e2a00

File tree

1 file changed

+195
-4
lines changed

1 file changed

+195
-4
lines changed

‎docs/classic-ui/portlets.md‎

Lines changed: 195 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,204 @@
11
---
22
myst:
33
html_meta:
4-
"description": ""
5-
"property=og:description": ""
6-
"property=og:title": ""
7-
"keywords": ""
4+
"description": "Basic information about portlets in classic UI"
5+
"property=og:description": "Basic information about portlets in classic UI"
6+
"property=og:title": "Portlets"
7+
"keywords": "portlets"
88
---
99

1010
(classic-ui-portlets-label)=
1111

1212
# Portlets
1313

14+
In Plone, a portlet is a small, modular visual element that can be added to a specific area of a web page, such as the right or left columns, or the footer.
15+
Portlets can be used to display a variety of information, such as the latest news, upcoming events, or a list of related documents.
16+
They can also be prepared to store their own set of fields, allowing users to add custom content to the portlet.
17+
Portlets are typically used to provide relevant information to users in the context of the current page, hierarchy, user, or group.
18+
19+
Inheritance of Plone portlets allows for the automatic display of portlets in child items within the content hierarchy.
20+
This means that if a portlet is set on a parent folder, all child items within that folder will automatically display the portlet unless it is explicitly blocked.
21+
This can be useful for displaying consistent information throughout a section of the website, without having to individually set the portlet on each child item.
22+
The inheritance of portlets can be overridden at any level of the content hierarchy, allowing for fine-grained control over the display of portlets on the website.
23+
24+
Portlets are highly customizable and can be used to display a wide variety of information.
25+
They can be added, removed, or rearranged on a web page by users with the appropriate permissions, allowing for a high degree of flexibility in the layout and content of a Plone site.
26+
27+
Plone comes with several built-in portlets, such as the news portlet, the events portlet, and the login portlet.
28+
In addition, developers can create custom portlets to display specific types of information or to provide specific functionality.
29+
30+
## Adding a portlet to a page
31+
32+
As a user, you can add a portlet to a web page in a Plone site by following these steps:
33+
34+
1. Navigate to the web page where you want to add the portlet.
35+
36+
2. Click on the {guilabel}`Manage portlets` link in the toolbar of the page and select the region on the page to modify.
37+
This will open the screen to manage portlets for the current item.
38+
39+
Note that you must have the appropriate permissions to add portlets to a web page.
40+
If you do not see the {guilabel}`Manage portlets` link, you may need to contact the site administrator to request access.
41+
42+
3. In the {menuselection}`Add portlets` menu, select the portlet type that you want to add, and click the {guilabel}`Add` button.
43+
This will open a form to edit the settings for the selected portlet type.
44+
45+
4. Click the {guilabel}`Save` button to save your changes and add the portlet to the web page.
46+
This adds the portlet to the list of {guilabel}`Portlets assigned here` on the screen.
47+
48+
5. Use the {guilabel}`Up` and {guilabel}`Down` arrows in the {guilabel}`Assigned portlets` section to change the order in which the portlets will be displayed on the web page.
49+
The {guilabel}`Hide` button will deactivate the portlet.
50+
The {guilabel}`X` button deletes the portlet.
51+
These options will only appear at the root from which the object inherits its settings.
52+
53+
54+
## Writing a custom Portlet
55+
56+
To create a portlet, you will need to write Python classes that define the portlet and its behavior.
57+
This class should subclass the `Portlet` class from the `plone.portlets` package.
58+
59+
Here is an example of a very simple portlet class `my_portlet.py`:
60+
61+
```python
62+
from plone.app.portlets.portlets import base
63+
from plone.portlets.interfaces import IPortletDataProvider
64+
from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile
65+
from zope import schema
66+
from zope.interface import implementer
67+
68+
69+
class IExamplePortlet(IPortletDataProvider):
70+
"""A portlet that displays a greeting message."""
71+
72+
message = schema.TextLine(
73+
title="Greeting message",
74+
description="The message to display in the portlet.",
75+
required=True,
76+
)
77+
78+
79+
@implementer(IExamplePortlet)
80+
class Assignment(base.Assignment):
81+
"""Portlet assignment."""
82+
83+
def __init__(self, message="Hello World!"):
84+
self.message = message
85+
86+
@property
87+
def title(self):
88+
"""This property is used to give the title of the portlet in the
89+
"manage portlets" screen. Here we use the message as a part of the title.
90+
"""
91+
return f"Greeting: {self.message}"
92+
93+
94+
class Renderer(base.Renderer):
95+
"""Portlet renderer."""
96+
97+
# Define the page template that will be used to render the portlet
98+
template = ViewPageTemplateFile("my_portlet.pt")
99+
100+
def message(self):
101+
"""This method is called by the page template to render the portlet."""
102+
return self.data.message
103+
104+
def render(self):
105+
"""This method is called whenever the portlet is rendered."""
106+
return self.template()
107+
108+
109+
class AddForm(base.AddForm):
110+
"""Portlet add form."""
111+
112+
schema = IExamplePortlet
113+
label = "Add Greeting Portlet"
114+
description = "This portlet displays a greeting."
115+
116+
def create(self, data):
117+
return Assignment(**data)
118+
119+
120+
class EditForm(base.EditForm):
121+
"""Portlet edit form."""
122+
123+
schema = IExamplePortlet
124+
label = "Edit Greeting Portlet"
125+
description = "This portlet displays a greeting."
126+
127+
```
128+
129+
Here is the example for a simple page template `my_portlet.pt`:
130+
131+
```html
132+
<html
133+
xmlns="http://www.w3.org/1999/xhtml"
134+
xmlns:tal="http://xml.zope.org/namespaces/tal"
135+
xmlns:i18n="http://xml.zope.org/namespaces/i18n"
136+
tal:omit-tag=""
137+
>
138+
<div class="card portlet" i18n:domain="my-example">
139+
<div class="card-header">Greeter</div>
140+
141+
<div class="card-body">
142+
<p>${python:view.message()}</p>
143+
</div>
144+
145+
<div class="card-footer portletFooter"></div>
146+
</div>
147+
</html>
148+
```
149+
150+
This portlet class defines a portlet with the title "My Portlet" and the name "my-portlet". When the portlet is rendered, it will use the template file `my_portlet.pt` to generate its HTML output that displays a greeting message.
151+
152+
The message is set when the portlet is added and can be edited in the portlet's edit form.
153+
154+
To register this portlet with Plone, you will need to create a `configure.zcml` file that tells Plone about the portlet.
155+
After a restart, you can add it to a Plone page using the {guilabel}`Manage portlets` screen.
156+
Here is an example `configure.zcml` file that registers the `MyPortlet` class defined above:
157+
158+
```xml
159+
<configure xmlns="http://namespaces.zope.org/zope"
160+
xmlns:browser="http://namespaces.zope.org/browser"
161+
xmlns:plone="http://namespaces.plone.org/plone"
162+
i18n_domain="example.portlet">
163+
164+
<plone:portlet
165+
title="Example Portlet"
166+
description="A portlet that displays a greeting message"
167+
addview="example.portlet.add"
168+
editview="example.portlet.edit"
169+
assignment="example.portlet.Assignment"
170+
renderer="example.portlet.Renderer"
171+
schema="example.portlet.IExamplePortlet"
172+
/>
173+
174+
</configure>
175+
```
176+
177+
This file registers a portlet with the following properties:
178+
179+
Title
180+
: `Example Portlet`
181+
182+
Description
183+
: `A portlet that displays a greeting message`
184+
185+
Add form
186+
: `example.portlet.add`
187+
188+
Edit form
189+
: `example.portlet.edit`
190+
191+
Assignment
192+
: `example.portlet.Assignment`
193+
194+
Renderer
195+
: `example.portlet.Renderer`
196+
197+
Schema
198+
: `example.portlet.IExamplePortlet`
199+
200+
These values should match the corresponding classes and interfaces defined in the example code from the previous example.
201+
202+
This file registers the `MyPortlet` class as a portlet with Plone. It also specifies the portlet's name, title, description, and category.
203+
204+
For more examples of how to write and register portlets, look at the source code of the Plone core package [`plone.app.portlets`](https://github.com/plone/plone.app.portlets), or of other Plone add-ons that include portlets.

0 commit comments

Comments
 (0)