Adds docs for creating custom control panel #1909 revision

docs/developer-guide/create-backend-add-on.md

@@ -0,0 +1,150 @@
+---
+myst:
+  html_meta:
+    "description": "Create a backend add-on for Plone"
+    "property=og:description": "Create a backend add-on for Plone"
+    "property=og:title": "Create a backend add-on for Plone"
+    "keywords": "Plone, create, add-on, plonecli, mr.bob, bobtemplates.plone, Cookieplone, buildout, backend"
+---
+
+(create-backend-add-on-label)=
+
+# Create backend add-on
+
+This chapter describes how to create a backend add-on for Plone using {term}`plonecli`.
+
+```{note}
+This chapter does not apply for either of the following methods, because they create a backend add-on, as well as install Plone for development.
+
+-   {doc}`/install/create-project-cookieplone`
+-   `uvx cookieplone backend_addon` command
+
+Additionally, if you created a frontend add-on only project using the command `uvx cookieplone frontend_addon` and later realized you need a backend add-on to complement it, then you can create a new project using the command `uvx cookieplone` to generate both the frontend and backend add-ons, then finally move files from your existing project to the new one.
+```
+
+
+## Prerequisites
+
+-   You've installed Plone for development through either of the following methods.
+
+    -   {doc}`/admin-guide/install-buildout`
+    -   {doc}`/admin-guide/install-pip`
+
+-   {term}`plonecli` is designed for developing backend add-ons—or packages—for Plone.
+
+    You can install `plonecli` as any other Python package.
+    Since it's used for development, it's advantageous to install it in your user environment, thus making it available to all your Plone projects.
+
+    ```shell
+    python -m pip install plonecli --user
+    ```
+
+
+## `plonecli` usage
+
+Change your working directory to the root of your Plone development installation for your project.
+Create the backend add-on with the following command.
+
+```shell
+plonecli create addon src/collective.myaddon
+```
+
+Answer the prompts by either hitting the {kbd}`Enter` key to accept the default value, or entering a custom value.
+
+```console
+RUN: bobtemplates.plone:addon -O src/collective.myaddon
+
+Welcome to mr.bob interactive mode. Before we generate directory structure, some questions need to be answered.
+
+Answer with a question mark to display help.
+Values in square brackets at the end of the questions show the default value if there is no answer.
+
+
+--> Author's name [YOUR NAME]: 
+
+--> Author's email [YOUR EMAIL]: 
+
+--> Author's GitHub username:
+
+--> Package description [An add-on for Plone]: 
+
+--> Do you want me to initialize a GIT repository in your new package? (y/n) [y]: 
+
+--> Plone version [6.0.0]: 
+
+--> Python version for virtualenv [python3]: 
+
+--> Do you want me to activate VS Code support? (y/n) [y]: 
+
+<snip>
+
+Should we run?:
+git add .
+git commit -m Create addon: collective.myaddon
+in: /path/to/buildout/project/src/collective.myaddon
+[y]/n: 
+RUN: git add .
+RUN: git commit -m Create addon: collective.myaddon
+
+Generated file structure at /path/to/buildout/project/src/collective.myaddon/src/collective.myaddon
+```
+
+You can now start developing your new add-on and add features to it.
+
+
+### Available templates
+
+To list the available {term}`mr.bob` templates, issue the following command.
+
+```shell
+plonecli -l
+```
+
+You should see output similar to the following.
+
+```console
+ - addon
+  - behavior
+  - content_type
+  - controlpanel
+  - form
+  - indexer
+  - mockup_pattern
+  - portlet
+  - restapi_service
+  - site_initialization
+  - subscriber
+  - svelte_app
+  - theme
+  - theme_barceloneta
+  - theme_basic
+  - upgrade_step
+  - view
+  - viewlet
+  - vocabulary
+ - buildout
+```
+
+
+(backend-add-on-subtemplates-label)=
+
+### Subtemplates
+
+You can add different features to your add-on through subtemplates, using any of the available mr.bob templates.
+You can use them multiple times to create different features of the same type, such as two different content types.
+
+First change your working directory into the root of your add-on.
+Then issue the command to add a feature as a subtemplate, and answer the prompts.
+
+```shell
+cd src/collective.myaddon/
+plonecli add <TEMPLATE>
+```
+
+```{seealso}
+The `plonecli` `README.md` has a section on [Usage](https://github.com/plone/plonecli?tab=readme-ov-file#usage).
+```
+
+```{seealso}
+-   {doc}`create-control-panel`
+```

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

