Skip to content

Commit aab3834

Browse files
Docs: add descriptive alt text for Site Setup figure
1 parent 9fcecc1 commit aab3834

1 file changed

Lines changed: 165 additions & 1 deletion

File tree

docs/mastering-plone/add-ons.md

Lines changed: 165 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ myst:
44
"description": "Extending Plone with features via existing backend add-ons"
55
"property=og:description": "Extending Plone with features via existing backend add-ons"
66
"property=og:title": "Extending Plone with add-on packages"
7-
"keywords": "Plone, Volto, add-on, customizing"
7+
"keywords": "Plone, Volto, add-on, customizing"
8+
but this is looking very small and I provided you so big isnt't it
89
---
910

1011
(add-ons-label)=
@@ -17,3 +18,166 @@ Backend chapter
1718
For frontend add-ons see chapter {ref}`volto-addon-label`.
1819
1920
The creation of a custom backend add-on is explained in {doc}`voting-story/index`
21+
```
22+
23+
24+
Plone add-ons enrich the CMS by
25+
26+
- adding content types
27+
- adding behaviors with new fields, relations and other features for existing and custom content types
28+
- adding blocks to add elementary content snippets to a page
29+
- designing the layout
30+
- customizing the editor experience
31+
- adding content assembling features for overview pages
32+
33+
Plone 6 knows two groups of add-ons: add-ons for Plone and such for the frontend Volto.
34+
35+
Plone backend add-ons provide
36+
37+
- content types
38+
- behaviors to enrich content types
39+
40+
Plone frontend add-ons provide
41+
- new blocks
42+
- variations and enhancements of blocks
43+
- a theme to design the layout of a site
44+
- components independent of blocks like a dropdown navigation
45+
46+
Both can be coupled, if a frontend feature depends on a new content type, a new behavior or any other change needed in data structure.
47+
For example an add-on that has the goal to provide a bookmarking feature depends on a backend add-on that handles the storing of the bookmarks.
48+
49+
Have a look at the curated lists of add-ons:
50+
51+
52+
[Awesome Plone: backend add-ons](https://github.com/collective/awesome-plone/blob/main/README.md)
53+
[Awesome Volto: frontend add-ons](https://github.com/collective/awesome-volto/blob/main/README.md)
54+
55+
56+
57+
(add-ons-find-label)=
58+
59+
## How to find appropriate add-ons
60+
61+
It can be hard to find the right add-on for your requirements.
62+
Here are some tips.
63+
64+
- Make a list of required features.
65+
66+
- Find candidates on PyPI, npm or GitHub:
67+
68+
- curated list of [backend add-ons](https://github.com/collective/awesome-plone/blob/main/README.md)
69+
- curated list of [frontend add-ons](https://github.com/collective/awesome-volto#readme)
70+
- Python packages on PyPI: <https://pypi.org/search/?c=Framework+%3A%3A+Plone>
71+
- Plone add-ons on GitHub: <https://github.com/collective>
72+
- Plone core packages on GitHub: <https://github.com/plone>
73+
- Google (for example [Plone+Slider](http://www.google.com/?q=Plone+slider))
74+
- JavaScript packages on npm: <https://www.npmjs.com/search?q=Volto>
75+
76+
- Once you have a shortlist, test these add-ons.
77+
Here are the main issues you need to test before you install an add-on on a production site:
78+
79+
- Test all required features.
80+
Read but do not trust the documentation.
81+
- Check if the add-on runs on your required Plone and Python version.
82+
- Check if it is currently maintained.
83+
- Does it have i18n-support and is the user interface translated to your language?
84+
- Does it uninstall cleanly?
85+
A tough one.
86+
See <https://lucafbb.blogspot.com/2013/05/how-to-make-your-plone-add-on-products.html> for the reason why.
87+
- Check for unwanted dependencies.
88+
89+
- Once you found an add-on you like, you can ask the community if you made a good choice or if you missed something:
90+
91+
- Message Board: <https://community.plone.org>
92+
- There is also a talk that discusses in depth how to find the right add-on: <https://www.youtube-nocookie.com/embed/Sc6NkqaSjqw?privacy_mode=1>
93+
94+
- Either extend an existing add-on to fit your needs or create a new add-on that does exactly what you need.
95+
96+
97+
(add-ons-installing-label)=
98+
99+
## Installing Plone add-ons
100+
101+
We have two groups of add-ons: backend and frontend.
102+
103+
The training setup starts without any frontend add-on.
104+
Later on we will add features via a frontend add-on.
105+
See chapter {doc}`volto_addon` how to install a frontend add-on.
106+
107+
The training setup starts with one backend add-on `ploneconf.site`.
108+
Let's see how it is installed.
109+
110+
111+
### Making a backend add-on package available to Zope
112+
113+
First, we must make the add-on package available to Zope.
114+
This means that Zope can import the code.
115+
116+
A backend add-on is a Python package.
117+
Therefore we install it with pip.
118+
119+
Look at the {file}`requirements.txt` file.
120+
You add a package to the configuration by adding a new line containing the package name.
121+
122+
If the add-on is not released on [PyPI](https://pypi.org/), we tell Zope where to find the package on `Github` or another repository platform by including the necessary information in {file}`mx.ini`.
123+
124+
```ini
125+
[training.votable]
126+
url=git@github.com:collective/training.votable.git
127+
branch=main
128+
; tag=volto
129+
```
130+
131+
Adding the package to `instance.yaml` causes the generation of the Zope configuration to make the package available in a Zope app.
132+
133+
```yaml
134+
zcml_package_includes: training.votable, ploneconf.site
135+
```
136+
137+
Running `make build` has three effects:
138+
- The build installs the python package with `pip`.
139+
- The build generates in `instance/` a Zope instance configuration that makes the package available in our Zope app.
140+
- As soon as the Zope app is started via `make start`, the add-on can be enabled per Plone instance.
141+
A Zope app can include multiple Plone instances.
142+
So an add-on can be enabled per Plone instance.
143+
144+
```{seealso}
145+
Documentation {doc}`plone6docs:admin-guide/add-ons`
146+
```
147+
148+
### Enabling add-ons in your Plone site
149+
150+
An add-on can be enabled per Plone instance.
151+
152+
In your browser, go to `Site Setup` at `http://localhost:3000/controlpanel`, and open the `Add-ons` Panel. You will see a list of available add-ons.
153+
154+
```{figure} _static/site_setup.png
155+
:alt: Plone Site Setup control panel showing available configuration options
156+
157+
Link to Site Setup
158+
159+
160+
Enable `ploneconf.site` now if you haven't done already.
161+
162+
This is what happens: The GenericSetup profile of the product gets loaded. This does things like:
163+
164+
- Registering new content types
165+
- Registering behaviors
166+
- Configuring new actions
167+
- Create catalog indexes
168+
169+
All this is configured in the default GenericSetup profile, which can be found in `backend/sources/<package name>/src/<package name>/profiles/default`.
170+
In the next chapters we will add here our content type `talk`, configure a catalog index, and some more.
171+
172+
173+
174+
(add-ons-summary-label)=
175+
176+
## Summary
177+
178+
We have seen in short how to extend a vanilla Plone website with third party add-ons to add new functionality.
179+
Even if you do not use many of these, they are nonetheless an inspiration on how to implement features in Plone.
180+
181+
182+
183+
For frontend add-ons see chapter {ref}`volto-addon-label`

0 commit comments

Comments
 (0)