Skip to content

Commit 9fcd80f

Browse files
stevepiercystevepiercy
authored
Merge branch '6.0' into rohnsha0-control-panel
2 parents 5ad2633 + ffda6cf commit 9fcd80f

File tree

10 files changed

+322
-30
lines changed

10 files changed

+322
-30
lines changed

‎docs/_static/documentation.css

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
/*
2+
Remove the external link icon from Plone Sphinx Theme for links
3+
in submodules that refer to Plone 6 Documentation via Intersphinx.
4+
Although these links have `external` in their class, they are
5+
actually internal to Plone 6 Documentation.
6+
*/
7+
.reference.external::after {
8+
all: unset;
9+
}
10+
a:not([title="(in Plone Documentation v6)"]).reference.external::after {
11+
margin-left: .3em;
12+
display: inline-block;
13+
content: var(--pst-icon-external-link);
14+
white-space: nowrap;
15+
font: var(--fa-font-solid);
16+
font-size: .75em;
17+
}

‎docs/_static/test-rendering/bootstrap-cheatsheet.png

41.4 KB
Loading

‎docs/_static/test-rendering/icons.png

31.6 KB
Loading

‎docs/_static/test-rendering/test-rendering.png

51.5 KB
Loading

‎docs/backend/subscribers.md

+158-4
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,162 @@ myst:
1111

1212
# Subscribers (event handlers)
1313

