Metadata-Version: 1.1
Name: plone.app.themingplugins
Version: 1.0
Summary: Plugins providing advanced plone.app.theming integration
Home-page: http://pypi.python.org/pypi/plone.app.theming.plugins
Author: Martin Aspeli
Author-email: optilude@gmail.com
License: GPL
Description: ============
        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.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]
        
Keywords: plone.app.theming diazo jbot views
Platform: UNKNOWN
Classifier: Framework :: Plone
Classifier: Programming Language :: Python
