Skip to content

Build upon #2702 #2073

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
davisagli merged 6 commits into from
Mar 26, 2026
Merged

Build upon #2702 #2073

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
31ac9dc
Extension of PR #2072
stevepiercy Mar 26, 2026
f8b392b
Added guilabel role, and reversed the order of instructions in increa…
stevepiercy Mar 26, 2026
a1ac3f9
The instructions for installation from PyPI for both uv and pip were …
stevepiercy Mar 26, 2026
72c0b9c
Move tip outside DRY, and combine both the original and new options. …
stevepiercy Mar 26, 2026
358fefc
- Move tip outside DRY, and combine both the original and new options…
stevepiercy Mar 26, 2026
bde905b
- Repeat for source installation the same DRY, split of configuration…
stevepiercy Mar 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
190 changes: 94 additions & 96 deletions docs/admin-guide/add-ons.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,92 +18,48 @@ The Volto frontend has its own system of add-ons using Node.js packages.
See {doc}`/volto/development/add-ons/index`.
```

## Install an add-on from PyPI

For instructions to install an add-on that is released on {term}`PyPI`, select the tab below according to your Python package manager.

```{tip}
Select the tab for uv if you have a project that was created using Cookieplone, and you have `managed = true` set in the `[tool.uv]` section of the file {file}`backend/pyproject.toml`.
Select the tab for pip if you have a project that was created using Cookieplone that does not have this setting.
```

`````{tab-set}

````{tab-item} uv

Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`.
This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/).
(install-an-add-on-from-pypi-label)=

```{code-block} toml
:emphasize-lines: 6
dependencies = [
"Products.CMFPlone==6.1.1",
"plone.api",
"plone.classicui",
"plone.app.caching",
"collective.easyform==4.4.0",
]
```
## Install an add-on from PyPI

```{tip}
Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future.
```
This section describes how to install an add-on that is released on {term}`PyPI`.

Also add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` to make sure its configuration will be loaded.

```yaml
default_context:
zcml_package_includes: project_title, collective.easyform
```
(configure-add-on-installation-pypi-label)=

Stop the backend with {kbd}`ctrl-c`.
### Configure add-on installation

To actually download and install the new add-on, run the following command.
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.

```shell
make backend-build
```

````

````{tab-item} pip
`````{tab-set}
````{tab-item} Cookieplone
:sync: cookieplone

Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`.
This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/).

```{code-block} toml
:emphasize-lines: 6
dependencies = [
"Products.CMFPlone==6.1.1",
"Products.CMFPlone==6.1.4",
"plone.api",
"plone.classicui",
"plone.app.caching",
"collective.easyform==4.4.0",
"collective.easyform==4.5.1",
]
```

```{tip}
Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future.
```

Also add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` to make sure its configuration will be loaded.
To configure the add-on to load, in the file {file}`backend/instance.yaml`, under the key `default_context`, for the key `zcml_package_includes`, set its value to the add-on's name.

```yaml
default_context:
zcml_package_includes: project_title, collective.easyform
```

Stop the backend with {kbd}`ctrl-c`.

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

```shell
make backend-build
```

````

````{tab-item} Buildout
:sync: buildout

Update the file {file}`buildout.cfg`.
This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
Expand All @@ -125,24 +81,46 @@ eggs =
collective.easyform

[versions]
collective.easyform = 4.2.1
collective.easyform = 4.5.1
```
````
`````

```{tip}
Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future.
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-pypi-label)=

### Install the add-on

Stop the backend with {kbd}`ctrl-c`.

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

`````{tab-set}
````{tab-item} Cookieplone
:sync: cookieplone

```shell
bin/buildout -N
make backend-build
```

````

````{tab-item} Buildout
:sync: buildout

```shell
bin/buildout -N
```
````
`````

Now restart the backend.
Next, restart the backend.

```{seealso}
{doc}`run-plone`
Expand All @@ -159,18 +137,26 @@ At the bottom of the page, you should see the heading {guilabel}`Add-on Configur

## Install an add-on from source

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


(configure-add-on-installation-source-label)=

### Configure add-on installation

For instructions to install an add-on that is released on {term}`PyPI`, select the tab below according to your Python package manager.
First, configure your project according to the instructions in the tabbed interface below.
Select the tab according to your Python package manager.

```{tip}
Select the tab for uv if you have a project that was created using Cookieplone, and you have `managed = true` set in the `[tool.uv]` section of the file {file}`backend/pyproject.toml`.
Select the tab for pip if you have a project that was created using Cookieplone that does not have this setting.
For projects created with Cookieplone, select either the tab labeled:

- {guilabel}`uv` if the file {file}`backend/pyproject.toml`, under the table `[tool.uv]` has the setting of `managed = true`
- {guilabel}`pip` if your project doesn't have this setting
```

`````{tab-set}

````{tab-item} uv
:sync: uv

Clone the repository into a local directory.
This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
Expand All @@ -186,43 +172,32 @@ cd backend
uv add --editable ../collective.easyform
```

```{note}
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.
```

Next add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` so that its configuration will load.
To configure the add-on to load, in the file {file}`backend/instance.yaml`, under the key `default_context`, for the key `zcml_package_includes`, set its value to the add-on's name.

```yaml
default_context:
zcml_package_includes: project_title, collective.easyform
```

Stop the backend with {kbd}`ctrl-c`.
````

````{tab-item} pip
:sync: pip

Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`.
This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/).

```{code-block} toml
:emphasize-lines: 6
dependencies = [
"Products.CMFPlone==6.1.1",
"Products.CMFPlone==6.1.4",
"plone.api",
"plone.classicui",
"plone.app.caching",
"collective.easyform",
]
```

```{note}
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.
```

Next add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` so that its configuration will load.
To configure the add-on to load, in the file {file}`backend/instance.yaml`, under the key `default_context`, for the key `zcml_package_includes`, set its value to the add-on's name.

```yaml
default_context:
Expand All @@ -242,18 +217,10 @@ extras=test
The {file}`mx.ini` file configures a tool called {term}`mxdev`.
For an explanation of why Plone uses `mxdev`, see {ref}`manage-packages-mxdev-label`.
```

Stop the backend with {kbd}`ctrl-c`.

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

```shell
make backend-build
```

````

````{tab-item} Buildout
:sync: buildout

Update the file {file}`buildout.cfg`.
This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
Expand All @@ -280,22 +247,53 @@ eggs =
[sources]
collective.easyform = git https://github.com/collective/collective.easyform.git
```
````
`````

```{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-source-label)=

### Install the add-on

Stop the backend with {kbd}`ctrl-c`.

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

`````{tab-set}
````{tab-item} uv
:sync: uv

```shell
bin/buildout
make backend-build
```
````

````{tab-item} pip
:sync: pip

```shell
make backend-build
```
````

````{tab-item} Buildout
:sync: buildout

```shell
bin/buildout
```
```{seealso}
This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension.
```

````

`````

Now restart the backend.
Next, restart the backend.

```{seealso}
{doc}`run-plone`
Expand Down
Loading