@@ -13,40 +13,54 @@ myst:
 
 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.
+This chapter begins with automating all the manual steps to create a control panel using {term}`plonecli`.
+It then walks through all these manual steps.
 
+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`
 
--   [`plonecli`](https://pypi.org/project/plonecli/)
--   manual
+> **Note**: This method only works when developing Plone add-ons. If you're working on a Plone project that is not an add-on, you'll need to follow the manual steps described in the next section.
 
+Given you've already created a Plone add-on using one of the following methods.
 
-### `plonecli`
+-   {doc}`/install/create-project-cookieplone`
+-   {doc}`create-backend-add-on`
 
-To add a control panel to your add-on, you can use [`plonecli`](https://pypi.org/project/plonecli/) as follows.
+Then, as described in {ref}`backend-add-on-subtemplates-label`, from the root of your add-on, issue the following command to add a control panel as a subtemplate in your add-on.
 
 ```shell
 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.
+This creates Python modules in the folder {file}`src/collective/myaddon/controlpanel`.
+This is where you can define your control panel schema fields, as described in {ref}`define-the-settings-interface-and-form-label`.
+
+`plonecli` also goes through all the steps to create a control panel, as described in {ref}`steps-to-create-a-control-panel-label`.
+
 
+(steps-to-create-a-control-panel-label)=
 
-### Manual
+## Steps to create a control panel
 
-To manually create a control panel, go through the following steps.
+Whether performed automatically with `plonecli` or manually, the following steps are required to create a control panel.
 
 -   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.
+-   Register the control panel in XML.
 
-#### Define the settings interface and form
+The code examples are for illustrative purposes only, and may differ from those that `plonecli` generates and what you'll actually create.
+The language addresses you as if you'd manually perform these steps.
 
-Create a Python module, {file}`mypackage/controlpanel/settings.py`, that defines your control panel's settings interface and form class as follows.
+
+(define-the-settings-interface-and-form-label)=
+
+### 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, or schema, as follows.
 
 ```python
 # mypackage/controlpanel/settings.py
@@ -59,34 +73,36 @@ 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',
+        title="My Setting",
+        description="Enter the value for my setting",
         required=False,
-        default=u''
+        default=""
     )
 
     my_choice = schema.Choice(
-        title=u'My Choice',
-        description=u'Select a value for my choice',
+        title="My Choice",
+        description="Select a value for my choice",
         required=False,
-        default=u'value3',
-        values=['value1', 'value2', 'value3']
+        default="value3",
+        values=["value1", "value2", "value3"]
     )
 
 class MyControlPanelForm(RegistryEditForm):
     """Control panel form."""
 
     schema = IMyControlPanelSettings
     schema_prefix = "my.addon"
-    label = u"My Addon Settings"
+    label = "My add-on settings"
 
 # Wrap the form with plone.z3cform's ControlPanelFormWrapper to get the Plone
 # control panel look and feel
 MyControlPanelView = layout.wrap_form(MyControlPanelForm, ControlPanelFormWrapper)
 ```
 
 
-#### Register the control panel view
+### Register the control panel view
+
+This step registers a view to display the control panel defined in the previous step.
 
 Create a file {file}`mypackage/controlpanel/configure.zcml` with the following content to register the control panel view in ZCML.
 
@@ -107,7 +123,7 @@ Create a file {file}`mypackage/controlpanel/configure.zcml` with the following c
 </configure>
 ```
 
-Make sure to include the above file in your package's main {file}`mypackage/configure.zcml` as shown by the highlighted line below.
+Include the above file in your package's main {file}`mypackage/configure.zcml`, as shown by the highlighted line below.
 
 {emphasize-lines="9"}
 ```xml
@@ -124,7 +140,8 @@ 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.
 
@@ -133,7 +150,7 @@ Create a {file}`mypackage/profiles/default/controlpanel.xml` in your package's G
 <?xml version="1.0"?>
 <object name="portal_controlpanel">
     <configlet
