Plone Distributions

Package supporting the (easy) implementation of a Plone distribution.

What is a Plone distribution

A Plone distribution is a pre-packaged version of Plone that includes specific features, themes, modules, and configurations. It is a convenient way to get a specific type of website up and running quickly, as the distribution includes everything needed to run that type of site.

Examples of Plone distributions include:

• SENAITE
• Quaive
• Portal Modelo
• Portal Padrão

Similar Concept in Other CMS

• Drupal: Drupal has distributions for blogs, e-commerce sites, and intranet portals.

• WordPress: WordPress has a similar concept in the form of "WordPress Multisite," which allows users to run multiple websites from a single installation of WordPress.

• Joomla: Joomla has a similar concept in the form of "Joomla Templates," which are pre-designed templates for Joomla websites.

• TYPO3: TYPO3 has a similar concept in the form of "TYPO3 Distributions," which are pre-configured installations of TYPO3 for specific types of websites.

plone.distribution versions

Creating a new distribution

A Plone distribution is a Python Package that can be installed by pip.

setup.py

The package will follow some conventions, to make it "discoverable" by others.

In setup.py, always add the correct Trove classifiers:

        "Framework :: Plone",
        "Framework :: Plone :: 6.0",
        "Framework :: Plone :: Distribution",

and also require plone.distribution to be available:

    install_requires=[
        "Plone",
        "setuptools",
        "plone.distribution",
    ],

configure.zcml

In your main configure.zcml, make sure to have the plone XML namespace declared:

<configure
    xmlns="http://namespaces.zope.org/zope"
    xmlns:plone="http://namespaces.plone.org/plone"
    >

And also include plone.distribution:

<include package="plone.distribution" />

Then declare the distributions included in your package:

  <plone:distribution
      name="blog"
      title="Personal Blog"
      description="A Plone site already configured to host a personal Blog."
      directory="distributions/blog"
      />

The registered distribution will configure a Personal Blog, with some default content.

distribution handlers

When registering a distribution, you can provide a pre_handler, a handler and a post_handler which must be functions with the following signatures.

def pre_handler(answers: dict) -> dict:
    return answers

def handler(distribution: Distribution, site, answers: dict):
    return site

def post_handler(distribution: Distribution, site, answers: dict):
    return site

Each of those handlers will be called in this way:

• pre_handler: it will process the answers to do modifications on them before creating the site
• 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.
• post_handler: it will be run after the site is set up.

If you have added some extra fields in the Plone site creation form and want to do some extra configuration in the Plone site, you can add your own handler and register as follows:

  <plone:distribution
      name="blog"
      title="Personal Blog"
      description="A Plone site already configured to host a personal Blog."
      directory="distributions/blog"
      post_handler=".handlers.blog.post_handler"
      />

distribution folder

A convention is to use the distributions/<distribution_name>folder in the root of your package to organize your distribution configuration.

In that folder, you will need to provide:

image.png

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.

profiles.json

A JSON file with the GenericSetup profiles that are used by your distribution during installation.

This file needs to contain two keys:

• base: List of profiles installed in every new site using this distribution.

• content: List of profiles installed when the user decides to create a site with example content.

The configuration for a new Volto site is:

{
  "base": [
    "plone.app.contenttypes:default",
    "plone.app.caching:default",
    "plonetheme.barceloneta:default",
    "plone.volto:default"
  ],
  "content": [
    "plone.volto:default-homepage"
  ]
}

How to add an add-on

If you want to add a Plone backend add-on to your Plone distribution, then you must perform the following steps.

Add your add-on, such as collective.person, to your setup.py:

    install_requires=[
        "setuptools",
        "Plone",
        "plone.distribution>=1.0.0b2",
        "plone.api",
        "collective.person",
    ],

Add it to your dependencies.zcml:

  <!-- List all packages you depend here -->
  <include package="plone.volto" />
  <include package="plone.restapi" />
  <include package="collective.person" />
  <include package="plone.distribution" />

</configure>

Add it to your profiles.json:

  "base": [
    "plone.app.contenttypes:default",
    "plone.app.caching:default",
    "plone.restapi:default",
    "plone.volto:default",
    "collective.person:default",
    "plonetheme.barceloneta:default"
  ],

schema.json

In case you require additional input from the user during site creation, you can customize the form using the schema.json file.

The file should contain two keys:

• schema: A JSON Schema definition.
• uischema: A react-jsonschema-form configuration to modify how the form is displayed.

The schema should have at least the following keys:

• site_id
• title
• description
• default_language
• portal_timezone
• setup_content

The schema.json used for the default site creation is:

{
  "schema": {
    "title": "Create a Plone site",
    "description": "Adds a new Plone content management system site to the underlying application server.",
    "type": "object",
    "required": [
      "site_id",
      "title"
    ],
    "properties": {
      "site_id": {
        "type": "string",
        "title": "Path Identifier",
        "default": "Plone",
        "description": "The ID of the site. No special characters or spaces are allowed. This ends up as part of the URL unless hidden by an upstream web server."
      },
      "title": {
        "type": "string",
        "title": "Title",
        "default": "Site",
        "description": "A short title for the site. This will be shown as part of the title of the browser window on each page."
      },
      "description": {
        "type": "string",
        "title": "Site Description",
        "default": "A Plone Site"
      },
      "default_language": {"$ref": "#/definitions/languages"},
      "portal_timezone": {"$ref": "#/definitions/timezones"},
      "setup_content": {
        "type": "boolean",
        "title": "Create Content",
        "description": "Should example content be added during site creation?",
        "default": false
      }
    }
  },
  "uischema": {
  }
}

