Metadata-Version: 1.0
Name: megrok.chameleon
Version: 0.1
Summary: Chameleon page template support for Grok
Home-page: http://pypi.python.org/pypi/megrok.chameleon
Author: Uli Fouquet
Author-email: grok-dev@zope.org
License: ZPL
Description: megrok.chameleon
        ****************
        
        `megrok.chameleon` makes it possible to use chameleon templates in Grok.
        
        Currently support for chameleon genshi templates and chameleon zope
        page templates is provided.
        
        For more information on Grok and Chameleon templates see:
        
        - http://grok.zope.org/
        - http://pypi.python.org/pypi/chameleon.zpt
        - http://pypi.python.org/pypi/chameleon.genshi
        
        .. contents::
        
        Requirements
        ============
        
        .. note:: **This package works only with Python2.5**
        
        - Chameleon templates (`chameleon.zpt`)  Tested with v 1.0b9.
        - Chameleon genshi templates (`chameleon.genshi`) Tested with v 1.0b3.
        - Grok v1.0a1 or later.  Tested with 1.0a1.
        
        Installation
        ============
        
        To use Chameleon page templates with Grok all you need is to install
        megrok.chameleon as an egg and include its ZCML. The best place to do
        this is to make `megrok.chameleon` a dependency of your application by
        adding it to your ``install_requires`` list in ``setup.cfg``. If you
        used grokprojet to create your application ``setup.py`` is located in the
        project root. It should look something like this::
        
        install_requires=['setuptools',
        'grok',
        'megrok.chameleon',
        # Add extra requirements here
        ],
        
        Then include ``megrok.chameleon`` in your ``configure.zcml``. If you
        used grokproject to create your application it's at
        ``src/<projectname>/configure.zcml``. Add the include line after the
        include line for grok, but before the grokking of the current
        package. It should look something like this::
        
        <include package="grok" />
        <include package="megrok.chameleon" />
        <grok:grok package="." />
        
        If you use ``autoInclude`` in your ``configure.zcml``, you should not
        have to do this latter step.
        
        Then run ``bin/buildout`` again. You should now see buildout saying
        something like::
        
        Getting distribution for 'megrok.chameleon'.
        Got megrok.genshi 0.1.
        
        That's all. You can now start using Chameleon page templates in your
        Grok application!
        
        
        Usage
        =====
        
        ``megrok.chameleon`` supports the Grok standard of placing templates
        in a templates directory, for example ``app_templates``, so you can
        use Chameleon page templates by simply placing the Chameleon genshi
        templates or Chameleon Zope page templates in the templates directory,
        just as you would with regular ZPT templates.  Although chameleon
        templates themselves do not have a standard for the file extensions
        for templates, Grok needs to have an association between an
        extension and a type so it knows which type of template each template
        is.  `megrok.chameleon` defines the following extensions:
        
        * ``.cpt`` (``Chameleon page template``) for Chameleon page templates
        
        * ``.cg`` (``Chameleon genshi template``) for chameleon driven genshi
        templates
        
        * ``.cgt`` (``Chameleon genshi text template``) for chameleon driven
        genshi text templates
        
        You can also use Chameleon page templates inline.  The syntax for this
        is::
        
        from megrok.chameleon.components import ChameleonPageTemplate
        index = ChameleonPageTemplate('<html>the html code</html>')
        
        Or if you use files::
        
        from megrok.genshi.components import ChameleonPageTemplateFile
        index = ChameleonPageTemplateFile(filename='thefilename.html')
        
        
        
        Detailed Description
        ********************
        
        Grok-support for using chameleon driven templates.
        
        :Test-Layer: functional
        
        With `megrok.chameleon` you can use templates parsed and rendered by
        `chameleon`. Currently Zope page templates and Genshi templates are
        supported.
        
        Chameleon Zope page templates
        =============================
        
        Chameleon provides support for Zope page templates which can be used
        from grok writing templates with the ``.cpt`` (=Chameleon Page
        Template) filename extension.
        
        Chameleon page templates differ from standard Zope page templates in a
        few aspects, most notably:
        
        * Expressions are parsed in ``Python-mode`` by default. This means,
        instead of ``tal:content="view/value"`` you must use
        ``tal:content="view.value"``. Every occurence of TAL-expressions
        starting with ``python:`` now can be shortened by skipping this
        marker.
        
        * Also genshi-like variable substitutions are supported. For example
        you can write ``${myvar}`` instead of ``tal:content="myvar"``.
        
        Beside this, most rules for regular Zope page templates apply also to
        chameleon page templates.
        
        See the `chameleon.zpt`_ page for more information.
        
        .. _chameleon.zpt: http://pypi.python.org/pypi/chameleon.zpt
        
        Prerequisites
        -------------
        
        Before we can see the templates in action, we care for correct
        registration and set some used variables::
        
        >>> import os
        >>> testdir = os.path.join(os.path.dirname(__file__), 'tests')
        >>> cpt_fixture = os.path.join(testdir, 'cpt_fixture')
        >>> template_dir = os.path.join(cpt_fixture, 'app_templates')
        
        We register everything. Before we can grok our fixture, we have to
        grok the `megrok.chameleon` package. This way the new template types
        are registered with the framework::
        
        >>> import grok
        >>> grok.testing.grok('megrok.chameleon')
        >>> grok.testing.grok('megrok.chameleon.tests.cpt_fixture')
        
        We create a mammoth, which should provide us a bunch of chameleon page
        template driven views and put it in the database to setup location
        info::
        
        >>> from megrok.chameleon.tests.cpt_fixture.app import Mammoth
        >>> manfred = Mammoth()
        >>> getRootFolder()['manfred'] = manfred
        
        Furthermore we prepare for getting the different views on manfred::
        
        >>> from zope.publisher.browser import TestRequest
        >>> from zope.component import getMultiAdapter
        >>> request = TestRequest()
        
        Simple templates
        ----------------
        
        We prepared a plain cavepainting view. The template looks like this::
        
        >>> cavepainting_cpt = os.path.join(template_dir, 'cavepainting.cpt')
        >>> print open(cavepainting_cpt, 'rb').read()
        <html>
        <body>
        A cave painting.
        </body>
        </html>
        
        The rendered view looks like this::
        
        >>> view = getMultiAdapter((manfred, request),
        ...                         name='cavepainting')
        >>> print view()
        <html>
        <body>
        A cave painting.
        </body>
        </html>
        
        Substituting variables
        ----------------------
        
        A template can access variables like ``view``, ``context`` and its
        methods and attributes. The ``food`` view does exactly this. The
        template looks like this::
        
        >>> food_cpt = os.path.join(template_dir, 'food.cpt')
        >>> print open(food_cpt, 'rb').read()
        <html>
        <body>
        <span tal:define="foo 'a FOO'" />
        ${view.me_do()}
        CSS-URL: ${static['test.css']()}
        My context is: ${view.url(context)}
        ${foo}
        </body>
        </html>
        
        The rendered view looks like this::
        
        >>> view = getMultiAdapter((manfred, request), name='food')
        >>> print view()
        <html>
        <body>
        <span />
        ME GROK EAT MAMMOTH!
        CSS-URL: http://127.0.0.1/@@/megrok.chameleon.tests.cpt_fixture/test.css
        My context is: http://127.0.0.1/manfred
        a FOO
        </body>
        </html>
        
        Inline Templates
        ----------------
        
        We can also define inline templates. In our ``app.py`` we defined an
        inline template like this::
        
        import grok
        from megrok.chameleon import components
        
        ...
        
        class Inline(grok.View):
        sometext = 'Some Text'
        
        inline = components.ChameleonPageTemplate(
        "<html><body>ME GROK HAS INLINES! ${view.sometext}</body></html>")
        
        If we render this view we get::
        
        >>> view = getMultiAdapter((manfred, request), name='inline')
        >>> print view()
        <html><body>ME GROK HAS INLINES! Some Text</body></html>
        
        Clean up::
        
        >>> del getRootFolder()['manfred']
        
        
        Chameleon Genshi templates
        ==========================
        
        Chameleon provides supprt for Genshi templates which can be used from
        grok writing templates with the ``.cg`` filename extension.
        
        Genshi text templates can be used with the ``.cgt`` filename
        extension.
        
        Note, that chameleon genshi templates might not cover the full range
        of functionality offered by native genshi parsers. Use `megrok.genshi`
        if you want native genshi support.
        
        See the `chameleon.genshi`_ page for more information.
        
        .. _chameleon.genshi: http://pypi.python.org/pypi/chameleon.genshi
        
        
        Prerequisites
        -------------
        
        Before we can see the templates in action, we care for correct
        registration and set some used variables::
        
        >>> import os
        >>> testdir = os.path.join(os.path.dirname(__file__), 'tests')
        >>> genshi_fixture = os.path.join(testdir, 'genshi_fixture')
        >>> template_dir = os.path.join(genshi_fixture, 'app_templates')
        
        We register everything. Before we can grok our fixture, we have to
        grok the `megrok.chameleon` package. This way the new template types
        are registered with the framework::
        
        >>> import grok
        >>> grok.testing.grok('megrok.chameleon')
        >>> grok.testing.grok('megrok.chameleon.tests.genshi_fixture')
        
        We create a mammoth, which should provide us a bunch of Genshi driven
        views and put it in the database to setup location info::
        
        >>> from megrok.chameleon.tests.genshi_fixture.app import Mammoth
        >>> manfred = Mammoth()
        >>> getRootFolder()['manfred'] = manfred
        
        Furthermore we prepare for getting the different views on manfred::
        
        >>> from zope.publisher.browser import TestRequest
        >>> from zope.component import getMultiAdapter
        >>> request = TestRequest()
        
        
        Simple templates
        ----------------
        
        We prepared a plain cavepainting view. The template looks like this::
        
        >>> cavepainting_cg = os.path.join(template_dir, 'cavepainting.cg')
        >>> print open(cavepainting_cg, 'rb').read()
        <html>
        <body>
        A cave painting.
        </body>
        </html>
        
        The rendered view looks like this::
        
        >>> view = getMultiAdapter((manfred, request),
        ...                         name='cavepainting')
        >>> print view()
        <html>
        <body>
        A cave painting.
        </body>
        </html>
        
        
        Substituting variables
        ----------------------
        
        A template can access variables like ``view``, ``context`` and its
        methods and attributes. The ``food`` view does exactly this. The
        template looks like this::
        
        >>> food_cg = os.path.join(template_dir, 'food.cg')
        >>> print open(food_cg, 'rb').read()
        <html>
        <body>
        ${view.me_do()}
        CSS-URL: ${static['test.css']()}
        My context is: ${view.url(context)}
        </body>
        </html>
        
        The rendered view looks like this::
        
        >>> view = getMultiAdapter((manfred, request), name='food')
        >>> print view()
        <html>
        <body>
        ME GROK EAT MAMMOTH!
        CSS-URL: http://127.0.0.1/@@/megrok.chameleon.tests.genshi_fixture/test.css
        My context is: http://127.0.0.1/manfred
        </body>
        </html>
        
        
        Including other templates
        -------------------------
        
        With genshi support we can also include other templates. The
        ``gatherer`` view looks like this::
        
        >>> gatherer_cg = os.path.join(template_dir, 'gatherer.cg')
        >>> print open(gatherer_cg, 'rb').read()
        <html xmlns:xi="http://www.w3.org/2001/XInclude">
        <body>
        ME GROK GATHER BERRIES!
        <xi:include href="berries.cg"/>
        </body>
        </html>
        
        Apparently here we include a template called ``berries.cg``. It looks
        like this::
        
        >>> berries_cg = os.path.join(template_dir, 'berries.cg')
        >>> print open(berries_cg, 'rb').read()
        <strong>Lovely blueberries!</strong>
        
        
        When we render the former template, we get::
        
        >>> view = getMultiAdapter((manfred, request), name='gatherer')
        >>> print view()
        <html>
        <body>
        ME GROK GATHER BERRIES!
        <strong>Lovely blueberries!</strong>
        </body>
        </html>
        
        Text templates
        --------------
        
        Also genshi text templates are supported. We have a template that
        looks like so::
        
        >>> hunter_cgt = os.path.join(template_dir, 'hunter.cgt')
        >>> print open(hunter_cgt, 'rb').read()
        ME GROK HUNT ${view.game}!
        
        Note, that this template has the ``.cgt`` (= **c**\ ameleon **g**\ enshi
        **t**\ ext template) file extension.
        
        If we render it, all expressions are substituted::
        
        >>> view = getMultiAdapter((manfred, request), name='hunter')
        >>> print view()
        ME GROK HUNT MAMMOTH!!
        
        
        CHANGES
        *******
        
        0.1 (2009-02-22)
        ================
        
        * Initial release
        
Keywords: grok chameleon template
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python :: 2.5
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
