Skip to main content

Plugins providing advanced plone.app.theming integration

Project description

plone.app.theming supports plugins that allow theme authors to bundle more advanced functionality with their themes. This package contains two such plugins:

  • The ability to override specific Zope Page Templates when a theme is enabled

  • The ability to register views providing custom markup using Zope Page Templates when a theme is enabled

Both of these only work for themes distributed on the filesystem (either in a Python package or in the global themes resource directory), i.e. not for themes imported through-the-web in ZIP archives. That said, the features provided by these plugins are more likely to be useful in building “customer” sites (where filesystem development is likely to be the norma) than in distributing generic themes (where the through-the-web ZIP import is more attractive).

Installation

Themes that rely on the plugins described below will still work even if this package is not installed: the plugin configuration will simply be ignored.

To enable these plugins, the plone.app.themingplugins package must be enabled in the buildout. You can achieve this in one of two ways:

  • By listing plone.app.themingplugins in the eggs list used by the Zope instances in your buildout.cfg file.

  • By adding plone.app.themingplugins to the install_requires list in the setup.py file for a package that is installed in your buildout, for example a package used to house your theme or site policy.

The plugins

A Diazo theme works by transforming the content that is generated by Plone (or another system). So long as the requires information is output, there is virtually no limit to how it can be transformed into the themed output.

If the information isn’t there, however, you will need to extract it somehow, usually through a page template. This can be done using views in a standard Python distribution, but plone.app.themingplugins provides two simplified mechanisms that only require knowledge of TAL, the syntax of Zope Page Templates.

Zope Page Template overrides

When distributing themes in a resource directory on the filesystem, it is possible to override existing Zope Page Template templates on an ad-hoc basis when the theme is enabled. This can be useful if you need to change the data being provided by Plone in a view, viewlet or other template-based resource.

This functionality relies on z3c.jbot. To use it, add a directory named overrides to the root of your theme resource directory. In this directory, you can place page template files using the naming convention <package>.<filename>.pt to override the template originally found in <filename>.pt in the package <package>.

For example, to override logo.pt in plone.app.layout.viewlets, which is found in plone/app/layout/viewlets/logo.pt inside the plone.app.layout distribution, you would copy logo.pt into the overrides directory as plone.app.layout.viewlets.logo.pt. You can then modify this as required.

Note: Templates are loaded at Zope startup. In debug mode, template changes are reflected on the fly, but you will need to restart Zope to pick up new templates.

The overrides directory name can be changed in the theme’s manifest.cfg file if required:

[theme:overrides]
directory = template-overrides

The directory name is relative to the theme directory.

Registering new views from Zope Page Templates

When distributing themes in a resource directory on the filesystem, it is possible to register new views based on Zope Page Templates which are available when the theme is enabled.

This can be useful for generating additional dynamic markup based on Plone content or settings, usually for use with an href on a theme rule, e.g. to generate a custom navigation structure or some other dynamic content.

Note: This style of view registration is not intended to contain complex logic. For more advanced use cases, you are advised to create a Python distribution and register a standard browser view.

To create new views, add a directory views to the root of your theme resource directory and place any number of *.pt files here.

For example, say you had a file custom-menu.pt in the views directory containing (a somewhat frivolous example):

<ul id="menu">
    <li class="menuItem" tal:repeat="item context/values">
        <a tal:attributes="href item/absolute_url"
           tal:content="item/title_or_id"
           />
    </li>
</ul>

(The variables context and request will work as normal in the page templates.)

You could then use a rule like:

<replace css:theme="#menu" css:content="#menu" href="./@@custom-menu" />

This will replace #menu in the theme with #menu in the output of rendering the custom-menu.pt template.

Note: If you invoke the @@custom-menu view when the theme is not enabled, you will get a 404 NOT FOUND error. This is because the view is registered to a browser layer that is dynamically generated for the theme and automatically applied only when the theme is enabled.

By default, the view name is the template name, minus the .pt extension. The view requires the standard View permission (zope2.View), and is available for all contexts (for="*").

These defaults can be overridden by placing a file views.cfg in the views directory. This should contain one section per template, where the section name is the template name minus the .pt extension. The valid options in each section are:

  • name, to change the view name

  • permission, to give a different permission name

  • for, to change the view’s context

  • class, to let the view re-use an existing view class

For example:

# for my-view.pt:
[my-view]
name = my-view-at-root
for = Products.CMFCore.interfaces.ISiteRoot
permission = cmf.ManagePortal
class = some.package.browser.MyView

All options are optional, as is the views.cfg file itself.

Note: Templates are loaded at Zope startup. In debug mode, template changes are reflected on the fly, but you will need to restart Zope to pick up new templates.

The views directory name can be changed in the theme’s manifest.cfg file if required:

[theme:views]
directory = template-views

The directory name is relative to the theme directory.

Changelog

1.0b1

  • Initial release spun off from plone.app.theming [optilude]

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

plone.app.themingplugins-1.0b1.zip (29.7 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page