-        title="My Addon Settings"
+        title="My add-on settings"
         action_id="my-controlpanel"
         appId="my.addon"
         category="plone-general"
@@ -165,7 +182,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,9 +199,9 @@ Define default values for your settings in {file}`mypackage/profiles/default/reg
 ```
 
 
-#### Register a control panel
+### Register the control panel
 
-To manually register a view as a control panel, add the following registration to your {file}`/profiles/default/controlpanel.xml`.
+To register the view as a control panel so that it appears in the {guilabel}`Site Setup`, add the following registration to your {file}`/profiles/default/controlpanel.xml`.
 
 ```xml
 <?xml version="1.0"?>
@@ -207,7 +224,15 @@ 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:
+
+## Load your control panel
+
+After performing the above steps, you must perform below mentioned steps as they are important to load the profile (including registry) to the project.
+
+### Restarting the instance
+
+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}
 
@@ -247,8 +272,37 @@ make frontend-start
 
 `````
 
+### Importing the Generic Profile
+
+​To apply your newly created control panel in a Plone project, you'll need to manually import the GenericSetup profile associated with your project. Here's how you can do this:​
+
+#### Access the ZMI (Zope Management Interface)
+
+Navigate to your Plone site's URL and append /manage to access the ZMI. For example:​
+
+```bash
+http://localhost:8080/Plone/manage
+
+```
+
+#### Navigate to the Setup Tool
+
+In the ZMI, locate and click on portal_setup.​
+
+#### Import the Profile
+
+- Within portal_setup, go to the Import tab.
+- From the Profile dropdown menu, select your project's profile. This is typically named in the format:​
+```
+profile-your.projectname:default
+```
+- Click the Import All Steps button to apply the profile.​
+
+This process will register your control panel and any associated registry settings defined in your registry.xml and controlpanel.xml files.
+
 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.
@@ -265,6 +319,7 @@ my_setting_value = settings.my_setting
 my_choice_value = settings.my_choice
 ```
 
+
 ## Use `FieldSet` to group fields
 
 For complex control panels, you can group fields together as in the following example.
@@ -275,26 +330,26 @@ from plone.supermodel import model
 class IMyControlPanelSettings(Interface):
 
     model.fieldset(
-        'advanced',
-        label=u"Advanced Settings",
-        fields=['advanced_setting1', 'advanced_setting2']
+        "advanced",
+        label="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',
+        title="My Setting",
+        description="Enter the value for my setting",
         required=False
     )
 
     # Advanced settings
     advanced_setting1 = schema.TextLine(
-        title=u'Advanced Setting 1',
+        title="Advanced Setting 1",
         required=False
     )
 
     advanced_setting2 = schema.Bool(
-        title=u'Advanced Setting 2',
+        title="Advanced Setting 2",
         default=False
     )
 ```
@@ -353,7 +408,7 @@ If your control panel doesn't appear or doesn't work as expected:
 
 Below is a complete example file structure for a basic add-on with a control panel.
 
-```
+```text
 mypackage/
 ├── __init__.py
 ├── configure.zcml
@@ -368,6 +423,7 @@ mypackage/
         └── registry.xml
 ```
 
+
 ## REST API compatibility
 
 For better integration between Plone's backend and its frontend Volto, you can create REST API compatible control panels using the adapter pattern.
@@ -391,7 +447,7 @@ class MyAddonControlPanel(RegistryConfigletPanel):
     schema_prefix = "my.addon"
     configlet_id = "my-controlpanel"
     configlet_category_id = "plone-general"
-    title = _("My Addon Settings")
+    title = _("My add-on settings")
     group = "General"
 ```
 

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-backend-add-on
 create-control-panel
 create-a-distribution
 standardize-python-project-configuration

docs/glossary.md

@@ -586,8 +586,10 @@ Zope instance
 ZPT
     Zope Page Template is a template language for Python.
 
-plonecli
+Plone CLI
+`plonecli`
     The [`plonecli`](https://pypi.org/project/plonecli/) helps developers to create Plone add-ons in a modular and reproducible way.
+    It uses logic from {term}`bobtemplates.plone`.
 
 ZCA
 Zope Component Architecture