Skip to content

Commit 816824a

Browse files
committed
Add documentation for REST API compatible control panels in Volto
1 parent 81e2079 commit 816824a

File tree

1 file changed

+54
-2
lines changed

1 file changed

+54
-2
lines changed

docs/developer-guide/create-control-panel.md

Lines changed: 54 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,6 @@ To manually create a control panel, go through the following steps.
3737
- Add the control panel to the Plone control panel listing.
3838
- Set default values in the registry.
3939

40-
4140
### Define the settings interface and form
4241

4342
Create a Python module, {file}`mypackage/controlpanel/settings.py`, that defines your control panel's settings interface and form class as follows.
@@ -322,6 +321,59 @@ mypackage/
322321
└── registry.xml
323322
```
324323

324+
## REST API compatible control panels
325+
326+
For better integration between backend and Volto, you can create REST API compatible control panels using the adapter pattern. This approach is particularly useful when developing control panels that need to work seamlessly with Volto.
327+
328+
Create a Python module like `mypackage/controlpanel.py`:
329+
330+
```python
331+
from plone.restapi.controlpanels import RegistryConfigletPanel
332+
from zope.component import adapter
333+
from zope.interface import Interface
334+
from zope.i18nmessageid import MessageFactory
335+
336+
_ = MessageFactory("mypackage")
337+
338+
@adapter(Interface, Interface)
339+
class MyAddonControlPanel(RegistryConfigletPanel):
340+
"""Volto-compatible REST API control panel for my addon settings."""
341+
342+
schema = IMyControlPanelSettings
343+
schema_prefix = "my.addon"
344+
configlet_id = "my-controlpanel"
345+
configlet_category_id = "plone-general"
346+
title = _("My Addon Settings")
347+
group = "General"
348+
```
349+
350+
Then register the adapter in your ZCML configuration file:
351+
352+
```xml
353+
<!-- mypackage/configure.zcml or mypackage/controlpanel/configure.zcml -->
354+
<configure
355+
xmlns="http://namespaces.zope.org/zope"
356+
i18n_domain="mypackage">
357+
358+
<adapter
359+
factory=".controlpanel.MyAddonControlPanel"
360+
name="my-controlpanel"
361+
/>
362+
363+
</configure>
364+
```
365+
366+
The `group` property in the control panel class corresponds to the control panel category in Volto:
367+
- `General`: General settings (corresponds to `plone-general`)
368+
- `Content`: Content-related settings (corresponds to `plone-content`)
369+
- `Users`: Users and groups settings (corresponds to `plone-users`)
370+
- `Security`: Security settings (corresponds to `plone-security`)
371+
- `Advanced`: Advanced settings (corresponds to `plone-advanced`)
372+
373+
With this approach, your control panel will be automatically available through the REST API at the endpoint `@controlpanels/my-controlpanel`, making it easy to integrate with Volto without additional configuration.
374+
375+
You will still need to set up the registry.xml with default values as described earlier.
376+
325377
```{seealso}
326378
See the chapter {ref}`training:controlpanel-label` from the Mastering Plone 6 Training.
327-
```
379+
```

0 commit comments

Comments
 (0)