============
Introduction
============
`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).
.. contents:: Contents
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.
.. _plone.app.theming: http://pypi.python.org/pypi/plone.app.theming
.. _z3c.jbot: http://pypi.python.org/pypi/z3c.jbot
Changelog
=========
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]
Raw data
{
"_id": null,
"home_page": "http://pypi.python.org/pypi/plone.app.theming.plugins",
"name": "plone.app.themingplugins",
"maintainer": null,
"docs_url": null,
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,<3.13,>=2.7",
"maintainer_email": null,
"keywords": "plone.app.theming diazo jbot views",
"author": "Martin Aspeli",
"author_email": "optilude@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/24/da/c1e419e91bd6556a5bdd423631832809f79dc5e1303ba9439ff939bcdb3f/plone_app_themingplugins-1.2.tar.gz",
"platform": null,
"description": "============\nIntroduction\n============\n\n`plone.app.theming`_ supports plugins that allow theme authors to bundle\nmore advanced functionality with their themes. This package contains two\nsuch plugins:\n\n* The ability to override specific Zope Page Templates when a theme is enabled\n* The ability to register views providing custom markup using Zope Page\n Templates when a theme is enabled\n\nBoth of these *only* work for themes distributed on the filesystem (either in\na Python package or in the global ``themes`` resource directory), i.e. not\nfor themes imported through-the-web in ZIP archives. That said, the features\nprovided by these plugins are more likely to be useful in building \"customer\"\nsites (where filesystem development is likely to be the norma) than in\ndistributing generic themes (where the through-the-web ZIP import is more\nattractive).\n\n.. contents:: Contents\n\nInstallation\n============\n\nThemes that rely on the plugins described below will still work even if\nthis package is not installed: the plugin configuration will simply be\nignored.\n\nTo enable these plugins, the ``plone.app.themingplugins`` package must be\nenabled in the buildout. You can achieve this in one of two ways:\n\n* By listing ``plone.app.themingplugins`` in the ``eggs`` list used by the\n Zope instances in your ``buildout.cfg`` file.\n* By adding ``plone.app.themingplugins`` to the ``install_requires`` list in\n the ``setup.py`` file for a package that is installed in your buildout,\n for example a package used to house your theme or site policy.\n\nQuick Example\n=============\n\nAssuming you are developing a diazo theme called my.theme, do the following \nto override the logo viewlet when your diazo theme is activated:\n\n* add ``plone.app.themingplugins`` to the ``install_requires`` list in\n ``src/my.theme/setup.py`` \n* To override the logo viewlet add ``plone.app.layout.viewlets.logo.pt`` \n to src/my.theme/my/theme/theme/overrides and modify as required.\n\nThe plugins\n===========\n\nA Diazo theme works by transforming the content that is generated by Plone\n(or another system). So long as the requires information is output, there is\nvirtually no limit to how it can be transformed into the themed output.\n\nIf the information isn't there, however, you will need to extract it somehow,\nusually through a page template. This can be done using views in a standard\nPython distribution, but ``plone.app.themingplugins`` provides two simplified\nmechanisms that only require knowledge of TAL, the syntax of Zope Page\nTemplates.\n\nZope Page Template overrides\n----------------------------\n\nWhen distributing themes in a resource directory on the filesystem, it is\npossible to override existing Zope Page Template templates on an ad-hoc basis\nwhen the theme is enabled. This can be useful if you need to change the data\nbeing provided by Plone in a view, viewlet or other template-based resource.\n\nThis functionality relies on `z3c.jbot`_. To use it, add a directory named\n``overrides`` to the root of your theme resource directory. In this directory,\nyou can place page template files using the naming convention\n``<package>.<filename>.pt`` to override the template originally found in\n``<filename>.pt`` in the package ``<package>``.\n\nFor example, to override ``logo.pt`` in ``plone.app.layout.viewlets``, which\nis found in ``plone/app/layout/viewlets/logo.pt`` inside the\n``plone.app.layout`` distribution, you would copy ``logo.pt`` into the\n``overrides`` directory as ``plone.app.layout.viewlets.logo.pt``. You can then\nmodify this as required.\n\n **Note:** Templates are loaded at Zope startup. In debug mode, template\n changes are reflected on the fly, but you will need to restart Zope to\n pick up new templates.\n\nThe overrides directory name can be changed in the theme's ``manifest.cfg`` file\nif required::\n \n [theme:overrides]\n directory = template-overrides\n \nThe directory name is relative to the theme directory.\n\nRegistering new views from Zope Page Templates\n----------------------------------------------\n\nWhen distributing themes in a resource directory on the filesystem, it is\npossible to register new views based on Zope Page Templates which are\navailable when the theme is enabled.\n\nThis can be useful for generating additional dynamic markup based on Plone\ncontent or settings, usually for use with an ``href`` on a theme rule, e.g.\nto generate a custom navigation structure or some other dynamic content.\n\n **Note:** This style of view registration is not intended to contain complex\n logic. For more advanced use cases, you are advised to create a Python\n distribution and register a standard browser view.\n\nTo create new views, add a directory ``views`` to the root of your theme\nresource directory and place any number of ``*.pt`` files here.\n\nFor example, say you had a file ``custom-menu.pt`` in the ``views`` directory\ncontaining (a somewhat frivolous example)::\n\n <ul id=\"menu\">\n <li class=\"menuItem\" tal:repeat=\"item context/values\">\n <a tal:attributes=\"href item/absolute_url\"\n tal:content=\"item/title_or_id\"\n />\n </li>\n </ul>\n\n(The variables ``context`` and ``request`` will work as normal in the page\ntemplates.)\n\nYou could then use a rule like::\n\n <replace css:theme=\"#menu\" css:content=\"#menu\" href=\"./@@custom-menu\" />\n\nThis will replace ``#menu`` in the theme with ``#menu`` in the output of\nrendering the ``custom-menu.pt`` template.\n\n **Note:** If you invoke the ``@@custom-menu`` view when the theme is not\n enabled, you will get a ``404 NOT FOUND`` error. This is because the view\n is registered to a browser layer that is dynamically generated for the theme\n and automatically applied only when the theme is enabled.\n\nBy default, the view name is the template name, minus the ``.pt`` extension.\nThe view requires the standard ``View`` permission (``zope2.View``), and is\navailable for all contexts (``for=\"*\"``).\n\nThese defaults can be overridden by placing a file ``views.cfg`` in the\n``views`` directory. This should contain one section per template, where the\nsection name is the template name minus the ``.pt`` extension. The valid\noptions in each section are:\n\n* ``name``, to change the view name\n* ``permission``, to give a different permission name\n* ``for``, to change the view's context\n* ``class``, to let the view re-use an existing view class\n\nFor example::\n\n # for my-view.pt:\n [my-view]\n name = my-view-at-root\n for = Products.CMFCore.interfaces.ISiteRoot\n permission = cmf.ManagePortal\n class = some.package.browser.MyView\n\nAll options are optional, as is the ``views.cfg`` file itself.\n\n **Note:** Templates are loaded at Zope startup. In debug mode, template\n changes are reflected on the fly, but you will need to restart Zope to\n pick up new templates.\n\nThe views directory name can be changed in the theme's ``manifest.cfg`` file\nif required::\n \n [theme:views]\n directory = template-views\n \nThe directory name is relative to the theme directory.\n\n.. _plone.app.theming: http://pypi.python.org/pypi/plone.app.theming\n.. _z3c.jbot: http://pypi.python.org/pypi/z3c.jbot\n\nChangelog\n=========\n\n1.2 (2024-10-21)\n----------------\n\n- Python3 compat: Fix bytes decoding for views.cfg file\n\n\n1.1 (2019-04-26)\n----------------\n\n- Python 3 compat, code-style.\n [jensens]\n\n1.0 (2015-08-20)\n----------------\n\n- Fix parsing of views plugin settings\n [tlyng]\n\n- Add `Quick Example` section to REAMDE\n [djowett]\n\n\n1.0b1\n-----\n\n- Initial release spun off from plone.app.theming\n [optilude]\n",
"bugtrack_url": null,
"license": "GPL",
"summary": "Plugins providing advanced plone.app.theming integration",
"version": "1.2",
"project_urls": {
"Homepage": "http://pypi.python.org/pypi/plone.app.theming.plugins"
},
"split_keywords": [
"plone.app.theming",
"diazo",
"jbot",
"views"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b86e20442ae55653989e07032b7bc8d62ff35563c4ada3dcae5757e976dd9a42",
"md5": "0af99a527a9b3de2a89dfd6f7789ed57",
"sha256": "74ab5aafc8c11bf039eb2a94d2a7c82a79cdafd0135cfcd7576f57d8ffbf47fb"
},
"downloads": -1,
"filename": "plone.app.themingplugins-1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0af99a527a9b3de2a89dfd6f7789ed57",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,<3.13,>=2.7",
"size": 22121,
"upload_time": "2024-10-21T09:14:20",
"upload_time_iso_8601": "2024-10-21T09:14:20.869421Z",
"url": "https://files.pythonhosted.org/packages/b8/6e/20442ae55653989e07032b7bc8d62ff35563c4ada3dcae5757e976dd9a42/plone.app.themingplugins-1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "24dac1e419e91bd6556a5bdd423631832809f79dc5e1303ba9439ff939bcdb3f",
"md5": "04ea2b9c2a265598dec713742323ddba",
"sha256": "5d6378d4c8f2fa2ce837a6f244235a6250adf6f1e8e58cc03609eba96c6cdc4d"
},
"downloads": -1,
"filename": "plone_app_themingplugins-1.2.tar.gz",
"has_sig": false,
"md5_digest": "04ea2b9c2a265598dec713742323ddba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,<3.13,>=2.7",
"size": 22703,
"upload_time": "2024-10-21T09:14:22",
"upload_time_iso_8601": "2024-10-21T09:14:22.714909Z",
"url": "https://files.pythonhosted.org/packages/24/da/c1e419e91bd6556a5bdd423631832809f79dc5e1303ba9439ff939bcdb3f/plone_app_themingplugins-1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-21 09:14:22",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "plone.app.themingplugins"
}
JSON