Skip to content

Adds docs for creating custom control panel #1909 revision #1939

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 10 commits into
base: rohnsha0-control-panel
Choose a base branch
from
150 changes: 150 additions & 0 deletions docs/developer-guide/create-backend-add-on.md
Original file line number Diff line number Diff line change
@@ -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`
Comment on lines +28 to +31
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- You've installed Plone for development through either of the following methods.
- {doc}`/admin-guide/install-buildout`
- {doc}`/admin-guide/install-pip`

we dont need to have Plone installed for creating a backend addon (it is an optional).

plonecli create addon src/collective.myaddon

creates a backend addon, changing the directory and running:

plonecli build

builds the addon which can be run and previewed using

plonecli serve

runs the the plone server using classic ui from the Plone Version defined during creation of addon or the .mrbob global config

additionally, we can integrate the same addon using local.cfg file in buildouts


- {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`
```
130 changes: 93 additions & 37 deletions docs/developer-guide/create-control-panel.md
Original file line number Diff line number Diff line change
@@ -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"
```

1 change: 1 addition & 0 deletions docs/developer-guide/index.md
Original file line number Diff line number Diff line change
@@ -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
4 changes: 3 additions & 1 deletion docs/glossary.md
Original file line number Diff line number Diff line change
@@ -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