Adds docs for creating custom control panel #1909 revision

[stevepiercy]

@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 📚:

• https://plone6--1939.org.readthedocs.build/developer-guide/create-backend-add-on.html
• https://plone6--1939.org.readthedocs.build/developer-guide/create-control-panel.html

[stevepiercy]

@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]

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]

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

[stevepiercy]

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]

@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]

@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]

@stevepiercy it works everytime!

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

[rohnsha0]

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]

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]

@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]

@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]

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

[stevepiercy]

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]

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]

@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.

[stevepiercy]

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]

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

[rohnsha0]

@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]

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]

Some suggestions:

1. add an upgrade step via plonecli to update the database with the new settings, it's one command ;)
2. 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]

@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]

@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.