(Layers)

はじめに

Layers allow you to activate different code paths and modules depending on the external configuration

Examples:

• Theme code is only activated when theme is being selected
• Mobile browsing code is only activated when the site is being browser on a mobile phone

Layers are marker interfacse applied to HTTPRequest object. They are usually used in conjunction with ZCML directives to dynamically activate various parts of the configuration (theme files, 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, but still leaving you with an option to have possibly conflicting add-on products in your buildout and ZCML once. Remember that multiple Plone site instances can share the same ZCML and code files.

Many ZCML directives take the optional layer parameter. See example, resourceDirectory

Layers can be activated when an add-on product is installed or a certain theme is picked.

For more information, read

• Making components theme specific
• Browser Layer tutorial.
• Zope 3 Developer Handbook, Skinning

Using layers

Some ZCML directives (example: browser:page) take layer attribute.

If you have

# plonetheme.yourthemename.interfaces.IThemeSpecific layer defined in Python code

# YourTheme product installed through add-on product installer on your site instance

Views and viewlets will be active 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"
    />

Unconditional overrides

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 overrides.zcml.

Creating a layer

Theme layer

Theme layers can be created with the following steps

1. Subclass an interface from IDefaultPloneLayer

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.
    """

2. Register in in ZCML. Name must match the theme name.

<interface
    interface=".interfaces.IThemeSpecific"
    type="zope.publisher.interfaces.browser.IBrowserSkinType"
    name="SitsSkin"
    />

3. Declare your theme in profiles/default/skins.xml. Example.

<skin-path name="SitsSkin" based-on="Plone Default">
  <layer name="plone_skins_style_folder_name"
     insert-before="*"/>
</skin-path>

4. Create profiles/default/browserlayer.xml.

<layers>
 <layer
     name="myproduct"
     interface="Products.myproduct.interfaces.IThemeSpecific"
     />
 </layer>
</layers>

Product layer

Product layer is enabled when an add-on product is installed. It works like the theme layer.

See example in LinguaPlone.

Manual layers

Apply your layer to HTTPRequest in before_traverse hook or before you call the code which looks up the interfaces.

Choosing skin layer dynamically 1: http://blog.fourdigits.nl/changing-your-plone-theme-skin-based-on-the-objects-portal_type

Choosing skin layer dynamically 2: http://code.google.com/p/plonegomobile/source/browse/trunk/gomobile/gomobile.mobile/gomobile/mobile/monkeypatch.py

See plone.app.z3cform.z2 module.

In the example below we turn on a layer for request which is later checked by the rendering code. This way some pages can ask special View/Viewlet rendering.

Example:

# Defining layer

from zope.publisher.interfaces.browser import IBrowserRequest

class INoHeaderLayer(IBrowserRequest):
    """ When applied to HTTP request object, hedaer animations or images are not rendered on this.

    If this layer is on 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)

Problem with IDefaultBrowserLayer

zope.publisher.interfaces.browser.IDefaultBrowserLayer is a problematic layer is it takes precedence in HTTP request multi-adapter look up (due to magic involving Plone themes).

Below is self.request.__provides__.__iro__ dump for adding an extra form layer

(<InterfaceClass Products.CMFDefault.interfaces.ICMFDefaultSkin>,
 <InterfaceClass plone.z3cform.z2.IFixedUpRequest>,
 <InterfaceClass getpaid.expercash.browser.views.IExperCashFormLayer>,
 <InterfaceClass plone.app.z3cform.interfaces.IPloneFormLayer>,
 <InterfaceClass z3c.form.interfaces.IFormLayer>,
 <InterfaceClass zope.publisher.interfaces.browser.IBrowserRequest>,
 ...

One would assume a custom form layer (IExperCashFormLayer) is used and it would take priority over more generic IPloneFormLayer. However, due to involment of IDefaultBrowserLayer when registering items using <browser:page for="*"> syntax.

The fix is to make your custom layer to subclass IDefaultBrowserLayer like:

class IExperCashFormLayer(IDefaultBrowserLayer, IPloneFormLayer):
    """ Define a custom layer for which against our form macros are registered.

    This way we override the default plone.app.z3cform templates.

    Inheriting from IDefaultBrowserLayer makes sure this layer will get 1st priority.
    """

We register a custom macros like

<!-- Override plone.app.z3cform default form template -->
<browser:page
    name="ploneform-macros"
    for="*"
    layer=".views.IExperCashFormLayer"
    class=".views.Macros"
    template="templates/expercash-form-macros.pt"
    allowed_interface="zope.interface.common.mapping.IItemMapping"
    permission="zope.Public"
    />

And then the manual assignment works ok:

def update(self):
      """ z3c.form.form.Form.Update() method
      """

      # This will fix @@ploneform-macros to use our special version
      zope.interface.alsoProvides(self.request, IExperCashFormLayer)

      # This should return macros we have registered
      macros = self.context.unrestrictedTraverse("@@ploneform-macros")

(If this didn’t make sense for you, don’t worry. It doesn’t make sense for me either.)

Checking active layers

Layers are activated on the current request object

Example:

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 list of all layers active on the site. Note that this is different list of layers which are application on the current HTTP request object - request object may contain manually activated layers.

Example:

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 activate at once.

Active theme name is defined in portal_skins properties. This name can be resolved to a theme layer.

Debugging active layers

You can check the activated layers from HTTP request object in self.request.__provides__.__iro__. Layers are evaluated from zero index (highest priority) the last index (lowest priority)