Layers allow you to activate different code paths and modules depending on the external configuration. Layers are useful in the following scenarios.
Code belonging to a theme is only active when that theme has been selected.
Mobile browsing code is only active when the site is being browsed on a mobile phone.
Layers are marker interfaces applied to the HTTPRequest object. They are usually used in conjunction with Zope Configuration Mark-up Language (ZCML) directives to dynamically activate various parts of the configuration, such as theme files or add-on product functionality.
Layers ensure that only one add-on product can override the specific Plone instance functionality in your site at a time, while still allowing you to have possibly conflicting add-on products in your buildout and ZCML. Multiple Plone site instances can share the same ZCML and code files.
Many ZCML directives take the optional
Layers are activated when an add-on product is installed or a certain theme is activated.
You can find an example of the layer attribute in the Chapter Using layers.
Some ZCML directives take a
layer attribute, such as
Given the following:
A layer interface defined in Python code,
Your add-on or theme package installed through the add-on product installer on your site instance.
Then views and viewlets from your product can be enabled on the site instance using the following ZCML:
<!-- Site actions override in YourTheme --> <browser:viewlet name="plone.site_actions" manager="plone.app.layout.viewlets.interfaces.IPortalHeader" class=".siteactions.SiteActionsViewlet" layer="plonetheme.yourthemename.interfaces.IThemeSpecific" permission="zope2.View" />
If you want to override a view or a viewlet unconditionally for all sites without the add-on product installer support, you need to use
You can override classes and templates in this file.
To do this, you put the ZCML registration in a file called
overrides.zcml in the package root, next to the top-most
Creating a layer#
Developers can create layers for themes, extensions, behaviors, and other functions.
Theme layers can be created through the following steps.
Subclass an interface from
from plone.theme.interfaces import IDefaultPloneLayer class IThemeSpecific(IDefaultPloneLayer): """ Marker interface that defines a Zope 3 skin layer bound to a Skin Selection in portal_skins. If you need to register a viewlet only for the "YourSkin" skin, this is the interface that must be used for the layer attribute in YourSkin/browser/configure.zcml. """
Register it in ZCML. The name must match the theme name.
<interface interface=".interfaces.IThemeSpecific" type="zope.publisher.interfaces.browser.IBrowserSkinType" name="SitsSkin" />
Register and set your theme as the default theme in
profiles/default/skins.xml. Theme layers require that they are set as the default theme and not just activated on your Plone site. Example:
<object name="portal_skins" allow_any="False" cookie_persistence="False" default_skin="SitsSkin"> <!-- define skins-based folder objects here if any --> <skin-path name="SitsSkin" based-on="Plone Default"> <layer name="plone_skins_style_folder_name" insert-before="*"/> </skin-path> </object>
Add-on layer for clean extensions#
An add-on product layer is enabled when an add-on product is installed. Since one Zope application server may contain several Plone sites, you need to keep enabled code paths separate by using add-on layers. Otherwise, all views and viewlets apply to all sites in one Zope application server.
You can enable views and viewlets specific to functional add-ons.
Unlike theme layers, add-on layers depend on the activated add-on products, not on the selected theme.
An add-on layer is a marker interface which is applied on the HTTPRequest object by Plone core logic.
First create an interface for your layer in
""" Define interfaces for your add-on. """ import zope.interface class IAddOnInstalled(zope.interface.Interface): """ A layer specific for this add-on product. This interface is referred in browserlayer.xml. All views and viewlets register against this layer will appear on your Plone site only when the add-on installer has been run. """
You then need to refer to this in the
profile/default/browserlayer.xml file of your add-on installer to use it:
<layers> <layer name="your.product" interface="your.product.interfaces.IAddOnInstalled" /> </layers>
The add-on layer registry is persistent and stored in the database. The changes to add-on layers are applied only when add-ons are installed or uninstalled.
Add-on layer for changing existing behavior#
You can also use layers to modify the behavior of Plone or another add-on.
To make sure that your own view is used, your layer must be more specific than the layer where the original view is registered.
For example, some
z3cform things register their views on the
If you want to override the
ploneform-macros view that is registered on the
IPloneFormLayer, your own layer must be a subclass of
If a view does not declare a specific layer, it becomes registered on the
Apply your layer to the HTTPRequest in the
before_traverse hook, or before you call the code which looks up the interfaces.
In the example below, we turn on a layer for the request, which is later checked by the rendering code. This way some pages can ask for special View/Viewlet rendering.
# Defining layer from zope.publisher.interfaces.browser import IBrowserRequest class INoHeaderLayer(IBrowserRequest): """ When applied to HTTP request object, header animations or images are not rendered on this layer. If this layer is on a request, do not render header images. This allows uncluttered editing of header animations and images. """ # Applying layer for some requests (manually done in view) # The browser page which renders the form class EditHeaderAnimationsView(FormWrapper): form = HeaderCRUDForm def __call__(self): """ """ # Signal viewlet layer that we are rendering # edit view for header animations and it is not meaningful # to try to render the big animation on this page zope.interface.alsoProvides(self.request, INoHeaderLayer) # Render the edit form return FormWrapper.__call__(self)
Troubleshooting instructions for layers#
Check that your view is working without a layer assigned globally.
configure.zcmlhas a layer entry. Put some garbage to trigger a syntax error in
configure.zcmlto make sure that it is being loaded.
Add-on layer: check that
profiles/default/browserlayer.xmlhas a matching entry with a matching name.
Theme layer: if it is a theme layer, check that there is a matching
Check that the layer name is spelled correctly in the view declaration.
Checking active layers#
This section describes a few strategies for developers to check active layers according to their type.
Layers are activated on the current request object#
if INoHeaderLayer.providedBy(self.request): # The page has asked to suspend rendering of the header animations return ""
Active themes and add-on products#
registered_layers() method returns a list of all layers active on the site.
Note that this is different from the list of layers which are applied on the current HTTP request object.
The request object may contain manually activated layers.
from interfaces import IThemeSpecific from plone.browserlayer.utils import registered_layers if IThemeSpecific in registered_layers(): # Your theme specific code pass else: # General code pass
Getting active theme layer#
Only one theme layer can be active at once.
The active theme name is defined in
This name can be resolved to a theme layer.
Debugging active layers#
You can check the activated layers from the HTTP request object by looking at
Layers are evaluated from zero index (highest priority) to the last index (lowest priority).
Plone testing tool kits will not register layers for you. You have to do it yourself somewhere in the boilerplate code, as shown in the following example.
from zope.interface import directlyProvides directlyProvides(self.portal.REQUEST, IThemeLayer)