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

stevepiercy · 2025-04-17T07:33:18Z

@rohnsha0 please take a look at these revisions. I haven't been able to express myself clearly in a review. I think this PR simplifies its structure and makes it flow better. Please let me know. Thank you!

📚 Documentation preview 📚:

stevepiercy · 2025-04-17T07:36:36Z

@rohnsha0 one thing that still confuses me are these two headings:

Register the control panel view

Register the control panel

What's the difference, other than one is in ZCML and the other in XML?

rohnsha0 · 2025-04-17T13:45:06Z

Register the control panel view

It register the view (different field in the controlpanel) and once registered can be accessed via given URL directly...
eg. https://classic.demo.plone.org/@@discussion-controlpanel

Register the control panel

It register the control panel i. e. once registered the control panel appears on the Site Setup screen
eg.

rohnsha0

LGTM! Can be merged into the docs

stevepiercy · 2025-04-17T21:05:27Z

@rohnsha0 thanks for the explanation. I'll push an update, then merge.

stevepiercy · 2025-04-17T21:39:46Z

I'm concerned that plonecli does not work with Cookieplone.

$ .venv/bin/plonecli add controlpanel
/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/case_conversion/case_conversion.py:202: SyntaxWarning: invalid escape sequence '\c'
  """Return text in backslash\case style.
/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/case_conversion/case_parse.py:28: SyntaxWarning: invalid escape sequence '\p'
  upper = regex.compile(u'^[\p{Lu}]$')
/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/case_conversion/case_parse.py:29: SyntaxWarning: invalid escape sequence '\p'
  sep = regex.compile(u'^[^\p{Ll}\p{Lu}\p{Nd}]$')
/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/case_conversion/case_parse.py:30: SyntaxWarning: invalid escape sequence '\p'
  notsep = regex.compile(u'^[\p{Ll}\p{Lu}\p{Nd}]$')
/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/case_conversion/case_parse.py:97: SyntaxWarning: invalid escape sequence '\p'
  valid_acronym = regex.compile(u'^[\p{Ll}\p{Lu}\p{Nd}]+$')

RUN: mrbob bobtemplates.plone:controlpanel

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.



RUN: git status --porcelain --ignore-submodules
git status result:
----------------------------
b'?? docs/project-title/\n?? docs/uv.lock\n?? frontend/pnpm-lock.yaml\n'
--> Please commit your changes, before using a sub-template! Continue anyway? [n/y] [n]: y

--> Name of the Control Panels's Python class? [MyFeaturedControlPanel]: 

>>> reading Plone version from bobtemplate.cfg

Traceback (most recent call last):
  File "/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/bin/plonecli", line 10, in <module>
    sys.exit(cli())
             ^^^^^
  File "/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/click/core.py", line 1719, in invoke
    rv.append(sub_ctx.command.invoke(sub_ctx))
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/click/decorators.py", line 33, in new_func
    return f(get_current_context(), *args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/plonecli/cli.py", line 128, in add
    mrbobmain(mrbob_args)
  File "/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/mrbob/cli.py", line 175, in main
    c.render()
  File "/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/mrbob/configurator.py", line 186, in render
    render_structure(self.template_dir,
  File "/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/.venv/lib/python3.12/site-packages/mrbob/rendering.py", line 95, in render_structure
    os.mkdir(abs_dir)
FileNotFoundError: [Errno 2] No such file or directory: '/Users/stevepiercy/projects/Plone/cookieplone-templates/fluffy/backend/backend/controlpanels'

And @rohnsha0 reported an issue with what I think is buildout in plone/plonecli#87.

We might need to rip out plonecli if we can't get it to work.

stevepiercy · 2025-04-17T21:42:42Z

@rohnsha0 also I don't think we need to use u"foo" Unicode designations any more, now that we're using Python 3. Can you verify?

stevepiercy · 2025-04-17T23:34:24Z

@rohnsha0 did you try the plonecli process that you documented? The set up process is omitted. I also could not get it to work with Cookieplone, only with buildout. pip is untested. We can't merge this with inaccurate information or guess work.

rohnsha0 · 2025-04-18T02:15:30Z

@stevepiercy it works everytime!

What did u do?! If you could list out the seq

rohnsha0 · 2025-04-18T03:03:31Z

Ah, Sorry. We can add a note a that ploneclli works only with addons and not on the entire plone project... or else ig we should remove the plonecli section altogether. I thought it would work here too..

rohnsha0 · 2025-04-18T03:05:10Z

And @rohnsha0 reported an issue with what I think is buildout in plone/plonecli#87.

it was something which was related to version pinning. it solved the same by adding a explicit version pin but just listed for tracking purpose!

rohnsha0 · 2025-04-18T03:06:49Z

@rohnsha0 did you try the plonecli process that you documented? The set up process is omitted. I also could not get it to work with Cookieplone, only with buildout. pip is untested. We can't merge this with inaccurate information or guess work.

i somehow made it work with cookieplone somehow but not tested with pip

stevepiercy · 2025-04-18T03:19:25Z

@stevepiercy it works everytime!

What did u do?! If you could list out the seq

I did exactly what you documented, using a buildout installation.

plonecli add controlpanel

Resulted in the following console output.

Usage: plonecli add [OPTIONS] TEMPLATE
Try 'plonecli add -h' for help.

Error: The "add" command is only allowed within an existing package.

See also what I tried for Cookieplone in #1939 (comment).

Clearly there are some steps missing.

rohnsha0 · 2025-04-18T03:31:45Z

See also what I tried for Cookieplone in #1939 (comment).

the same i am getting too..
Ig we should remove the plonecli thing... as manual processes i have tried and tested

…cluding usage in non-add-on projects and detailed steps for manual creation.

stevepiercy · 2025-04-18T03:49:13Z

We also have nothing for Plone 6 Documentation about how to create a Plone add-on for the backend with plonecli, which is a prerequisite to creating a control panel for the add-on. I dug up these links from 5.2.

https://5.docs.plone.org/search.html?q=plonecli&check_keywords=yes&area=default

The first four links are duplicates that point the reader to plonecli's repo. Hilariously, the most relevant content is buried under the title Installing Plone on a Windows 10 Linux Subsystem for Development. I'm not making this up! I see why first-timers can't get started with Plone backend. It's not a matter of not wanting to get started, but there's no clear documented direction.

rohnsha0 · 2025-04-18T03:55:37Z

We also have nothing for Plone 6 Documentation about how to create a Plone add-on for the backend with plonecli, which is a prerequisite to creating a control panel for the add-on. I dug up these links from 5.2.

PloneCLI's readme gives some info on how to create a addon (it doesnt use the term "backend addon") but it gives a rough idea on how to create it using the tool.
see: https://github.com/plone/plonecli?tab=readme-ov-file#creating-a-plone-add-on

stevepiercy · 2025-04-18T08:22:47Z

@rohnsha0 I added a new page that should separate the concerns of creating a backend add-on and creating a control panel. The latter is actually the creation of a subtemplate. This will change the structure of the control panel file once more.

- Add reference targets and labels

stevepiercy · 2025-04-18T09:44:54Z

I've pushed this as far as possible. I was not able to get the control panel to load from the steps I wrote up using plonecli and buildout. I'm out of my depth here. I'm afraid someone else will need to step in and fill in the blanks.

rohnsha0 · 2025-04-18T10:26:19Z

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

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


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

I don't know what I'm doing. Please amend the docs so that a complete idiot (me) who knows nothing about how to create a backend add-on with a control panel can be successful. I've read docs from 5.2, buildout, plonecli, and it's all over the place. There's no cohesive process.

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

How can you view it in your Site Setup if you don't have Plone installed?

You also did not include any of the above steps in your revision.

I want to take care to avoid "crossing the streams". If readers jump between different procedures and do things in the wrong context, then we're harming them. Any modifications need to flow well.

@rohnsha0 does your comment and suggestion still apply? Please reply or resolve this comment. Thank you!

…importing the Generic Profile and clarifying buildout steps.

rohnsha0 · 2025-04-18T15:08:48Z

@stevepiercy, I have completed everything from my end and according to me it looks complete! and i have verified everything! and works on my machine...

davisagli · 2025-04-18T20:37:29Z

I'm concerned that plonecli does not work with Cookieplone.

There are some updates needed since the recent refactoring of the backend addon template. There's some work in progress in plone/bobtemplates.plone#584

MrTango · 2025-04-23T14:00:49Z

Some suggestions:

add an upgrade step via plonecli to update the database with the new settings, it's one command ;)
add a chapter with infos how to add an upgrade step or better add a separate chapter upgrade steps under "backend" and describe it there and reference it here

MrTango · 2025-04-23T16:22:27Z

@stevepiercy I'm wondering a bit why this should be in developer guide?
As i see it, things like what is a control panel, Python + zcml registration is reference documentation.
Like we have in frontend/backend/classic ui.
The new sections on the front page are very confusing for me.
Maybe if you have time next week, we cal talk a bit about the strategy there?
I'm really trying my best to work on the docs from time to time, but i feel a bit lost with the recent changes.
And i don't want to work in a different direction than others.

stevepiercy · 2025-04-23T22:23:43Z

@stevepiercy I'm wondering a bit why this should be in developer guide?

@MrTango for background and a full explanation, start with PLIP: Plone 7 Documentation Layout, Structure, Theme, and Search to Improve Usability.

After reviewing that, if you still have questions, I'm happy to have a call via Discord anytime. I want feedback, especially if it improves and clarifies the PLIP so we're all going in the same direction.

Although I targeted Plone 7, I'd love to have it for Plone 6.2 before PloneConf 2025.

stevepiercy · 2025-06-02T11:00:39Z

plone/bobtemplates.plone#584 was merged. Let's revisit this PR.

stevepiercy · 2025-09-22T03:29:13Z

plone/bobtemplates.plone#584 was merged. Let's revisit this PR.

Ping @rohnsha0. I'd love to get this finished before PloneConf 2025.

rohnsha0 · 2025-09-22T13:04:13Z

plone/bobtemplates.plone#584 was merged. Let's revisit this PR.

Ping @rohnsha0. I'd love to get this finished before PloneConf 2025.

sorry @stevepiercy for being so late for replying.. ill look into this PR in coming days. thanks for the patience ;)

…ches, prerequisites, and steps for both automated and manual methods.

rohnsha0 · 2025-09-22T17:13:19Z

@stevepiercy I have refined the docs and its structure as per my knowledge... @MrTango, do you have any more things to add?! since last time you were working with plonecli

- Add reference labels and targets, instead of copy-paste - Use correct structural markup instead of cosmetic markup - Add synonym for ZMI to glossary

stevepiercy

I've completed my revisions of @rohnsha0's revisions.

Could I get another final review from @MrTango, @rohnsha0, @davisagli, and anyone else who may have experience or interest in these two topics? Thank you!

stevepiercy · 2025-04-18T06:23:20Z

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

 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


@rohnsha0 Why would a developer create either a policy or custom theme package that is not an add-on? Is that the same as hacking on Plone core?

Also why would either a policy or custom theme package need a control panel? I can't think of such a scenario, but maybe you've done this?

stevepiercy · 2025-04-18T10:56:21Z

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

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


I don't know what I'm doing. Please amend the docs so that a complete idiot (me) who knows nothing about how to create a backend add-on with a control panel can be successful. I've read docs from 5.2, buildout, plonecli, and it's all over the place. There's no cohesive process.

stevepiercy · 2025-04-18T21:05:28Z

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

+-   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).

How can you view it in your Site Setup if you don't have Plone installed?

You also did not include any of the above steps in your revision.

I want to take care to avoid "crossing the streams". If readers jump between different procedures and do things in the wrong context, then we're harming them. Any modifications need to flow well.

stevepiercy · 2025-09-25T08:03:31Z

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

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


@rohnsha0 does your comment and suggestion still apply? Please reply or resolve this comment. Thank you!

Adds docs for creating custom control panel #1909 revision

579492d

github-project-automation bot added this to Plone Documentation Apr 17, 2025

github-project-automation bot moved this to New in Plone Documentation Apr 17, 2025

stevepiercy removed this from Plone Documentation Apr 17, 2025

stevepiercy added this to Plone Documentation Apr 17, 2025

stevepiercy self-assigned this Apr 17, 2025

stevepiercy requested a review from rohnsha0 April 17, 2025 07:33

github-project-automation bot moved this to New in Plone Documentation Apr 17, 2025

stevepiercy moved this from New to In Progress in Plone Documentation Apr 17, 2025

remove extra space

e7413d4

rohnsha0 approved these changes Apr 17, 2025

View reviewed changes

github-project-automation bot moved this from In Progress to Approved in Plone Documentation Apr 17, 2025

stevepiercy added 2 commits April 17, 2025 14:44

Blackify code, removing u designation since we're on Python 3

c3a4efb

s/Addon/add-on

0034ae6

Enhance documentation for creating control panels with plonecli, in…

3beb688

…cluding usage in non-add-on projects and detailed steps for manual creation.

Add new page for how to create a backend add-on

f5db4a5

Tidy up the Glossary

735b878

stevepiercy added 2 commits April 18, 2025 01:29

plonecli is in the user Python

72508d4

- Improve flow

0b71881

- Add reference targets and labels

rohnsha0 reviewed Apr 18, 2025

View reviewed changes

Enhance documentation for creating control panels by adding notes on …

c89c927

…importing the Generic Profile and clarifying buildout steps.

rohnsha0 mentioned this pull request Apr 18, 2025

Adds docs for creating custom control panel #1909

Open

stevepiercy mentioned this pull request Apr 19, 2025

Ensure references to the repository url are consistent across all templates plone/cookieplone-templates#223

Merged

Refine documentation for creating control panels by clarifying approa…

5d8f44e

…ches, prerequisites, and steps for both automated and manual methods.

stevepiercy added 2 commits September 25, 2025 00:53

- Make introduction more concise and avoid duplication

416fceb

- Add reference labels and targets, instead of copy-paste - Use correct structural markup instead of cosmetic markup - Add synonym for ZMI to glossary

Minor grammar tweak

fee0532

stevepiercy commented Sep 25, 2025

View reviewed changes

Uh oh!

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

Are you sure you want to change the base?

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

Conversation

stevepiercy commented Apr 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stevepiercy commented Apr 17, 2025

Register the control panel view

Register the control panel

Uh oh!

rohnsha0 commented Apr 17, 2025

Uh oh!

rohnsha0 left a comment

Choose a reason for hiding this comment

Uh oh!

stevepiercy commented Apr 17, 2025

Uh oh!

stevepiercy commented Apr 17, 2025

Uh oh!

stevepiercy commented Apr 17, 2025

Uh oh!

stevepiercy commented Apr 17, 2025

Uh oh!

rohnsha0 commented Apr 18, 2025

Uh oh!

rohnsha0 commented Apr 18, 2025

Uh oh!

rohnsha0 commented Apr 18, 2025

Uh oh!

rohnsha0 commented Apr 18, 2025

Uh oh!

stevepiercy commented Apr 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rohnsha0 commented Apr 18, 2025

Uh oh!

stevepiercy commented Apr 18, 2025

Uh oh!

rohnsha0 commented Apr 18, 2025

Uh oh!

stevepiercy commented Apr 18, 2025

Uh oh!

stevepiercy commented Apr 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rohnsha0 commented Apr 18, 2025

Uh oh!

davisagli commented Apr 18, 2025

Uh oh!

MrTango commented Apr 23, 2025

Uh oh!

MrTango commented Apr 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stevepiercy commented Apr 23, 2025

Uh oh!

stevepiercy commented Jun 2, 2025

Uh oh!

stevepiercy commented Sep 22, 2025

Uh oh!

rohnsha0 commented Sep 22, 2025

Uh oh!

rohnsha0 commented Sep 22, 2025

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stevepiercy commented Apr 17, 2025 •

edited

Loading

stevepiercy commented Apr 18, 2025 •

edited

Loading

MrTango commented Apr 23, 2025 •

edited

Loading