plone.app.themingplugins 1.2

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.

1.2 (2024-10-21)

• Python3 compat: Fix bytes decoding for views.cfg file

1.1 (2019-04-26)

• Python 3 compat, code-style. [jensens]

1.0 (2015-08-20)

• Fix parsing of views plugin settings [tlyng]

• Add Quick Example section to REAMDE [djowett]

1.0b1

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