From 420759bad1e55256aaa359069521e14f04a87ae2 Mon Sep 17 00:00:00 2001
From: Rohan Shaw <rohnsha0@gmail.com>
Date: Fri, 14 Mar 2025 01:56:15 +0530
Subject: [PATCH 01/10] adds docs for creating custom control panel

---
 docs/backend/control-panels.md | 247 ++++++++++++++++++++++++++++++++-
 1 file changed, 241 insertions(+), 6 deletions(-)

diff --git a/docs/backend/control-panels.md b/docs/backend/control-panels.md
index 602a90f75..cc74b6f97 100644
--- a/docs/backend/control-panels.md
+++ b/docs/backend/control-panels.md
@@ -12,15 +12,170 @@ myst:
 # Control panels
 
 ## Adding a control panel
+
+There are two approaches to creating a control panel for your Plone add-on:
+
+### Approach 1: Using plonecli
+
 To add a control panel to your add-on, you can use [`plonecli`](https://pypi.org/project/plonecli/) as follows:
 
 ```shell
 plonecli add controlpanel
 ```
 
-This will create the control panel Python file in the control panel's folder where you can define your control panel schema fields. 
+This will create the control panel Python file in the control panel's folder where you can define your control panel schema fields.
+
+### Approach 2: Creating a Custom Control Panel Manually
+
+Creating a custom control panel involves these main steps:
+
+1. Define an interface for your settings
+2. Create a form based on that interface
+3. Register the control panel view in ZCML
+4. Add the control panel to the Plone control panel listing
+5. Set default values in the registry
+
+#### 1. Define the Settings Interface and Form
+
+First, create a Python module that defines your control panel's settings interface and form class:
+
+```python
+# mypackage/controlpanel/settings.py
+from zope import schema
+from zope.interface import Interface
+from plone.app.registry.browser.controlpanel import RegistryEditForm, ControlPanelFormWrapper
+from plone.z3cform import layout
+
+class IMyControlPanelSettings(Interface):
+    """Schema for the control panel form."""
+    
+    my_setting = schema.TextLine(
+        title=u'My Setting',
+        description=u'Enter the value for my setting',
+        required=False,
+        default=u''
+    )
+    
+    my_choice = schema.Choice(
+        title=u'My Choice',
+        description=u'Select a value for my choice',
+        required=False,
+        default=u'value3',
+        values=['value1', 'value2', 'value3']
+    )
+
+class MyControlPanelForm(RegistryEditForm):
+    """Control panel form."""
+    
+    schema = IMyControlPanelSettings
+    schema_prefix = "my.addon"
+    label = u"My Addon Settings"
+
+# Wrap the form with plone.z3cform's ControlPanelFormWrapper to get the Plone
+# control panel look and feel
+MyControlPanelView = layout.wrap_form(MyControlPanelForm, ControlPanelFormWrapper)
+```
+
+#### 2. Register the Control Panel View in ZCML
+
+Next, register the control panel view in ZCML:
+
+```xml
+<!-- mypackage/controlpanel/configure.zcml -->
+<configure
+    xmlns="http://namespaces.zope.org/zope"
+    xmlns:browser="http://namespaces.zope.org/browser"
+    i18n_domain="mypackage">
+
+    <browser:page
+        name="my-controlpanel"
+        for="Products.CMFPlone.interfaces.IPloneSiteRoot"
+        class=".settings.MyControlPanelView"
+        permission="cmf.ManagePortal"
+        />
+
+</configure>
+```
+
+Make sure to include this configure.zcml from your package's main configure.zcml:
+
+```xml
+<!-- mypackage/configure.zcml -->
+<configure
+    xmlns="http://namespaces.zope.org/zope"
+    xmlns:i18n="http://namespaces.zope.org/i18n"
+    i18n_domain="mypackage">
+    
+    <!-- Other configuration -->
+    
+    <include package=".controlpanel" />
+    
+</configure>
+```
+
+#### 3. Add the Control Panel Entry
+
+Create a controlpanel.xml in your package's GenericSetup profile to add your control panel to the Plone control panel listing:
+
+```xml
+<!-- mypackage/profiles/default/controlpanel.xml -->
+<?xml version="1.0"?>
+<object name="portal_controlpanel">
+    <configlet
+        title="My Addon Settings"
+        action_id="my-controlpanel"
+        appId="my.addon"
+        category="plone-general"
+        condition_expr=""
+        icon_expr="string:puzzle"
+        url_expr="string:${portal_url}/@@my-controlpanel"
+        visible="True">
+        <permission>Manage portal</permission>
+    </configlet>
+</object>
+```
+
+The category attribute can be one of:
+- `plone-general` - General settings
+- `plone-content` - Content-related settings
+- `plone-users` - Users and groups settings
+- `plone-security` - Security settings
+- `plone-advanced` - Advanced settings
+
+#### 4. Set Default Values in the Registry
+
+Define default values for your settings in registry.xml:
+
+```xml
+<!-- mypackage/profiles/default/registry.xml -->
+<?xml version="1.0"?>
+<registry>
+    <records interface="mypackage.controlpanel.settings.IMyControlPanelSettings"
+             prefix="my.addon">
+        <value key="my_setting">default value</value>
+        <value key="my_choice">value3</value>
+    </records>
+</registry>
+```
+
+#### 5. Accessing Your Settings in Code
+
+You can access your settings in Python code as follows:
+
+```python
+from plone.registry.interfaces import IRegistry
+from zope.component import getUtility
+
+registry = getUtility(IRegistry)
+settings = registry.forInterface(IMyControlPanelSettings, prefix="my.addon")
+
+# Now you can access the settings
+my_setting_value = settings.my_setting
+my_choice_value = settings.my_choice
+```
 
 ## Registering a Control panel
+
 To manually register a view as a control panel, add the following registration to your `/profiles/default/controlpanel.xml`.
 
 ```xml
@@ -44,11 +199,91 @@ To manually register a view as a control panel, add the following registration t
   </object>
 ```
 
-```{seealso}
-See the chapter {ref}`training:controlpanel-label` from the Mastering Plone 6 Training.
+## Advanced Topics
+
+### Using FieldSet for Grouping Fields
+
+For complex control panels, you might want to group fields together:
+
+```python
+from plone.supermodel import model
+
+class IMyControlPanelSettings(Interface):
+    
+    model.fieldset(
+        'advanced',
+        label=u"Advanced Settings",
+        fields=['advanced_setting1', 'advanced_setting2']
+    )
+    
+    # Basic settings
+    my_setting = schema.TextLine(
+        title=u'My Setting',
+        description=u'Enter the value for my setting',
+        required=False
+    )
+    
+    # Advanced settings
+    advanced_setting1 = schema.TextLine(
+        title=u'Advanced Setting 1',
+        required=False
+    )
+    
+    advanced_setting2 = schema.Bool(
+        title=u'Advanced Setting 2',
+        default=False
+    )
 ```
 
-```{todo}
-Contribute to this documentation!
-See issue [Backend > Control Panels needs content](https://github.com/plone/documentation/issues/1304).
+### Common Schema Fields
+
+Here are some commonly used schema field types:
+
+- `schema.TextLine`: For single-line text
+- `schema.Text`: For multi-line text
+- `schema.Bool`: For boolean values
+- `schema.Int`: For integer values
+- `schema.Float`: For floating-point values
+- `schema.Choice`: For selection from a list of values
+- `schema.Datetime`: For date and time values
+- `schema.List`: For list of values
+
+### Note on Updating Control Panel Fields
+
+When you modify the fields in your control panel settings interface, the changes won't be automatically reflected in existing sites. You'll need to:
+
+1. Run the appropriate upgrade steps, or
+2. Reinstall your add-on, or
+3. Test with a fresh site installation
+
+## Troubleshooting
+
+If your control panel doesn't appear or doesn't work as expected:
+
+1. Verify that all ZCML is properly registered
+2. Check for errors in the Plone error log
+3. Ensure your GenericSetup profiles are correctly installed
+4. Validate that the interface path in registry.xml matches your actual Python path
+
+## Complete Example
+
+Below is a complete file structure for a simple add-on with a control panel:
+
+```
+mypackage/
+├── __init__.py
+├── configure.zcml
+├── controlpanel/
+│   ├── __init__.py
+│   ├── configure.zcml
+│   └── settings.py
+└── profiles/
+    └── default/
+        ├── controlpanel.xml
+        ├── metadata.xml
+        └── registry.xml
+```
+
+```{seealso}
+See the chapter {ref}`training:controlpanel-label` from the Mastering Plone 6 Training.
 ```
\ No newline at end of file

From f221c11732673521786fe8edaa8a895552a4eff2 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Sat, 15 Mar 2025 02:18:58 -0700
Subject: [PATCH 02/10] Move to developer-guide and rename

---
 docs/backend/index.md                                            | 1 -
 .../create-control-panel.md}                                     | 0
 docs/developer-guide/index.md                                    | 1 +
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename docs/{backend/control-panels.md => developer-guide/create-control-panel.md} (100%)

diff --git a/docs/backend/index.md b/docs/backend/index.md
index 3e7dd3278..7bea7cfd5 100644
--- a/docs/backend/index.md
+++ b/docs/backend/index.md
@@ -21,7 +21,6 @@ annotations
 behaviors
 configuration-registry
 content-types/index
-control-panels
 fields
 global-utils
 indexing
diff --git a/docs/backend/control-panels.md b/docs/developer-guide/create-control-panel.md
similarity index 100%
rename from docs/backend/control-panels.md
rename to docs/developer-guide/create-control-panel.md
diff --git a/docs/developer-guide/index.md b/docs/developer-guide/index.md
index dfc6d8c50..7fa3d26b8 100644
--- a/docs/developer-guide/index.md
+++ b/docs/developer-guide/index.md
@@ -21,6 +21,7 @@ You can help consolidate all of development documentation here, even if it is to
 ```{toctree}
 :maxdepth: 2
 
+create-control-panel
 create-a-distribution
 standardize-python-project-configuration
 ```

From 4f87d25b4e0557f12d5961c403fcaea3fa66bc6c Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Sat, 15 Mar 2025 03:09:48 -0700
Subject: [PATCH 03/10] - Flatten hierarchy - Sentence case headings - Add
 content to empty headings - Use appropriate list type, either bulleted or
 definition - Indent lists 4 spaces for consistency and visually spotting
 syntax issues - Use `{file}` markup for files, directories, and file paths -
 Emphasize lines in code block as needed

---
 docs/developer-guide/create-control-panel.md | 154 ++++++++++++-------
 1 file changed, 96 insertions(+), 58 deletions(-)

diff --git a/docs/developer-guide/create-control-panel.md b/docs/developer-guide/create-control-panel.md
index cc74b6f97..f0582518c 100644
--- a/docs/developer-guide/create-control-panel.md
+++ b/docs/developer-guide/create-control-panel.md
@@ -9,35 +9,38 @@ myst:
 
 (backend-controlpanels-label)=
 
-# Control panels
+# Create a control panel
 
-## Adding a control panel
+There are two approaches to create a control panel for your Plone add-on:
 
-There are two approaches to creating a control panel for your Plone add-on:
+-   [`plonecli`](https://pypi.org/project/plonecli/)
+-   manual
 
-### Approach 1: Using plonecli
 
-To add a control panel to your add-on, you can use [`plonecli`](https://pypi.org/project/plonecli/) as follows:
+## `plonecli`
+
+To add a control panel to your add-on, you can use [`plonecli`](https://pypi.org/project/plonecli/) as follows.
 
 ```shell
 plonecli add controlpanel
 ```
 
-This will create the control panel Python file in the control panel's folder where you can define your control panel schema fields.
+This creates the control panel Python file in the control panel's folder where you can define your control panel schema fields.
+
 
-### Approach 2: Creating a Custom Control Panel Manually
+## Manual
 
-Creating a custom control panel involves these main steps:
+To manually create a control panel, go through the following steps.
 
-1. Define an interface for your settings
-2. Create a form based on that interface
-3. Register the control panel view in ZCML
-4. Add the control panel to the Plone control panel listing
-5. Set default values in the registry
+-   Define the settings interface and form.
+-   Register the control panel view in ZCML.
+-   Add the control panel to the Plone control panel listing.
+-   Set default values in the registry.
 
-#### 1. Define the Settings Interface and Form
 
-First, create a Python module that defines your control panel's settings interface and form class:
+### Define the settings interface and form
+
+Create a Python module, {file}`mypackage/controlpanel/settings.py`, that defines your control panel's settings interface and form class as follows.
 
 ```python
 # mypackage/controlpanel/settings.py
@@ -76,9 +79,10 @@ class MyControlPanelForm(RegistryEditForm):
 MyControlPanelView = layout.wrap_form(MyControlPanelForm, ControlPanelFormWrapper)
 ```
 
-#### 2. Register the Control Panel View in ZCML
 
-Next, register the control panel view in ZCML:
+### Register the control panel view
+
+Create a file {file}`mypackage/controlpanel/configure.zcml` with the following content to register the control panel view in ZCML.
 
 ```xml
 <!-- mypackage/controlpanel/configure.zcml -->
@@ -97,8 +101,9 @@ Next, register the control panel view in ZCML:
 </configure>
 ```
 
-Make sure to include this configure.zcml from your package's main configure.zcml:
+Make sure to include the above file in your package's main {file}`mypackage/configure.zcml` as shown by the highlighted line below.
 
+{emphasize-lines="9"}
 ```xml
 <!-- mypackage/configure.zcml -->
 <configure
@@ -113,9 +118,9 @@ Make sure to include this configure.zcml from your package's main configure.zcml
 </configure>
 ```
 
-#### 3. Add the Control Panel Entry
+### Add the control panel entry
 
-Create a controlpanel.xml in your package's GenericSetup profile to add your control panel to the Plone control panel listing:
+Create a {file}`mypackage/profiles/default/controlpanel.xml` in your package's GenericSetup profile with the following content to add your control panel to the Plone control panel listing.
 
 ```xml
 <!-- mypackage/profiles/default/controlpanel.xml -->
@@ -135,16 +140,28 @@ Create a controlpanel.xml in your package's GenericSetup profile to add your con
 </object>
 ```
 
-The category attribute can be one of:
-- `plone-general` - General settings
-- `plone-content` - Content-related settings
-- `plone-users` - Users and groups settings
-- `plone-security` - Security settings
-- `plone-advanced` - Advanced settings
+The category attribute can be one of the following values.
+These values correspond to the groups in Site Setup.
+
+`plone-general`
+:   General settings
+
+`plone-content`
+:   Content-related settings
+
+`plone-users`
+:   Users and groups settings
 
-#### 4. Set Default Values in the Registry
+`plone-security`
+:   Security settings
 
-Define default values for your settings in registry.xml:
+`plone-advanced`
+:   Advanced settings
+
+
+### Set default values in the registry
+
+Define default values for your settings in {file}`mypackage/profiles/default/registry.xml`.
 
 ```xml
 <!-- mypackage/profiles/default/registry.xml -->
@@ -158,9 +175,10 @@ Define default values for your settings in registry.xml:
 </registry>
 ```
 
-#### 5. Accessing Your Settings in Code
 
-You can access your settings in Python code as follows:
+### Access your settings in code
+
+You can access your settings in Python code as follows.
 
 ```python
 from plone.registry.interfaces import IRegistry
@@ -174,12 +192,13 @@ my_setting_value = settings.my_setting
 my_choice_value = settings.my_choice
 ```
 
-## Registering a Control panel
 
-To manually register a view as a control panel, add the following registration to your `/profiles/default/controlpanel.xml`.
+## Register a control panel
+
+To manually register a view as a control panel, add the following registration to your {file}`/profiles/default/controlpanel.xml`.
 
 ```xml
-  <?xml version="1.0"?>
+<?xml version="1.0"?>
   <object
       name="portal_control-panel"
       xmlns:i18n="http://xml.zope.org/namespaces/i18n"
@@ -199,11 +218,10 @@ To manually register a view as a control panel, add the following registration t
   </object>
 ```
 
-## Advanced Topics
 
-### Using FieldSet for Grouping Fields
+## Use `FieldSet` to group fields
 
-For complex control panels, you might want to group fields together:
+For complex control panels, you can group fields together as in the following example.
 
 ```python
 from plone.supermodel import model
@@ -235,39 +253,59 @@ class IMyControlPanelSettings(Interface):
     )
 ```
 
-### Common Schema Fields
 
-Here are some commonly used schema field types:
+## Common schema fields
 
-- `schema.TextLine`: For single-line text
-- `schema.Text`: For multi-line text
-- `schema.Bool`: For boolean values
-- `schema.Int`: For integer values
-- `schema.Float`: For floating-point values
-- `schema.Choice`: For selection from a list of values
-- `schema.Datetime`: For date and time values
-- `schema.List`: For list of values
+The following is a list of commonly used schema field types.
 
-### Note on Updating Control Panel Fields
+`schema.TextLine`
+:   For single-line text
 
-When you modify the fields in your control panel settings interface, the changes won't be automatically reflected in existing sites. You'll need to:
+`schema.Text`
+:   For multi-line text
+
+`schema.Bool`
+:   For boolean values
+
+`schema.Int`
+:   For integer values
+
+`schema.Float`
+:   For floating-point values
+
+`schema.Choice`
+:   For selection from a list of values
+
+`schema.Datetime`
+:   For date and time values
+
+`schema.List`
+:   For list of values
+
+
+## Modify control panel fields
+
+When you modify the fields in your control panel settings interface, the changes won't be automatically reflected in existing sites.
+You'll need to perform one or more of the following steps.
+
+-   Run the appropriate upgrade steps.
+-   Reinstall your add-on.
+-   Test with a fresh site installation.
 
-1. Run the appropriate upgrade steps, or
-2. Reinstall your add-on, or
-3. Test with a fresh site installation
 
 ## Troubleshooting
 
 If your control panel doesn't appear or doesn't work as expected:
 
-1. Verify that all ZCML is properly registered
-2. Check for errors in the Plone error log
-3. Ensure your GenericSetup profiles are correctly installed
-4. Validate that the interface path in registry.xml matches your actual Python path
+-   Verify that all ZCML is properly registered
+-   Check for errors in the Plone error log
+-   Ensure your GenericSetup profiles are correctly installed
+-   Validate that the interface path in registry.xml matches your actual Python path
+
 
-## Complete Example
+## Example file structure
 
-Below is a complete file structure for a simple add-on with a control panel:
+Below is a complete example file structure for a basic add-on with a control panel.
 
 ```
 mypackage/
@@ -286,4 +324,4 @@ mypackage/
 
 ```{seealso}
 See the chapter {ref}`training:controlpanel-label` from the Mastering Plone 6 Training.
-```
\ No newline at end of file
+```

From 228a0d3f5536980441d92dafc876c56aa7129c21 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Sat, 15 Mar 2025 03:31:02 -0700
Subject: [PATCH 04/10] Tidy up meta stuff

---
 docs/developer-guide/create-control-panel.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/developer-guide/create-control-panel.md b/docs/developer-guide/create-control-panel.md
index f0582518c..42fada67c 100644
--- a/docs/developer-guide/create-control-panel.md
+++ b/docs/developer-guide/create-control-panel.md
@@ -1,10 +1,10 @@
 ---
 myst:
   html_meta:
-    "description": "How to add a Control Panel"
-    "property=og:description": "How to add a Control Panel"
-    "property=og:title": "Control panels"
-    "keywords": "Plone, Add, Control Panel"
+    "description": "How to create a control panel"
+    "property=og:description": "How to create a control panel"
+    "property=og:title": "Create a control panel"
+    "keywords": "Plone, create, control panel, plonecli, registry"
 ---
 
 (backend-controlpanels-label)=

From 816824abbcf3d0b7c074d31b7c3cf9573edae5d8 Mon Sep 17 00:00:00 2001
From: Rohan Shaw <rohnsha0@gmail.com>
Date: Sat, 5 Apr 2025 10:29:43 +0530
Subject: [PATCH 05/10] Add documentation for REST API compatible control
 panels in Volto

---
 docs/developer-guide/create-control-panel.md | 56 +++++++++++++++++++-
 1 file changed, 54 insertions(+), 2 deletions(-)

diff --git a/docs/developer-guide/create-control-panel.md b/docs/developer-guide/create-control-panel.md
index 42fada67c..8d4a2c670 100644
--- a/docs/developer-guide/create-control-panel.md
+++ b/docs/developer-guide/create-control-panel.md
@@ -37,7 +37,6 @@ To manually create a control panel, go through the following steps.
 -   Add the control panel to the Plone control panel listing.
 -   Set default values in the registry.
 
-
 ### Define the settings interface and form
 
 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/
         └── registry.xml
 ```
 
+## REST API compatible control panels
+
+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.
+
+Create a Python module like `mypackage/controlpanel.py`:
+
+```python
+from plone.restapi.controlpanels import RegistryConfigletPanel
+from zope.component import adapter
+from zope.interface import Interface
+from zope.i18nmessageid import MessageFactory
+
+_ = MessageFactory("mypackage")
+
+@adapter(Interface, Interface)
+class MyAddonControlPanel(RegistryConfigletPanel):
+    """Volto-compatible REST API control panel for my addon settings."""
+
+    schema = IMyControlPanelSettings
+    schema_prefix = "my.addon"
+    configlet_id = "my-controlpanel"
+    configlet_category_id = "plone-general"
+    title = _("My Addon Settings")
+    group = "General"
+```
+
+Then register the adapter in your ZCML configuration file:
+
+```xml
+<!-- mypackage/configure.zcml or mypackage/controlpanel/configure.zcml -->
+<configure
+    xmlns="http://namespaces.zope.org/zope"
+    i18n_domain="mypackage">
+
+    <adapter
+        factory=".controlpanel.MyAddonControlPanel"
+        name="my-controlpanel"
+    />
+
+</configure>
+```
+
+The `group` property in the control panel class corresponds to the control panel category in Volto:
+- `General`: General settings (corresponds to `plone-general`)
+- `Content`: Content-related settings (corresponds to `plone-content`)
+- `Users`: Users and groups settings (corresponds to `plone-users`)
+- `Security`: Security settings (corresponds to `plone-security`)
+- `Advanced`: Advanced settings (corresponds to `plone-advanced`)
+
+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.
+
+You will still need to set up the registry.xml with default values as described earlier.
+
 ```{seealso}
 See the chapter {ref}`training:controlpanel-label` from the Mastering Plone 6 Training.
-```
+```
\ No newline at end of file

From ac9fc7d10ceede87c3a7673543d9faba632a8f58 Mon Sep 17 00:00:00 2001
From: Rohan Shaw <86848116+rohnsha0@users.noreply.github.com>
Date: Sun, 6 Apr 2025 19:42:57 +0530
Subject: [PATCH 06/10] Apply suggestions from code review

Co-authored-by: Steve Piercy <web@stevepiercy.com>
---
 docs/developer-guide/create-control-panel.md | 35 +++++++++++++-------
 1 file changed, 23 insertions(+), 12 deletions(-)

diff --git a/docs/developer-guide/create-control-panel.md b/docs/developer-guide/create-control-panel.md
index 8d4a2c670..767df5bd3 100644
--- a/docs/developer-guide/create-control-panel.md
+++ b/docs/developer-guide/create-control-panel.md
@@ -192,7 +192,7 @@ my_choice_value = settings.my_choice
 ```
 
 
-## Register a control panel
+### Register a control panel
 
 To manually register a view as a control panel, add the following registration to your {file}`/profiles/default/controlpanel.xml`.
 
@@ -323,9 +323,10 @@ mypackage/
 
 ## REST API compatible control panels
 
-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.
+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.
 
-Create a Python module like `mypackage/controlpanel.py`:
+Create a Python module {file}`mypackage/controlpanel.py` as follows.
 
 ```python
 from plone.restapi.controlpanels import RegistryConfigletPanel
@@ -337,7 +338,7 @@ _ = MessageFactory("mypackage")
 
 @adapter(Interface, Interface)
 class MyAddonControlPanel(RegistryConfigletPanel):
-    """Volto-compatible REST API control panel for my addon settings."""
+    """Volto-compatible REST API control panel for my add-on settings."""
 
     schema = IMyControlPanelSettings
     schema_prefix = "my.addon"
@@ -347,7 +348,7 @@ class MyAddonControlPanel(RegistryConfigletPanel):
     group = "General"
 ```
 
-Then register the adapter in your ZCML configuration file:
+Then register the adapter in your ZCML configuration file.
 
 ```xml
 <!-- mypackage/configure.zcml or mypackage/controlpanel/configure.zcml -->
@@ -363,16 +364,26 @@ Then register the adapter in your ZCML configuration file:
 </configure>
 ```
 
-The `group` property in the control panel class corresponds to the control panel category in Volto:
-- `General`: General settings (corresponds to `plone-general`)
-- `Content`: Content-related settings (corresponds to `plone-content`)
-- `Users`: Users and groups settings (corresponds to `plone-users`)
-- `Security`: Security settings (corresponds to `plone-security`)
-- `Advanced`: Advanced settings (corresponds to `plone-advanced`)
+The `group` property in the control panel class corresponds to the control panel category in Volto.
+
+`General`
+:   General settings (corresponds to `plone-general`)
+
+`Content`
+:   Content-related settings (corresponds to `plone-content`)
+
+`Users`
+:   Users and groups settings (corresponds to `plone-users`)
+
+`Security`
+:   Security settings (corresponds to `plone-security`)
+
+`Advanced`
+:   Advanced settings (corresponds to `plone-advanced`)
 
 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.
 
-You will still need to set up the registry.xml with default values as described earlier.
+You will still need to set up {file}`registry.xml` with default values as described earlier.
 
 ```{seealso}
 See the chapter {ref}`training:controlpanel-label` from the Mastering Plone 6 Training.

From 27489e4a9a7e49171e03ec685c1061c5e5680beb Mon Sep 17 00:00:00 2001
From: Rohan Shaw <86848116+rohnsha0@users.noreply.github.com>
Date: Mon, 7 Apr 2025 07:39:56 +0530
Subject: [PATCH 07/10] Apply suggestions from code review

Co-authored-by: Steve Piercy <web@stevepiercy.com>
---
 docs/developer-guide/create-control-panel.md | 41 ++++++++++++--------
 1 file changed, 25 insertions(+), 16 deletions(-)

diff --git a/docs/developer-guide/create-control-panel.md b/docs/developer-guide/create-control-panel.md
index 767df5bd3..c197a4ede 100644
--- a/docs/developer-guide/create-control-panel.md
+++ b/docs/developer-guide/create-control-panel.md
@@ -1,16 +1,23 @@
 ---
 myst:
   html_meta:
-    "description": "How to create a control panel"
-    "property=og:description": "How to create a control panel"
-    "property=og:title": "Create a control panel"
-    "keywords": "Plone, create, control panel, plonecli, registry"
+    "description": "How to create a control panel in Plone for Classic UI and Volto"
+    "property=og:description": "How to create a control panel in Plone for Classic UI and Volto"
+    "property=og:title": "Create a control panel in Plone for Classic UI and Volto"
+    "keywords": "Plone, create, control panel, plonecli, registry, Classic UI, Volto, frontend, backend"
 ---
 
 (backend-controlpanels-label)=
 
 # Create a control panel
 
+This chapter describes how to create a control panel for your Plone add-on, whether accessed through either the Classic UI or Volto frontend.
+
+It also covers advanced topics—including how to group fields in your control panel—and provides a schema field reference, troubleshooting tips, control panel file structure, and a Plone REST API compatibility reference.
+
+
+## Creation approaches
+
 There are two approaches to create a control panel for your Plone add-on:
 
 -   [`plonecli`](https://pypi.org/project/plonecli/)
@@ -140,22 +147,22 @@ Create a {file}`mypackage/profiles/default/controlpanel.xml` in your package's G
 ```
 
 The category attribute can be one of the following values.
-These values correspond to the groups in Site Setup.
+These values correspond to the groups in {guilabel}`Site Setup`.
 
 `plone-general`
-:   General settings
+:   {guilabel}`General`
 
 `plone-content`
-:   Content-related settings
+:   {guilabel}`Content`
 
 `plone-users`
-:   Users and groups settings
+:   {guilabel}`Users`
 
 `plone-security`
-:   Security settings
+:   {guilabel}`Security`
 
 `plone-advanced`
-:   Advanced settings
+:   {guilabel}`Advanced`
 
 
 ### Set default values in the registry
@@ -217,6 +224,8 @@ To manually register a view as a control panel, add the following registration t
   </object>
 ```
 
+Your control panel should now appear in {guilabel}`Site Setup`.
+
 
 ## Use `FieldSet` to group fields
 
@@ -296,10 +305,10 @@ You'll need to perform one or more of the following steps.
 
 If your control panel doesn't appear or doesn't work as expected:
 
--   Verify that all ZCML is properly registered
--   Check for errors in the Plone error log
--   Ensure your GenericSetup profiles are correctly installed
--   Validate that the interface path in registry.xml matches your actual Python path
+-   Verify that all ZCML is properly registered.
+-   Check for errors in the Plone error log.
+-   Ensure your GenericSetup profiles are correctly installed.
+-   Validate that the interface path in {file}`registry.xml` matches your actual Python path.
 
 
 ## Example file structure
@@ -321,9 +330,9 @@ mypackage/
         └── registry.xml
 ```
 
-## REST API compatible control panels
+## REST API compatibility
 
-For better integration between backend and Volto, you can create REST API compatible control panels using the adapter pattern.
+For better integration between Plone's backend and its frontend 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.
 
 Create a Python module {file}`mypackage/controlpanel.py` as follows.

From d1175d522b3d87affb2ab0fa1b4ceeb5a687bb05 Mon Sep 17 00:00:00 2001
From: Rohan Shaw <rohnsha0@gmail.com>
Date: Mon, 14 Apr 2025 21:07:28 +0530
Subject: [PATCH 08/10] Add instructions for restarting Plone after manual
 control panel setup

---
 docs/developer-guide/create-control-panel.md | 30 ++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/developer-guide/create-control-panel.md b/docs/developer-guide/create-control-panel.md
index c197a4ede..ff86fb674 100644
--- a/docs/developer-guide/create-control-panel.md
+++ b/docs/developer-guide/create-control-panel.md
@@ -224,6 +224,36 @@ To manually register a view as a control panel, add the following registration t
   </object>
 ```
 
+After you perform the above steps for the manual process, you must restart the Plone site. To stop a running Plone instance, press {kbd}`ctrl-c` in the terminal where Plone is running. To start it again, use the appropriate command based on your installation method:
+
+````{tab-set}
+
+```{tab-item} Buildout
+To start a Plone instance installed with Buildout:
+`bin/instance fg`
+```
+
+```{tab-item} Pip
+To start a Plone instance installed with Pip:
+`bin/runwsgi -v instance/etc/zope.ini`
+```
+
+```{tab-item} Cookiecutter (Backend only)
+To start a Plone backend instance created with the Cookiecutter template:
+`make backend-start`
+```
+
+```{tab-item} Cookiecutter (Full stack)
+For a full stack setup with both backend and frontend:
+
+1. Start the backend in one terminal:
+`make backend-start`
+2. Start the frontend in another terminal:
+`make frontend-start`
+```
+
+````
+
 Your control panel should now appear in {guilabel}`Site Setup`.
 
 

From 2a65a7948c995bbc69049a191afbc746c365338b Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Tue, 15 Apr 2025 13:11:35 -0700
Subject: [PATCH 09/10] Simplify MyST markup, convert inline literals to use
 code blocks with a syntax highlighter language

---
 docs/developer-guide/create-control-panel.md | 44 ++++++++++++--------
 1 file changed, 27 insertions(+), 17 deletions(-)

diff --git a/docs/developer-guide/create-control-panel.md b/docs/developer-guide/create-control-panel.md
index ff86fb674..d053bb174 100644
--- a/docs/developer-guide/create-control-panel.md
+++ b/docs/developer-guide/create-control-panel.md
@@ -226,34 +226,44 @@ To manually register a view as a control panel, add the following registration t
 
 After you perform the above steps for the manual process, you must restart the Plone site. To stop a running Plone instance, press {kbd}`ctrl-c` in the terminal where Plone is running. To start it again, use the appropriate command based on your installation method:
 
-````{tab-set}
+`````{tab-set}
 
-```{tab-item} Buildout
-To start a Plone instance installed with Buildout:
-`bin/instance fg`
+````{tab-item} buildout
+```shell
+bin/instance fg
 ```
+````
 
-```{tab-item} Pip
-To start a Plone instance installed with Pip:
-`bin/runwsgi -v instance/etc/zope.ini`
+````{tab-item} pip
+```shell
+bin/runwsgi -v instance/etc/zope.ini
 ```
+````
 
-```{tab-item} Cookiecutter (Backend only)
-To start a Plone backend instance created with the Cookiecutter template:
-`make backend-start`
+````{tab-item} Cookieplone
+For a backend add-on only, use the following command.
+
+```shell
+make backend-start
 ```
 
-```{tab-item} Cookiecutter (Full stack)
-For a full stack setup with both backend and frontend:
+For both a backend and frontend add-on project, open two separate terminal sessions.
+
+In the first session, start the backend.
 
-1. Start the backend in one terminal:
-`make backend-start`
-2. Start the frontend in another terminal:
-`make frontend-start`
+```shell
+make backend-start
 ```
 
+In the second session, start the frontent.
+
+```shell
+make frontend-start
+```
 ````
 
+`````
+
 Your control panel should now appear in {guilabel}`Site Setup`.
 
 
@@ -426,4 +436,4 @@ You will still need to set up {file}`registry.xml` with default values as descri
 
 ```{seealso}
 See the chapter {ref}`training:controlpanel-label` from the Mastering Plone 6 Training.
-```
\ No newline at end of file
+```

From e1b4aac22cfb205ee16b506a4e03da3f0c057d9b Mon Sep 17 00:00:00 2001
From: Rohan Shaw <rohnsha0@gmail.com>
Date: Wed, 16 Apr 2025 21:59:53 +0530
Subject: [PATCH 10/10] Refactor section headers in control panel documentation
 for consistency

---
 docs/developer-guide/create-control-panel.md | 46 ++++++++++----------
 1 file changed, 22 insertions(+), 24 deletions(-)

diff --git a/docs/developer-guide/create-control-panel.md b/docs/developer-guide/create-control-panel.md
index d053bb174..7f9d660f1 100644
--- a/docs/developer-guide/create-control-panel.md
+++ b/docs/developer-guide/create-control-panel.md
@@ -24,7 +24,7 @@ There are two approaches to create a control panel for your Plone add-on:
 -   manual
 
 
-## `plonecli`
+### `plonecli`
 
 To add a control panel to your add-on, you can use [`plonecli`](https://pypi.org/project/plonecli/) as follows.
 
@@ -35,7 +35,7 @@ plonecli add controlpanel
 This creates the control panel Python file in the control panel's folder where you can define your control panel schema fields.
 
 
-## Manual
+### Manual
 
 To manually create a control panel, go through the following steps.
 
@@ -44,7 +44,7 @@ To manually create a control panel, go through the following steps.
 -   Add the control panel to the Plone control panel listing.
 -   Set default values in the registry.
 
-### Define the settings interface and form
+#### Define the settings interface and form
 
 Create a Python module, {file}`mypackage/controlpanel/settings.py`, that defines your control panel's settings interface and form class as follows.
 
@@ -86,7 +86,7 @@ MyControlPanelView = layout.wrap_form(MyControlPanelForm, ControlPanelFormWrappe
 ```
 
 
-### Register the control panel view
+#### Register the control panel view
 
 Create a file {file}`mypackage/controlpanel/configure.zcml` with the following content to register the control panel view in ZCML.
 
@@ -124,7 +124,7 @@ Make sure to include the above file in your package's main {file}`mypackage/conf
 </configure>
 ```
 
-### Add the control panel entry
+#### Add the control panel entry
 
 Create a {file}`mypackage/profiles/default/controlpanel.xml` in your package's GenericSetup profile with the following content to add your control panel to the Plone control panel listing.
 
@@ -165,7 +165,7 @@ These values correspond to the groups in {guilabel}`Site Setup`.
 :   {guilabel}`Advanced`
 
 
-### Set default values in the registry
+#### Set default values in the registry
 
 Define default values for your settings in {file}`mypackage/profiles/default/registry.xml`.
 
@@ -182,24 +182,7 @@ Define default values for your settings in {file}`mypackage/profiles/default/reg
 ```
 
 
-### Access your settings in code
-
-You can access your settings in Python code as follows.
-
-```python
-from plone.registry.interfaces import IRegistry
-from zope.component import getUtility
-
-registry = getUtility(IRegistry)
-settings = registry.forInterface(IMyControlPanelSettings, prefix="my.addon")
-
-# Now you can access the settings
-my_setting_value = settings.my_setting
-my_choice_value = settings.my_choice
-```
-
-
-### Register a control panel
+#### Register a control panel
 
 To manually register a view as a control panel, add the following registration to your {file}`/profiles/default/controlpanel.xml`.
 
@@ -266,6 +249,21 @@ make frontend-start
 
 Your control panel should now appear in {guilabel}`Site Setup`.
 
+## Access your settings in code
+
+You can access your settings in Python code as follows.
+
+```python
+from plone.registry.interfaces import IRegistry
+from zope.component import getUtility
+
+registry = getUtility(IRegistry)
+settings = registry.forInterface(IMyControlPanelSettings, prefix="my.addon")
+
+# Now you can access the settings
+my_setting_value = settings.my_setting
+my_choice_value = settings.my_choice
+```
 
 ## Use `FieldSet` to group fields