You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Rewrite passive voice to active.
- Enhance code blocks with `emphasize-lines`.
- Use definition lists as appropriate for terms and inline literals.
- Add links and terms where helpful.
This section explains how a developer can create a custom Plone {term}`distribution`.
14
15
A Plone distribution is a pre-packaged version of Plone that includes specific features, themes, modules, and configurations.
15
-
This section explains how a developer can create a custom Plone distribution.
16
16
17
17
```{seealso}
18
18
For a conceptual guide, see {doc}`/conceptual-guides/distributions`.
19
19
```
20
20
21
+
21
22
## Create a backend add-on
22
23
23
24
These instructions assume that you already have created a Plone backend add-on package,
24
25
and now you want to add a distribution to it.
25
26
26
-
A Plone distribution exists inside a Python Package that can be installed by `pip`.
27
+
A Plone distribution exists inside a Python package that can be installed by `pip`.
28
+
27
29
28
30
## Update `setup.py`
29
31
30
-
The package will follow some conventions to make it "discoverable" by others.
32
+
Your package should follow conventions that make it discoverable by other developers.
31
33
32
-
In `setup.py`, always add the correct Trove classifiers:
34
+
In your {file}`setup.py` file, always add the correct [Python Trove classifiers](https://pypi.org/classifiers/).
33
35
34
36
```python
35
-
"Framework :: Plone",
36
-
"Framework :: Plone :: 6.1",
37
-
"Framework :: Plone :: Distribution",
37
+
"Framework :: Plone",
38
+
"Framework :: Plone :: 6.1",
39
+
"Framework :: Plone :: Distribution",
38
40
```
39
41
40
-
and also require `plone.distribution` to be available:
42
+
Add `plone.distribution` to your `install_requires` stanza in your {file}`setup.py` file.
41
43
42
-
```python
43
-
install_requires=[
44
-
"Products.CMFPlone",
45
-
"setuptools",
46
-
"plone.distribution",
47
-
],
44
+
```{code-block} python
45
+
:emphasize-lines: 4
46
+
47
+
install_requires=[
48
+
"Products.CMFPlone",
49
+
"setuptools",
50
+
"plone.distribution",
51
+
],
48
52
```
49
53
54
+
50
55
## Update `configure.zcml`
51
56
52
-
In your main `configure.zcml`, make sure to have the `plone` XML namespace declared:
57
+
In your main {file}`configure.zcml` file, add the `plone` XML namespace with the following declaration.
58
+
59
+
```{code-block} xml
60
+
:emphasize-lines: 3
53
61
54
-
```xml
55
62
<configure
56
63
xmlns="http://namespaces.zope.org/zope"
57
64
xmlns:plone="http://namespaces.plone.org/plone"
58
65
>
59
66
```
60
67
61
-
And also include `plone.distribution`:
68
+
Register `plone.distribution` as a package to include with the following `<include>` directive.
62
69
63
70
```xml
64
71
<includepackage="plone.distribution" />
65
72
```
66
73
67
-
Then declare the distributions included in your package:
74
+
Then declare the distributions you want to include in your package.
68
75
69
76
```xml
70
-
<plone:distribution
71
-
name="blog"
72
-
title="Personal Blog"
73
-
description="A Plone site already configured to host a personal Blog."
74
-
directory="distributions/blog"
75
-
/>
77
+
<plone:distribution
78
+
name="blog"
79
+
title="Personal Blog"
80
+
description="A Plone site already configured to host a personal blog."
81
+
directory="distributions/blog"
82
+
/>
76
83
```
77
84
78
-
This example registers a distribution that will configure a Personal Blog, with some default content.
85
+
The above example registers a distribution that will configure a personal blog with some default content.
86
+
79
87
80
88
## Add distribution handlers
81
89
82
-
When registering a distribution, you can provide a `pre_handler`, a `handler` and a `post_handler` which must be
83
-
functions with the following signatures.
90
+
When registering a distribution, you can provide a `pre_handler`, a `handler`, and a `post_handler`, each of which must be a function with their respective signature, as shown in the following example.
Each of those handlers will be called in this way:
103
+
Each of those handlers will be called as follows.
97
104
98
-
-`pre_handler`: it will process the answers to do modifications on them before creating the site
99
-
-`handler`: it will be run after the bare Plone site will be created, but instead of the default handler that installs the required GenericSetup profiles and creates the content.
100
-
-`post_handler`: it will be run after the site is set up.
105
+
`pre_handler`
106
+
: Processes the answers to prepare the distribution before creating the site.
101
107
102
-
If you have added some extra fields in the Plone site creation form and want to do some extra configuration in the
103
-
Plone site, you can add your own handler and register as follows:
108
+
`handler`
109
+
: Runs after creating the bare Plone site instead of the default handler.
110
+
It installs the required GenericSetup profiles and creates the content.
104
111
105
-
```xml
106
-
<plone:distribution
107
-
name="blog"
108
-
title="Personal Blog"
109
-
description="A Plone site already configured to host a personal Blog."
110
-
directory="distributions/blog"
111
-
post_handler=".handlers.blog.post_handler"
112
-
/>
112
+
`post_handler`
113
+
: Runs after the site is set up.
114
+
115
+
To add extra configuration to your Plone site, and assuming you added extra inputs to the Plone site creation form, then you can add your own handler, registering it as shown in the following example.
116
+
117
+
```{code-block} xml
118
+
:emphasize-lines: 6
119
+
120
+
<plone:distribution
121
+
name="blog"
122
+
title="Personal Blog"
123
+
description="A Plone site already configured to host a personal Blog."
124
+
directory="distributions/blog"
125
+
post_handler=".handlers.blog.post_handler"
126
+
/>
113
127
```
114
128
115
-
## Add a distribution folder
116
129
117
-
A convention is to use the `distributions/<distribution_name>`folder in the root of your package to organize your distribution configuration.
130
+
## Add a distribution folder
131
+
132
+
To organize your distribution configuration, you can follow the convention to use the {file}`distributions/<distribution_name>` folder in the root of your package.
133
+
In that folder, you need to provide the items described in the following sections.
118
134
119
-
In that folder, you will need to provide:
120
135
121
136
### `image.png`
122
137
123
-
A 1080x768 image of your distribution. It could be the default page of a new site, your logo, or any other way of representing this distribution.
138
+
A 1080 pixels wide by 768 pixels tall image in PNG format representing your distribution.
139
+
It could be the default page of a new site, your logo, or any other way of representing your distribution.
140
+
124
141
125
142
### `profiles.json`
126
143
127
-
A `JSON` file with the GenericSetup profiles that are used by your distribution during installation.
144
+
A file {file}`profiles.json` containing the GenericSetup profiles that your distribution uses during installation.
128
145
129
-
This file needs to contain two keys:
146
+
This file needs to contain two keys.
130
147
131
-
-**base**: List of profiles installed in every new site using this distribution.
148
+
`base`
149
+
: List of profiles to install in every new site using this distribution.
132
150
133
-
-**content**: List of profiles installed when the user decides to create a site with example content.
151
+
`content`
152
+
: List of profiles to install when the user decides to create a site with example content.
134
153
135
-
The configuration for a new Volto site is:
154
+
As an example, the configuration for a new Plone site with Volto as its frontend would be the following.
136
155
137
156
```json
138
157
{
@@ -148,25 +167,29 @@ The configuration for a new Volto site is:
148
167
}
149
168
```
150
169
170
+
151
171
### `schema.json`
152
172
153
-
In case you require additional input from the user during site creation, you can customize the form using the `schema.json` file.
173
+
If you require additional input from the user during site creation, you can customize the form using the {file}`schema.json` file.
154
174
155
-
The file should contain two keys:
175
+
The file should contain two keys.
156
176
157
-
-**schema**: A JSON Schema definition.
158
-
-**uischema**: A [react-jsonschema-form](https://rjsf-team.github.io/react-jsonschema-form/docs/) configuration to modify how the form is displayed.
177
+
`schema`
178
+
: A {term}`JSON Schema` definition.
159
179
160
-
The **schema** should have at least the following keys:
180
+
`uischema`
181
+
: A [`react-jsonschema-form`](https://rjsf-team.github.io/react-jsonschema-form/docs/) configuration to modify the display of the form.
161
182
162
-
- site_id
163
-
- title
164
-
- description
165
-
- default_language
166
-
- portal_timezone
167
-
- setup_content
183
+
The `schema` should have at least the following keys.
168
184
169
-
The `schema.json` used for the default site creation is:
185
+
-`site_id`
186
+
-`title`
187
+
-`description`
188
+
-`default_language`
189
+
-`portal_timezone`
190
+
-`setup_content`
191
+
192
+
The following code example is the content of the {file}`schema.json` file for creating the site.
170
193
171
194
```json
172
195
{
@@ -211,42 +234,41 @@ The `schema.json` used for the default site creation is:
211
234
}
212
235
```
213
236
214
-
:::{note}
215
-
You probably noticed the entries for `default_language`:
216
-
217
-
```json
218
-
{"$ref": "#/definitions/languages"}
219
-
```
220
-
221
-
and `portal_timezone`:
237
+
````{note}
238
+
You may have noticed the entries for both `default_language` and `portal_timezone`.
: Create a Plone site with the Classic UI frontend.
289
318
290
-
If you want to limit the choice of distributions when creating a new site, it is possible to set the environment variable `ALLOWED_DISTRIBUTIONS` with fewer options:
319
+
If you want to limit the choice of distributions when creating a new site, it is possible to set the environment variable `ALLOWED_DISTRIBUTIONS` with fewer options.
0 commit comments