14-
```{todo}
15-
Move content from:
16-
- https://5.docs.plone.org/external/plone.app.dexterity/docs/advanced/event-handlers.html
17-
- https://5.docs.plone.org/develop/addons/components/events.html
14+
A _subscriber_ is a callable object that takes one argument, an object that we call the _event_.
15+
16+
_Events_ are objects that represent something happening in a system.
17+
They are used to extend processing by providing processing plug points.
18+
19+
A _notification_ alerts subscribers that an event has occurred.
20+
21+
The {term}`Zope Component Architecture`'s [`zope.event`](https://zopeevent.readthedocs.io/en/latest/) package is used to manage subscribable events in Plone.
22+
23+
The Plone event system has some notable characteristics:
24+
25+
- It's simple.
26+
- The calling order of subscribers is random.
27+
You can't set the order in which event handlers are called.
28+
- Events can't be cancelled.
29+
All handlers will always get the event.
30+
- Event handlers can't have return values.
31+
- Exceptions raised in an event handler will interrupt the request processing.
32+
33+
34+
## Register an event handler
35+
36+
Plone events can be scoped:
37+
38+
- globally (no scope)
39+
- per content type
40+
- per behavior or marker interface
41+
42+
43+
### Register an event handler on content type creation
44+
45+
The following example demonstrates how to register an event handler when a content type is created.
46+
47+
In your {file}`.product/your/product/configure.zcml` insert the following code.
48+
49+
{lineno-start=1}
50+
```xml
51+
<subscriber
52+
for=".interfaces.IMyContentTypeClass
53+
zope.lifecycleevent.IObjectCreatedEvent"
54+
handler=".your_python_file.your_method"
55+
/>
56+
```
57+
58+
The second line defines to which interface you want to bind the execution of your code.
59+
Here, the event handler code will only be executed if the object is a content type providing the interface `.interfaces.IMyContentTypeClass`.
60+
If you want this to be interface agnostic, insert an asterix `*` as a wildcard instead.
61+
62+
The third line defines the event on which this should happen, which is `IObjectCreatedEvent`.
63+
For more available possible events to use as a trigger, see {ref}`subscribers-event-handlers`.
64+
65+
The fourth line gives the path to the callable function to be executed.
66+
67+
Create your {file}`.product/your/product/your_python_file.py` and insert the following code.
68+
69+
```python
70+
def your_subscriber(object, event):
71+
# do something with your created content type
72+
```
73+
74+
75+
### Subscribe to an event using ZCML
76+
77+
Subscribe to a global event using {term}`ZCML` by inserting the following code in your {file}`.product/your/product/configure.zcml`.
78+
79+
```xml
80+
<subscriber
81+
for="Products.PlonePAS.events.UserLoggedOutEvent"
82+
handler=".smartcard.clear_extra_cookies_on_logout"
83+
/>
84+
```
85+
86+
For this event, the Python code in {file}`smartcard.py` would be the following.
87+
88+
```python
89+
def clear_extra_cookies_on_logout(event):
90+
# What event contains depends on the
91+
# triggerer of the event and event class
92+
request = event.object.REQUEST
93+
```
94+
95+
The following example for a custom event subscribes content types to all `IMyEvents` when fired by `IMyObject`.
96+
97+
```xml
98+
<subscriber
99+
for=".interfaces.IMyObject
100+
.interfaces.IMyEvent"
101+
handler=".content.MyObject.myEventHandler"
102+
/>
18103
```
104+
105+
The following example shows how to subscribe a content type to the life cycle event.
106+
107+
```xml
108+
<subscriber
109+
zcml:condition="installed zope.lifecycleevent"
110+
for=".interfaces.ISitsPatient
111+
zope.lifecycleevent.IObjectModifiedEvent"
112+
handler=".content.SitsPatient.objectModified"
113+
/>
114+
```
115+
116+
117+
## Fire an event
118+
119+
Use `zope.event.notify()` to fire event objects to their subscribers.
120+
121+
The following code shows how to fire an event in unit tests.
122+
123+
```python
124+
import zope.event
125+
from plone.postpublicationhook.event import AfterPublicationEvent
126+
127+
event = AfterPublicationEvent(self.portal, self.portal.REQUEST)
128+
zope.event.notify(event)
129+
```
130+
131+
132+
(subscribers-event-types-label)=
133+
134+
## Event types
135+
136+
Plone has the following types of events.
137+
138+
139+
### Creation events
140+
141+
`zope.lifecycleevent.IObjectCreatedEvent` is fired for all Zope-ish objects when they are created, or copied via `IObjectCopiedEvent`.
142+
They don't have to be content objects.
143+
144+
### Modified events
145+
146+
`zope.lifecycleevent.IObjectModifiedEvent` is called for creation stage events as well, unlike the previous event type.
147+
148+
### Delete events
149+
150+
Delete events can be fired several times for the same object.
151+
Some delete event transactions are rolled back.
152+
153+
### Copy events
154+
155+
`zope.lifecycleevent.IObjectCopiedEvent` is triggered when an object is copied.
156+
It will also fire `IObjectCreatedEvent` event code.
157+
158+
### Workflow events
159+
160+
`Products.DCWorkflow.interfaces.IBeforeTransitionEvent` is triggered before a workflow transition is executed.
161+
162+
`Products.DCWorkflow.interfaces.IAfterTransitionEvent` is triggered after a workflow transition has been executed.
163+
164+
The DCWorkflow events are low-level events that can tell you a lot about the previous and current states.
165+
166+
`Products.CMFCore.interfaces.IActionSucceededEvent` is a higher level event that is more commonly used to react after a workflow action has completed.
167+
168+
### Zope startup events
169+
170+
`zope.processlifetime.IProcessStarting` is triggered after the component registry has been loaded and Zope is starting up.
171+
172+
`zope.processlifetime.IDatabaseOpened` is triggered after the main ZODB database has been opened.

‎docs/classic-ui/theming/create-add-on.md

+76
Original file line numberDiff line numberDiff line change
@@ -141,3 +141,79 @@ $state-colors: map-merge($state-colors, $custom-colors);
141141
Inside the file `theme/_custom.scss` you can write all your custom CSS/Sass code to adapt the theme to your needs.
142142
Feel free to add more files inside the `scss/` folder to make your code more readable.
143143
Don't forget to import your custom files in `scss/theme.scss`.
144+
145+
146+
## Styles test rendering
147+
148+
Plone's Classic UI includes special demonstration views that render ready-made examples of interface components using your site's active theme.
149+
These views help developers verify styling implementation and explore available UI patterns.
150+
These views work in any context.
151+
No special permissions are required.
152+
153+
Append one of the following view names with a leading slash `/` to any Plone site URL.
154+
155+
- `/@@test-rendering`
156+
- `/@@test-rendering-cheatsheet`
157+
- `/@@test-rendering-icons`
158+
159+
Each view name corresponds to a named tab in Plone as described in the following sections.
160+
161+
162+
### {guilabel}`Test Rendering`
163+
164+
The {guilabel}`Test Rendering` tab at the view name `@@test-rendering` displays Bootstrap style status message examples.
165+
It shows all alert variants including:
166+
167+
- Success, warning, and error notifications
168+
- Dismissible alerts
169+
- Contextual color examples
170+
171+
````{card}
172+
```{image} /_static/test-rendering/test-rendering.png
173+
:alt: Test Rendering
174+
:target: /_static/test-rendering/test-rendering.png
175+
```
176+
+++
177+
_Test Rendering_
178+
````
179+
180+
### {guilabel}`Bootstrap Cheatsheet`
181+
182+
The {guilabel}`Bootstrap Cheatsheet` tab at the view name `@@test-rendering-cheatsheet` displays the kitchen sink of Bootstrap components.
183+
It includes the following examples and dozens more:
184+
185+
- color mode switcher interface, located in the lower right corner of the browser window
186+
- grid layout examples
187+
- form control variants
188+
- navigation components
189+
- interactive element states
190+
191+
````{card}
192+
```{image} /_static/test-rendering/bootstrap-cheatsheet.png
193+
:alt: Bootstrap Cheatsheet
194+
:target: /_static/test-rendering/bootstrap-cheatsheet.png
195+
```
196+
+++
197+
_Bootstrap Cheatsheet_
198+
````
199+
200+
### {guilabel}`Icons`
201+
202+
The {guilabel}`Icons` tab at the view name `@@test-rendering-icons` displays a few icon classes.
203+
It includes the following examples:
204+
205+
- icon resolver usage
206+
- code samples for both URL and tag generation
207+
208+
````{card}
209+
```{image} /_static/test-rendering/icons.png
210+
:alt: Icons
211+
:target: /_static/test-rendering/icons.png
212+
```
213+
+++
214+
_Icons_
215+
````
216+
217+
```{seealso}
218+
For an overview of UI components in Volto, see its [Storybook](https://6.docs.plone.org/storybook/).
219+
```

‎docs/conf.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -278,7 +278,7 @@
278278
# If false, no index is generated.
279279
html_use_index = True
280280

281-
html_css_files = [("print.css", {"media": "print"})]
281+
html_css_files = ["documentation.css", ("print.css", {"media": "print"})]
282282
html_js_files = []
283283

284284
html_extra_path = [

0 commit comments

Comments
 (0)