Install Plone add-ons

Install Plone add-ons#

This chapter explains how to install add-ons as Python packages to extend the functionality of the Plone backend or Classic UI.

Note

The Volto frontend has its own system of add-ons using Node.js packages. See Develop Volto add-ons.

Install an add-on from PyPI#

This section describes how to install an add-on that is released on PyPI.

Configure add-on installation#

First, configure your project according to the instructions in the tabbed interface below. Select the tab according to the method you used to create your project.

Add the name of your add-on in the file backend/pyproject.toml in the section dependencies. This example adds collective.easyform.

dependencies = [
    "Products.CMFPlone==6.1.4",
    "plone.api",
    "plone.classicui",
    "plone.app.caching",
    "collective.easyform==4.5.1",
]

To configure the add-on to load, in the file backend/instance.yaml, under the key default_context, for the key zcml_package_includes, set its value to the add-on's name.

default_context:
    zcml_package_includes: project_title, collective.easyform

Update the file buildout.cfg. This example uses collective.easyform.

[buildout]
extends =
    https://dist.plone.org/release/6-latest/versions.cfg

parts =
    instance

[instance]
recipe = plone.recipe.zope2instance
user = admin:admin
http-address = 8080
eggs =
    Plone
    collective.easyform

[versions]
collective.easyform = 4.5.1

Tip

You can control which version of an add-on to install through "version pinning."

  • Specify the add-on version to avoid its unintentional upgrade.

  • Leave it off to always install the latest version.

Install the add-on#

If the backend is running, stop it with ctrl-c.

To actually download and install the new add-on, run the following command.

make backend-build

bin/buildout -N

Next, restart the backend.

See also

Run Plone

In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form.

Then click the Install button next to your add-on to complete installation of the add-on.

Some add-ons have configuration options. To configure such add-ons, return to the Site Setup control panel. At the bottom of the page, you should see the heading Add-on Configuration, and a control panel to configure the add-on that you just installed.

Install an add-on from source#

This section describes how to install an unreleased add-on from a source control system, such as GitHub.

Configure add-on installation#

First, configure your project according to the instructions in the tabbed interface below. Select the tab according to your Python package manager.

Tip

For projects created with Cookieplone, select the tab labeled:

  • pip if your project has the file backend/mx.ini

  • uv if your project doesn't have this file

Clone the repository into a local directory. This example uses collective.easyform.

git clone git@github.com:collective/collective.easyform.git

Add the local directory to your uv project as an editable package.

cd backend
uv add --editable ../collective.easyform

To configure the add-on to load, in the file backend/instance.yaml, under the key default_context, for the key zcml_package_includes, set its value to the add-on's name.

default_context:
    zcml_package_includes: project_title, collective.easyform

Add the name of your add-on in the file backend/pyproject.toml in the section dependencies. This example adds collective.easyform.

dependencies = [
    "Products.CMFPlone==6.1.4",
    "plone.api",
    "plone.classicui",
    "plone.app.caching",
    "collective.easyform",
]

To configure the add-on to load, in the file backend/instance.yaml, under the key default_context, for the key zcml_package_includes, set its value to the add-on's name.

default_context:
    zcml_package_includes: project_title, collective.easyform

Finally, add the package's source to the file mx.ini.

[collective.easyform]
url=git@github.com:collective/collective.easyform.git
branch=dev-branch-name
extras=test

See also

The mx.ini file configures a tool called mxdev. For an explanation of why Plone uses mxdev, see mxdev.

Update the file buildout.cfg. This example uses collective.easyform.

[buildout]
extends =
    https://dist.plone.org/release/6-latest/versions.cfg
extensions = mr.developer
auto-checkout =
    collective.easyform

parts =
    instance

[instance]
recipe = plone.recipe.zope2instance
user = admin:admin
http-address = 8080
eggs =
    Plone
    collective.easyform

[sources]
collective.easyform = git https://github.com/collective/collective.easyform.git

See also

This approach uses the mr.developer Buildout extension.

Tip

When installing an add-on from source, it's best not to pin a version. This way you always get the version that's currently available in the source control system.

Install the add-on#

If the backend is running, stop it with ctrl-c.

To actually download and install the package, run the following command.

make backend-build

make backend-build

bin/buildout -N

Next, restart the backend.

See also

Run Plone

In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form.

Then click the Install button next to your add-on to complete installation of the add-on.

Some add-ons have configuration options. To configure such add-ons, return to the Site Setup control panel. At the bottom of the page, you should see the heading Add-on Configuration, and a control panel to configure the add-on that you just installed.

Contents