This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
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.

Quick Example

Assuming you are developing a diazo theme called my.theme, do the following to override the logo viewlet when your diazo theme is activated:

  • add plone.app.themingplugins to the install_requires list in src/my.theme/setup.py
  • To override the logo viewlet add plone.app.layout.viewlets.logo.pt to src/my.theme/my/theme/theme/overrides and modify as required.

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.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]
Release History

Release History

1.0

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0b1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
plone.app.themingplugins-1.0.zip (38.4 kB) Copy SHA256 Checksum SHA256 Source Aug 20, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting