How to Create a Custom Control Panel for a Plone Add-On

When developing custom add-ons for your website, the control panel is one of the essential factors to consider. The control panel is the user interface site administrators use to manage add-on settings and configurations.

It is essential to create a control panel to make your add-on easy to use and flexible. In this blog, we’ll explore how to add a custom control panel to your add-on that gives site admins more power and encourages flexibility.

In this blog post, we’ll go over the steps involved in creating one for your Plone add-on in a way that’s easy to understand.

Step 1: Define a schema for the control panel

A schema defines the structure and properties of an object. It is used to describe the fields and their data types that an object should have. Schemas are typically defined using the zope.schema package, which is a part of the Zope Component Architecture (ZCA) that Plone is built upon.

To define a schema for an addon control panel, you need to create an interface using zope.interface and define fields using zope.schema. The interface will represent the contract for your control panel, specifying which fields it should have and their respective types.

browser/settings.py

from zope import schema
from zope.interface import Interface

class IExampleAddonControlPanel(Interface):
   """Define settings for IExampleAddonControlPanel"""

   textline_field = schema.TextLine(
       title='Textline field',
       description='A simple input field',
       required=False,
   )

Step 2: Register the interface to the registry

The Plone Registry XML configuration file serves as a central repository for storing and managing settings related to specific add-ons or components within the Plone CMS.
So it is necessary to add the interface to the registry.

registry/main.xml

<?xml version="1.0"?>
<registry
   xmlns:i18n="http://xml.zope.org/namespaces/i18n"
   i18n:domain="example.addon">
 <records interface ="example.addon.browser.settings.IExampleAddonControlPanel"
 prefix="example-setting"/>
</registry>

Step 3: Reinstall the addon and inspect the registry for the records

After registering the interface, you need to re-install the addon in order to see it in the configuration registry and search for the record by the schema’s prefix.

The configuration registry can be found in Site Setup -> Configuration Registry, or you can follow the path of this Url: http://localhost:8080/Plone/portal_registry

Step 4: Define a Plone control panel form for an example addon, with a corresponding view using the Z3CForm library.

from plone.app.registry.browser.controlpanel import ControlPanelFormWrapper
from plone.app.registry.browser.controlpanel import RegistryEditForm
from plone.z3cform import layout

class ExampleAddonControlPanelForm(RegistryEditForm):
   """Define settings for IExampleAddonControlPanel"""
   schema = IExampleAddonControlPanel
   schema_prefix = 'example-setting'
   label = 'Example Addon Control Panel'

ExampleSettingControlPanelView = layout.wrap_form(
   ExampleAddonControlPanelForm, ControlPanelFormWrapper
)

Step 5: Add to configure the form to configure.zcml

Add that form view class to the configure.zcml, then the view can be accessed from this URL: http://localhost:8080/Plone/@@example-settings

browser/configure.zcml

But this can be only accessed by the “/@@example-settings”.

Step 6: Define a Configlet for the form view

To display the icon for the form view in the control panel, we have to register a configlet in the control.

profiles/default/controlpanel.xml

<?xml version="1.0"?>
<object name="portal_controlpanel">
 <configlet
     title="Example Settings"
     action_id="example-settings"
     appId="example-setting"
     category="Products"
     condition_expr=""
     icon_expr=""
     url_expr="string:${portal_url}/@@example-settings"
     visible="True">
   <permission>Manage portal</permission>
 </configlet>
</object>

● title: Specifies the title of the configuration option, which is set to “Example Settings” in this case.
● action_id: Defines an action ID for the configuration option, which can be used to reference it in code or templates.
● appId: Specifies an application ID for the configuration option.
● category: Sets the category under which the configuration option will be displayed in the control panel (in this case, “Products”).
● condition_expr: Allows you to specify an expression that determines whether the configuration option should be displayed based on certain conditions.
● icon_expr: Defines an expression that can be used to dynamically set the icon for the configuration option.
● url_expr: Sets the URL expression for the configuration option, which determines the URL where the settings view will be accessible. In this case, it’s set to string:${portal_url}/@@example-settings, indicating that the view will be available at example.com/@@example-settings.
● visible: Specifies whether the configuration option should be visible (visible=”True”).
● The <permission> element is used to define the permission required to access the configuration option. In this case, the “Manage portal” permission is required.

In this blog post, we explored how to create a custom control panel for a Plone add-on. The control panel is an important component for managing add-on settings and configurations. By following the steps outlined in the blog, you can define a schema for the control panel, register it to the registry, create a Plone control panel form, configure the form, and define a configlet for the form view. These steps will help you create a user-friendly interface for site administrators to manage your add-on effectively.