Control Panels

Control panels in Plone allow you to configure the global site setup of a Plone site. The @controlpanels endpoint in plone.restapi allows you to list all existing control panels in a Plone site and to retrieve or edit the settings of a specific control panel.

Most of the settings in the Plone control panels are based on plone.registry (since Plone 5.x). Therefore you can also use the @registry endpoint to retrieve or manipulate site settings. The @controlpanels endpoint just gives developers are more a convenience way of accessing the settings and makes it easier to render control panels on the front-end.

Note

This is currently only implemented for Plone 5.

Listing Control Panels

A list of all existing control panels in the portal can be retrieved by sending a GET request to the @controlpanels endpoint:

http

GET /plone/@controlpanels HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@controlpanels -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@controlpanels Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@controlpanels', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/@controlpanels/date-and-time", 
    "group": "General", 
    "title": "Date and Time"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/language", 
    "group": "General", 
    "title": "Language"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/mail", 
    "group": "General", 
    "title": "Mail"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/navigation", 
    "group": "General", 
    "title": "Navigation"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/site", 
    "group": "General", 
    "title": "Site"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/search", 
    "group": "General", 
    "title": "Search"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/socialmedia", 
    "group": "General", 
    "title": "Social Media"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/editing", 
    "group": "Content", 
    "title": "Editing"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/imaging", 
    "group": "Content", 
    "title": "Image Handling"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/markup", 
    "group": "Content", 
    "title": "Markup"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/security", 
    "group": "Security", 
    "title": "Security"
  }
]

The following fields are returned:

  • @id: hypermedia link to the control panel
  • title: the title of the control panel
  • group: the group where the control panel should show up (e.g. General, Content, Users, Security, Advanced, Add-on Configuration)

Retrieve a single Control Panel

To retrieve a single control panel, send a GET request to the URL of the control panel:

http

GET /plone/@controlpanels/editing HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@controlpanels/editing -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@controlpanels/editing Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@controlpanels/editing', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@controlpanels/editing", 
  "data": {
    "available_editors": [
      "TinyMCE", 
      "None"
    ], 
    "default_editor": {
      "title": "TinyMCE", 
      "token": "TinyMCE"
    }, 
    "enable_link_integrity_checks": true, 
    "ext_editor": false, 
    "lock_on_ttw_edit": true, 
    "subjects_of_navigation_root": false
  }, 
  "group": "Content", 
  "schema": {
    "fieldsets": [
      {
        "fields": [
          "available_editors", 
          "default_editor", 
          "ext_editor", 
          "enable_link_integrity_checks", 
          "lock_on_ttw_edit", 
          "subjects_of_navigation_root"
        ], 
        "id": "default", 
        "title": "Default"
      }
    ], 
    "properties": {
      "available_editors": {
        "additionalItems": true, 
        "default": [
          "TinyMCE", 
          "None"
        ], 
        "description": "Available editors in the portal.", 
        "items": {
          "description": "", 
          "title": "", 
          "type": "string"
        }, 
        "title": "Available editors", 
        "type": "array", 
        "uniqueItems": false
      }, 
      "default_editor": {
        "default": "TinyMCE", 
        "description": "Select the default wysiwyg editor. Users will be able to choose their own or select to use the site default.", 
        "title": "Default editor", 
        "type": "string", 
        "vocabulary": {
          "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.AvailableEditors"
        }
      }, 
      "enable_link_integrity_checks": {
        "default": true, 
        "description": "Determines if the users should get warnings when they delete or move content that is linked from inside the site.", 
        "title": "Enable link integrity checks", 
        "type": "boolean"
      }, 
      "ext_editor": {
        "default": false, 
        "description": "Determines if the external editor feature is enabled. This feature requires a special client-side application installed. The users also have to enable this in their preferences.", 
        "title": "Enable External Editor feature", 
        "type": "boolean"
      }, 
      "lock_on_ttw_edit": {
        "default": true, 
        "description": "Disabling locking here will only affect users editing content through the Plone web UI.  Content edited via WebDAV clients will still be subject to locking.", 
        "title": "Enable locking for through-the-web edits", 
        "type": "boolean"
      }, 
      "subjects_of_navigation_root": {
        "default": false, 
        "description": "Limit tags aka keywords vocabulary used for Tags field and in searches to the terms used inside the subtree of the current navigation root. This can be used together with Plone's multilingual extension plone.app.multilingual to only offer keywords of the current selected language. Other addons may utilize this feature for its specific purposes.", 
        "title": "Limit tags/keywords to the current navigation root", 
        "type": "boolean"
      }
    }, 
    "required": [
      "available_editors", 
      "default_editor"
    ], 
    "type": "object"
  }, 
  "title": "Editing"
}

The following fields are returned:

  • @id: hypermedia link to the control panel
  • title: title of the control panel
  • group: group name of the control panel
  • schema: JSON Schema of the control panel
  • data: current values of the control panel

Updating a Control Panel with PATCH

To update the settings on a control panel send a PATCH request to control panel resource:

http

PATCH /plone/@controlpanels/editing HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
  "default_editor": "CKeditor",
  "ext_editor": true
}

curl

curl -i -X PATCH http://nohost/plone/@controlpanels/editing -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"default_editor": "CKeditor", "ext_editor": true}' --user admin:secret

httpie

echo '{
  "default_editor": "CKeditor",
  "ext_editor": true
}' | http PATCH http://nohost/plone/@controlpanels/editing Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.patch('http://nohost/plone/@controlpanels/editing', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'default_editor': 'CKeditor',
    'ext_editor': True,
}, auth=('admin', 'secret'))

A successful response to a PATCH request will be indicated by a 204 No Content response:

HTTP/1.1 204 No Content