Package: plone.app.themingplugins
plone.app.themingsupports 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 enabledThe ability to register views providing custom markup using Zope Page
Templates when a theme is enabledBoth of theseonlywork for themes distributed on the filesystem (either in
a Python package or in the globalthemesresource 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).ContentsInstallationQuick ExampleThe pluginsZope Page Template overridesRegistering new views from Zope Page TemplatesChangelog1.1 (2019-04-26)1.0 (2015-08-20)1.0b1InstallationThemes 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, theplone.app.themingpluginspackage must be
enabled in the buildout. You can achieve this in one of two ways:By listingplone.app.themingpluginsin theeggslist used by the
Zope instances in yourbuildout.cfgfile.By addingplone.app.themingpluginsto theinstall_requireslist in
thesetup.pyfile for a package that is installed in your buildout,
for example a package used to house your theme or site policy.Quick ExampleAssuming you are developing a diazo theme called my.theme, do the following
to override the logo viewlet when your diazo theme is activated:addplone.app.themingpluginsto theinstall_requireslist insrc/my.theme/setup.pyTo override the logo viewlet addplone.app.layout.viewlets.logo.ptto src/my.theme/my/theme/theme/overrides and modify as required.The pluginsA 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, butplone.app.themingpluginsprovides two simplified
mechanisms that only require knowledge of TAL, the syntax of Zope Page
Templates.Zope Page Template overridesWhen 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 onz3c.jbot. To use it, add a directory namedoverridesto the root of your theme resource directory. In this directory,
you can place page template files using the naming convention<package>.<filename>.ptto override the template originally found in<filename>.ptin the package<package>.For example, to overridelogo.ptinplone.app.layout.viewlets, which
is found inplone/app/layout/viewlets/logo.ptinside theplone.app.layoutdistribution, you would copylogo.ptinto theoverridesdirectory asplone.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’smanifest.cfgfile
if required:[theme:overrides]
directory = template-overridesThe directory name is relative to the theme directory.Registering new views from Zope Page TemplatesWhen 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 anhrefon 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 directoryviewsto the root of your theme
resource directory and place any number of*.ptfiles here.For example, say you had a filecustom-menu.ptin theviewsdirectory
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 variablescontextandrequestwill 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#menuin the theme with#menuin the output of
rendering thecustom-menu.pttemplate.Note:If you invoke the@@custom-menuview when the theme is not
enabled, you will get a404 NOT FOUNDerror. 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.ptextension.
The view requires the standardViewpermission (zope2.View), and is
available for all contexts (for="*").These defaults can be overridden by placing a fileviews.cfgin theviewsdirectory. This should contain one section per template, where the
section name is the template name minus the.ptextension. The valid
options in each section are:name, to change the view namepermission, to give a different permission namefor, to change the view’s contextclass, to let the view re-use an existing view classFor example:# for my-view.pt:
[my-view]
name = my-view-at-root
for = Products.CMFCore.interfaces.ISiteRoot
permission = cmf.ManagePortal
class = some.package.browser.MyViewAll options are optional, as is theviews.cfgfile 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’smanifest.cfgfile
if required:[theme:views]
directory = template-viewsThe directory name is relative to the theme directory.Changelog1.1 (2019-04-26)Python 3 compat, code-style.
[jensens]1.0 (2015-08-20)Fix parsing of views plugin settings
[tlyng]AddQuick Examplesection to REAMDE
[djowett]1.0b1Initial release spun off from plone.app.theming
[optilude]