plone.distribution 1.0.0b2

Plone distribution support

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.

Creating a new Distribution

First of all, 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 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"
  ]
}

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 exported using the @@dist_export_all browser view of this package.

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

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)