From 579492d9c279b001b71b520448ea58f7c163a505 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 17 Apr 2025 00:31:38 -0700 Subject: [PATCH 01/10] Adds docs for creating custom control panel #1909 revision --- docs/developer-guide/create-control-panel.md | 48 +++++++++++++------- 1 file changed, 31 insertions(+), 17 deletions(-) diff --git a/docs/developer-guide/create-control-panel.md b/docs/developer-guide/create-control-panel.md index 7f9d660f1..ee73f2479 100644 --- a/docs/developer-guide/create-control-panel.md +++ b/docs/developer-guide/create-control-panel.md @@ -15,36 +15,41 @@ This chapter describes how to create a control panel for your Plone add-on, whet 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. +[`plonecli`](https://pypi.org/project/plonecli/) automates all the manual steps to create a control panel. +This chapter will walk through all those steps as well. -## Creation approaches -There are two approaches to create a control panel for your Plone add-on: +## `plonecli` -- [`plonecli`](https://pypi.org/project/plonecli/) -- manual +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 +pip install plonecli --user +``` -### `plonecli` - -To add a control panel to your add-on, you can use [`plonecli`](https://pypi.org/project/plonecli/) as follows. +You can automatically create a control panel using the following command. ```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. +It also goes through all the following steps to create a control panel. -### 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 + +### 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 +91,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. @@ -107,7 +112,7 @@ Create a file {file}`mypackage/controlpanel/configure.zcml` with the following c ``` -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 +129,8 @@ Make sure to include the above file in your package's main {file}`mypackage/conf ``` -#### 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 +171,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 +188,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, add the following registration to your {file}`/profiles/default/controlpanel.xml`. ```xml @@ -207,7 +213,12 @@ 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: + +## Load your control panel + +After performing the above steps, 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} @@ -249,6 +260,7 @@ 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. @@ -265,6 +277,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. @@ -368,6 +381,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. From e7413d4d0d74c7a33cfaaa5433a487b51b088e35 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 17 Apr 2025 00:34:31 -0700 Subject: [PATCH 02/10] remove extra space --- docs/developer-guide/create-control-panel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guide/create-control-panel.md b/docs/developer-guide/create-control-panel.md index ee73f2479..bb2261f6d 100644 --- a/docs/developer-guide/create-control-panel.md +++ b/docs/developer-guide/create-control-panel.md @@ -40,7 +40,7 @@ It also goes through all the following steps to create a control panel. ## Steps to create a control panel -Whether performed automatically with `plonecli` or manually, the following steps are required to create a control panel. +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. From c3a4efb89cee49b40a6e1a8fe7678fbfa1d5135e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 17 Apr 2025 14:44:34 -0700 Subject: [PATCH 03/10] Blackify code, removing `u` designation since we're on Python 3 --- docs/developer-guide/create-control-panel.md | 30 ++++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/developer-guide/create-control-panel.md b/docs/developer-guide/create-control-panel.md index bb2261f6d..6bd6e739c 100644 --- a/docs/developer-guide/create-control-panel.md +++ b/docs/developer-guide/create-control-panel.md @@ -64,18 +64,18 @@ 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): @@ -83,7 +83,7 @@ class MyControlPanelForm(RegistryEditForm): schema = IMyControlPanelSettings schema_prefix = "my.addon" - label = u"My Addon Settings" + label = "My Addon Settings" # Wrap the form with plone.z3cform's ControlPanelFormWrapper to get the Plone # control panel look and feel @@ -288,26 +288,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 ) ``` From 0034ae63640a55fe4b99f786fd59ae66b8bf8567 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 17 Apr 2025 14:46:40 -0700 Subject: [PATCH 04/10] s/Addon/add-on --- docs/developer-guide/create-control-panel.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developer-guide/create-control-panel.md b/docs/developer-guide/create-control-panel.md index 6bd6e739c..a8c52514c 100644 --- a/docs/developer-guide/create-control-panel.md +++ b/docs/developer-guide/create-control-panel.md @@ -83,7 +83,7 @@ class MyControlPanelForm(RegistryEditForm): schema = IMyControlPanelSettings schema_prefix = "my.addon" - label = "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 @@ -139,7 +139,7 @@ Create a {file}`mypackage/profiles/default/controlpanel.xml` in your package's G Date: Fri, 18 Apr 2025 09:17:53 +0530 Subject: [PATCH 05/10] Enhance documentation for creating control panels with `plonecli`, including usage in non-add-on projects and detailed steps for manual creation. --- docs/developer-guide/create-control-panel.md | 26 +++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/developer-guide/create-control-panel.md b/docs/developer-guide/create-control-panel.md index a8c52514c..7bbebe8c0 100644 --- a/docs/developer-guide/create-control-panel.md +++ b/docs/developer-guide/create-control-panel.md @@ -28,7 +28,7 @@ Since it's used for development, it's advantageous to install it in your user en pip install plonecli --user ``` -You can automatically create a control panel using the following command. +`plonecli` is primarily designed for scaffolding Plone add-ons. If you have an existing add-on created with `plonecli`, you can automatically create a control panel using the following command while in the add-on root directory: ```shell plonecli add controlpanel @@ -37,6 +37,30 @@ 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. It also goes through all the following steps to create a control panel. +### Using `plonecli` in a non-add-on project + +If you're working on a Plone project that wasn't created as an add-on (for example, a custom policy package or a custom theme package), you have two options: + +1. **Create the control panel manually**: Follow the steps in this chapter to create all necessary files by hand. + +2. **Use `plonecli` partially**: You can use `plonecli` to generate the control panel code in a temporary add-on and then copy the relevant files to your project. For example: + + ```shell + # Create a temporary add-on + mkdir temp_addon + cd temp_addon + plonecli create addon temp.addon + cd temp.addon + + # Generate the control panel + plonecli add controlpanel + + # Examine and copy the generated files to your project + # You'll need to adapt paths and import statements + ``` + + After generating the files, you'll need to adapt them to fit your project's structure and naming conventions. + ## Steps to create a control panel From f5db4a54d5fc6b401308b2d2609e31d8e70cbef6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 18 Apr 2025 01:19:44 -0700 Subject: [PATCH 06/10] Add new page for how to create a backend add-on --- docs/developer-guide/create-backend-add-on.md | 148 ++++++++++++++++++ docs/developer-guide/index.md | 1 + 2 files changed, 149 insertions(+) create mode 100644 docs/developer-guide/create-backend-add-on.md diff --git a/docs/developer-guide/create-backend-add-on.md b/docs/developer-guide/create-backend-add-on.md new file mode 100644 index 000000000..ac6436bcc --- /dev/null +++ b/docs/developer-guide/create-backend-add-on.md @@ -0,0 +1,148 @@ +--- +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]: + + + +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 +venv/bin/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 +``` + + +### 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 your add-on. +Then issue the command to add a feature as a subtemplate, and answer the prompts. + +```shell +cd src/collective.myaddon/ +../venv/bin/plonecli add