Important You probably noticed the entries for default_language:

{"$ref": "#/definitions/languages"}

and portal_timezone:

{"$ref": "#/definitions/timezones"}

Both definitions are added in runtime by plone.distribution to provide a list of languages and timezones available on the installation.

content folder

Folder containing JSON data representing this distribution's content.

To export content from a site into this folder, use the bin/export-distribution script.

bin/export-distribution path/to/zope.conf Plone

In the example above, "Plone" is the ID of the Plone site to export.

Advanced Usage

Hiding Distributions

By default, plone.distribution ships with two ready-to-use distributions:

• default: Plone Site (Volto frontend)
• classic: Plone Site (Classic UI)

If you want to limit your users option to select a distribution, it is possible to set the environment variable ALLOWED_DISTRIBUTIONS with fewer options:

ALLOWED_DISTRIBUTIONS=default

This project is supported by

License

The project is licensed under the GPLv2.

Changelog

3.0.0a1 (2024-10-31)

Breaking changes:

• Move internal classic distribution to plone.classicui [@mauritsvanrees][@ericof] #79

New features:

• Move internal default distribution to plone.volto [@mauritsvanrees][@ericof] #80

Internal:

• Clarify RestTraverser code. [maurits]

2.0.0b1 (2024-05-17)

New features:

• Redesign the site creation page [@danalvrz] #63

2.0.0a1 (2024-05-16)

Breaking changes:

• plone.distribution is now based on plone.exportimport instead of collective.exportimport.

  There are some backwards-incompatible changes in the export format. To convert an existing distribution to the new format, use the following steps:

  1. Create a site from the distribution using plone.distribution 1.0.x
  2. Install plone.distribution 2.0.x
  3. Delete the distribution's contents/items folder.
  4. Export the distribution in the new format using the bin/export-distribution script.

  @davisagli, @ericof #61

New features:

• Default distribution: Allow users to upload a logo during site creation [@ericof] #66
• Classic distribution: Allow users to upload a logo during site creation [@ericof] #67
• Remove dependency on Plone package, add dependency on Products.CMFPlone [@ericof] #70

Bug fixes:

• Get the name of the existing distribution from the report, not the answers [@ericof] #60
• Fix issue with payload for new site creation breaking with certain plone.rest versions [@ericof] #71
• Read profile.json by the pathlib.Path.read_text method to avoid the unclosed file exception [@folix-01] #75

Internal:

• Update plone/meta configuration [@ericof] #73
• Log traceback when creating a site fails [@pbauer] #82
• Bump plone.exportimport to 1.0.0a5 [@ericof] #83

1.0.0b4 (2024-04-03)

Bug fixes:

• Fix exporting files. [pbauer] #58

1.0.0b3 (2024-03-08)

Bug fixes:

• Fix importing blocks on the site-root. [pbauer] #56

Internal:

• Update configuration files. [plone devs] 6e36bcc4

1.0.0b2 (2023-10-11)

New features:

• Remove old blobs before exporting content [@ericof] #34
• Support to new export/import format with one content item per json file [@ericof] #47

1.0.0b1 (2023-07-10)

New features:

• Validate answers payload against jsonschema [@ericof] #38
• Allow distribution to pre process answers before site creation [@ericof] #39
• Override @system from plone.restapi to display distribution information [@ericof] #45

1.0.0a9 (2023-06-27)

Bug fixes:

• Allow setting default_language "default" value [@ericof] #36

1.0.0a8 (2023-06-25)

New features:

• Bump @rjsf/core to version 5.8.2 [@ericof] #35

1.0.0a7 (2023-06-24)

Bug fixes:

• Fix content export to json [@ericof] #33

1.0.0a6 (2023-06-23)

New features:

• Improve support for testing distributions [@ericof] #24
• Allow export only for distributions still in development [@ericof] #28
• Create a report for Plone sites created from a distribution [@ericof] #30
• Clean up exported content to remove references to portal.absolute_url() [@ericof] #32

Bug fixes:

• Content language should be allowed in portal configuration [@ericof] #23

Internal:

• Update configuration files. [plone devs] 047ec50d, 55bda5c9, d7e9e748

1.0.0a5 (2023-05-18)

Bug fixes:

• Import did not import any steps except content and portal. [pbauer] #22

1.0.0a4 (2023-05-18)

New features:

• Increase test coverage. [ericof] #12
• Implement JSON import of content [pbauer] #13
• Use mxdev. [ericof] #18
• Implement default content for default and classic distributions as JSON. [ericof] #20

1.0.0a3 (2023-02-08)

Bug fixes:

• Fix Basic Authentication for Chrome [@ericof] #10

1.0.0a2 (2023-02-08)

New features:

• Change overview page favicon to use Plone logo [@ericof] #7
• Set content creation on default and classic distributions to be default. [@ericof] #9

Bug fixes:

• Use ajv8 with Ajv2019 class validator to fix function nested too deeply on Firefox [@ericof] #4
• Handle authentication when /acl_users does not support cookie extraction [@ericof] #6

1.0.0a1 (2023-02-08)

New features:

• Initial implementation of plone.distribution [@ericof] #1

1.0.0 (Unreleased)