Control panels

Control panels allow you to configure the global site setup. The @controlpanels endpoint allows you to list all existing control panels.

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:

GET /@controlpanels HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Response:

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

[
  {
    "@id": "http://localhost:8000/@controlpanels/language",
    "group": "General",
    "title": "Language"
  },
  {
    "@id": "http://localhost:8000/@controlpanels/mail",
    "group": "General",
    "title": "Mail"
  },
  {
    "@id": "http://localhost:8000/@controlpanels/navigation",
    "group": "General",
    "title": "Navigation"
  },
  {
    "@id": "http://localhost:8000/@controlpanels/site",
    "group": "General",
    "title": "Site"
  }
]

The following fields are returned:

@id: hypermedia link to the control panel
title: the title of the control panel
group: the group in which the control panel should appear, for example, General, Content, Users, Security, Advanced, or 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:

GET /@controlpanels/mail HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Response:

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

{
  "@id": "http://localhost:8000/@controlpanels/mail",
  "group": "General",
  "title": "Mail",
  "data": {
    "host": "localhost",
    "pass": "",
    "port": 25,
    "user": "",
    "debug": true,
    "secure": true,
    "email_from_name": "Webmaster",
    "email_from_address": "webmaster@nickcms.org"
  },
  "schema": {
    "required": ["host", "port", "email_from_name", "email_from_address"],
    "fieldsets": [
      {
        "id": "default",
        "title": "Default",
        "fields": [
          "host",
          "port",
          "secure",
          "user",
          "pass",
          "email_from_name",
          "email_from_address",
          "debug"
        ],
        "behavior": "plone"
      }
    ],
    "properties": {
      "host": {
        "type": "string",
        "title": "SMTP server",
        "default": "localhost",
        "description": "The address of your local SMTP (outgoing e-mail) server. Usually 'localhost', unless you use an external server to send e-mail."
      },
      "pass": {
        "type": "string",
        "title": "ESMTP password",
        "widget": "password",
        "description": "The password for the ESMTP user account."
      },
      "port": {
        "type": "integer",
        "title": "SMTP port",
        "default": 25,
        "description": "The port of your local SMTP (outgoing e-mail) server. Usually '25'."
      },
      "user": {
        "type": "string",
        "title": "ESMTP username",
        "description": "Username for authentication to your e-mail server. Not required unless you are using ESMTP."
      },
      "debug": {
        "type": "boolean",
        "title": "Debug",
        "description": "If enabled the mail is send to a test server."
      },
      "secure": {
        "type": "boolean",
        "title": "Secure",
        "description": "If enabled the mail is send using a secure connection."
      },
      "email_from_name": {
        "type": "string",
        "title": "Site 'From' name",
        "description": "Plone generates e-mail using this name as the e-mail sender."
      },
      "email_from_address": {
        "type": "string",
        "title": "Site 'From' address",
        "description": "Plone generates e-mail using this address as the e-mail return address. It is also used as the destination address for the site-wide contact form and the 'Send test e-mail' feature."
      }
    }
  }
}

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

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

PATCH /@controlpanels/mail HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "host": "mail.someserver.com",
  "port": 25
}

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

HTTP/1.1 204 No Content