GenericSetup profiles for plone.app.theming
collective.themesitesetup can automatically import one embedded set of generic setup steps during theme activation and another one (so called uninstall profile) when theme is deactivated. Yet, also additionals ets can be embedded and imported manually.
See it activating theme site setup at: https://youtu.be/3vkrc7JFUU0
Simply include this package into your Plone site buildout by following the official instructions. This add-on doesn’t require other activation, but, of course, requires plone.app.theming to be activated.
This plugin is enabled for any theme by simply adding the following line into theme’s manifest.cfg:
By default, this looks for the setup steps to be imported during activation from theme’s install-subdirectory and the steps to be imported during deactivation from theme’s uninstall-subdirectory. If such directory does not exist, this plugin simply does not import any steps.
The default lookup directories can be customized by overriding the defaults with custom values in theme’s manifest.cfg:
[theme:genericsetup] install = my-install uninstall = my-uninstall
This plugin can also be disabled at any time simply by adding the line disabled = true into plugin’s configuration in theme’s manifest.cfg:
[theme:genericsetup] disabled = true
A usual use for this plugin is to ship a theme with pre-configured Dexterity content types. Unfortunately, describing a Dexterity XML schema in type description inline in type description XML is inconvenient (because the schema must be escaped) and Dexterity only supports reading separate XML model files from filesystem and filesystem Python packages. Fortunately, this plugin allows populating existing Dexterity content types (and also the ones installed with this plugin) with a matching model XML from the theme.
By default, the plugin loads model files from models-subdirectory of the them. Models must have matching filename with the content type id (with .xml extension). The default import directory can be changed with:
[theme:genericsetup] models = my_models
The plugin does not overwrite existing models by default (unless they seem empty), but this can be changed (e.g. for development purposes) with:
[theme:genericsetup] models-overwrite = true
This plugin can also be used to register (and unregister) i18n message catalogs directly from the theme. By default, the plugin looks for message catalogs from locales-subdirectory of the theme, expecting the usual message catalog directory structure:
In the above example, two message catalogs, one for language en for domain foo and another for language en for domain bar are registered.
The default locales directory name can be changed with:
[theme:genericsetup] locales = my_locales
The registered message catalogs are unregistered when the theme is deactivated.
The registered message catalogs use the persistent message catalog classes from zope.app.i18n. The existence of these catalogs can be confirmed from ZMI Components-tab from Plone site root by looking for translationdomain utilities with themesitesetup in their names.
Mosaic layouts (and other resources)
This plugin can also be used to populate also other persistent resource directories than theme directories. For example, with this plugin, your theme could contain site and content layouts for Plone Mosaic. Layouts are copied from theme into their own resource directory namespaces when theme is activated (or updated). One layouts are copied, they are not removed, unless this plugin is configured to purge those directories.
For example, theme containing single site layout and content layout, could contain the following file structure:
./resources/sitelayout/manifest.cfg ./resources/sitelayout/layout.html ./resources/contentlayout/manifest.cfg ./resources/contentlayout/layout.html
The default resources directory name can be from resources to e.g. designs with:
[theme:genericsetup] resources = design
By default, this plugin never overwrites existing resources unless its configuration option resources-overwrite is enabled:
[theme:genericsetup] resources-overwrite = true
In addition, this plugin can be configured to purge existing directories before copying with:
[theme:genericsetup] resources-purge= true
Although, the plugin will still never remove top-level resources directories (like theme, sitelayout or contentlayout).
Technically resources are simply copied into portal_resources and they can be manually removed via ZMI. Please, note that changes made in theme editor are not copied unless theme has been re-activated (or updated).
This plugin has also experimental support for TTW custom permissions, which are useful for more complex content management scenarios involving Dexterity content types and workflows. New permissions are registered before the GenericSetup profile get imported, to make to new permission to be available during import.
Custom permissions are listed in theme’s manifest.cfg in id Title format as follow:
[theme:genericsetup] permissions = mydomain.addMyProduct MyDomain: Add My Product mydomain.removeMyProduct MyDomain: Remove My Product
Custom permissions are removed when theme is disabled. Yet, they disappear from ZMI only when the site is restarted.
The registered persistent permissions use and depend on LocalPermission class from zope.app.localpermission. If this package is removed without uninstalling theme with permisions at first, zope.app.localpermission must exit to prevent possible errors caused by missing object class.
In addition, permissions must be registered for Zope 2 in a non-persistent way, which requires restart to remove permissions from ZMI screens. Because of this, even installed permissions continue to work only as long as this package is available.
The existence of these permissions can be confirmed from ZMI Components-tab from Plone site root by looking for Permission utilities, on ZMI security tab and e.g. in the options for Add permission in ZMI portal type factory information pages.
Exporting the site setup
This plugin provides helper forms for exporting the current site setup into a through-the-web created (writable) theme and importing that site setup manually from the theme folder.
The export form is registered for the theme resource directory as @@export-site-setup and the import form as @@import-site-setup.
The export form is useful for creating the initial site setup into the theme directory. Simply
- Create a new theme from Theming control panel
- Go to the export form URL, e.g. http://localhost:8080/Plone/++theme++my-theme/@@export-site-setup:
- Choose the steps you wish to export and click Export.
Editing the site setup
The site setup steps can be edited like any theme file through the theme editor:
Note: Because the theme editor hides all dotfiles, files starting with a dot must be renamed to end with .dotfile (and to not start with a dot).
Importing the setup
By default, this plugin is configured import setup steps from a directory install whenever the theme is activated, and steps from a directory uninstall, when the theme is deactivated. Both, install and uninstall step directory can be changed in the plugin configuration.
In addition, it’s possible to import the embedded steps manually using the import setup form. Simply
- Go to the import form URL for your theme, e.g. http://localhost:8080/Plone/++theme++my-theme/@@import-site-setup:
- Choose the steps you wish to import and click Import.
Better site structure export and import
This package includes optional enhancements for the default Plone site structure export and import.
The enhancements include:
- support for News Item contents
- support for Zope Page Templates
- support for Python Scripts
- support for exporting tagged hidden folders (like portal_skins/custom)
The enhancements can be activated by including a special component configuration file in your Plone buildout’s instance parts with:
[instance] ... zcml = collective.themesitesetup-extras
ZMI-only content, which is hidden in Plone (folders like portal_skins) can be included in the export by tagging the folders in ZMI interface tab with a special marker interface:
PageTemplates and PythonScripts can only be exported when they are located in a ZMI-only container with this marker interface. So, if you’d like to export contents in portal_skins/custom, you should add one marker for portal_skins and the other for custom.
This is only required when exporting ZMI-only content. Importing ZMI-only content works according to normal structure import rules without these marker interfaces.
About plone.app.contenttypes support
In addition, plone.app.textfield >=1.2.5 is recommended to fix issue, where structure import does not decode field value properly, causing UnicodeDecodeErrors later.
About custom Dexterity content support
Importing site structures with custom Dexterity content types require custom adapter to be implemented and registered for each content type
from Products.GenericSetup.interfaces import IContentFactory from collective.themesitesetup.content import DexterityContentFactoryBase from plone.dexterity.interfaces import IDexterityContent from zope.component import adapter from zope.interface import implementer @adapter(IDexterityContent) @implementer(IContentFactory) class MyTypeFactory(DexterityContentFactoryBase): portal_type = 'MyType'
<adapter factory=".adapters.MyTypeFactory" name="MyType" />
This is not required when Dexterity content is only created into site root or Archetypes based container.
- Fix issue where it was not possible to install message catalogs with dot in domain [datakurre]
- Pin zope.app.i18n < 4.0.0 [datakurre]
- Removed debug print [datakurre]
- Patch TTW message catalogs to support plonejs18n view (translate-pattern), but note that with plonejsi18n TTW catalog overrides don’t cascade with the existing catalogs [datakurre]
- Use theme cache for TTW permissions, because TTW permissions require that their existence is checked on each request [datakurre]
- Fix issue where message catalog support allowed (mostly accidentally) overriding messages with empty strings. Messages with empty strings are now ignored. [datakurre]
- Add to purge plone.app.blocks’ site layout cache after resource directory copy [datakurre]
- Add support for populating persistent (plone.resource) resource directories [datakurre]
- Refactor permission support to use zope.app.localpermission [datakurre]
- Add support for TTW custom permissions [datakurre]
- Add support for populating Dexterity content type models from theme from ./models/Xxxxxx.xml [datakurre]
- Fix issue where translationdomain internals prevented updating existing catalog [datakurre]
- Add support for registering i18n message catalogs directly from theme from ./locales/xx/LC_MESSAGES/yyyyy.po [datakurre]
- Add support for exporting and importing plone.app.contenttypes -content [datakurre]
- Move custom GS import export adapters to external configuration [datakurre]
- Fix to register setup forms for p.a.theming layer [datakurre]
- Update README [datakurre]
- Add site setup import view to allow testing or manual upgrading of site setups [datakurre]
- Add option to disable setup steps import via plugin configuration variable in theme manifest (either with enabled = false or disabled = true) [datakurre]
- Add GS content export support to include non-CMF-containers marked with collective.themesitesetup.interfaces.IGenericSetupExportableContainer [datakurre]
- Add GS content export/import to support non-CMF-containers, PythonScripts and PageTemplates. [datakurre]
- First release.