repoze.bfg.skins 0.15

About

The package is written and maintained by Malthe Borch and Stefan Eletzhofer. Available as-is under the BSD license.

To contribute or get support for this package, please visit the #repoze channel on freenode irc or write to the repoze-dev mailinglist.

Application setup

Once you’ve included the repoze.bfg.skins ZCML, you may use the ZCML-directive <bfg:skins> to register a directory with templates and make them available as template components, e.g.::

<bfg:skins path="skins" />

The path parameter indicates a relative path which contains the skin object files.

The skins directive makes available skin components for use in library code. The default factory (see Factories) simply uses the relative path as the component name; some factories may strip off the file extension (this is the case for the page template factory).

To expose the contents of a skin directory as views, we can insert a view registration directive into the skins directive:

<bfg:skins path="skins">
   <bfg:view />
</bfg:skins>

The view directive has no required attributes, but all the attributes which are applicable for the standalone directive [1] are available, except name which is defined by the component and view which is given by the skin object.

When wrapped inside skins, an option index is available to allow registering default index views (e.g. index.pt):

<bfg:skins path="skins">
   <bfg:view index="index.pt" />
</bfg:skins>

Routes integration

Every skin component corresponds to a relative path. We can configure a route to map a subpath to skin components for which a view is registered:

<route
   name="skins"
   path="/content/*subpath"
   factory="repoze.bfg.skins.RoutesTraverserFactory"
   />

This traverser will convert the subpath into a view name and let BFG render the view if possible.

View integration

Skin components are registered as named utilities. We can use the getUtility function to retrieve a skin component by name.

For convenience, the SkinObject class doubles as a descriptor which can be used as a class attribute; it uses a getUtility call when accessed:

class MyView(object):
    __call__ = SkinObject("document_view")

The weak binding to the skin object makes it easy to depend on skin components from library code without a hard dependency.

Page template factory

Included with the package is a factory for Zope Page Templates (with the file extension “.pt”). The Chameleon rendering engine is used.

Page templates registered as skin objects will be called skin templates. Support is provided to locate other skin templates and include them as macros. This is made pluggable such that applications can add additional functionality.

This package provides a new expression skin: which will retrieve a skin object by name:

The skin object factory for page templates provide the macros attribute. The following snippet illustrates this:

<div
  tal:define="master skin: main_template"
  metal:use-macro="master.macros['main']"
  />

The route: expression maps to the route_url framework function:

<img tal:attributes=”src string:${route: skins}/images/logo.png” />

Automatic discovery and reload

When the global setting debug is set (to any non-trivial value), skin objects are discovered at run-time and files are automatically reloaded when changed.

Skin objects as components

After this bit of configuration, our skin objects are available as components.

>>> from zope.component import getUtility
>>> from repoze.bfg.skins.interfaces import ISkinObject

The name of the component is the relative path.

>>> getUtility(ISkinObject, name="images/logo.png")
<repoze.bfg.skins.models.SkinObject name="images/logo.png" at ...>

The page template factory strips off the file extension. The file “index.pt” becomes a skin template with the name “index”.

>>> getUtility(ISkinObject, name="index")
<repoze.bfg.skins.models.SkinTemplate name="index" at ...>

The component name is available in the name attribute:

>>> getUtility(ISkinObject, name="index").name
u'index'

Descriptor usage

The SkinObject class works as a descriptor. This is useful to tie user interface classes with skin files with a weak binding.

>>> from repoze.bfg.skins import SkinObject

Use it as a class attribute.

>>> class MyClass(object):
...     index = SkinObject("index")
...     logo = SkinObject("images/logo.png")

The property works on the class itself, and on instances.

>>> MyClass.index
<repoze.bfg.skins.models.SkinTemplate name="index" at ...>
>>> MyClass.logo
<repoze.bfg.skins.models.SkinObject name="images/logo.png" at ...>

Or directly as a view function:

>>> index_view = SkinObject("index")

The view function takes context and request arguments, but we can get away with trivial arguments for now.

>>> print index_view(None, None).body
<html>
  <body>
    Hello, world!
  </body>
</html>

View registration

We can register views for skin objects by wrapping a view directive in the skins directive.

There are no required arguments to the view directive:

>>> testing.configure("""
... <configure xmlns="http://namespaces.repoze.org/bfg">
...    <include package="repoze.bfg.skins" />
...    <skins path="%s">
...      <view />
...    </skins>
... </configure>""" % path)

The BFG framework function render_view_to_response lets us look up views by name and retrieve a response object for a given context and request.

>>> context = testing.DummyContext()
>>> request = testing.DummyRequest("")
>>> from repoze.bfg.view import render_view_to_response

Note in the example how the directory separator character has been replaced by an underscore.

>>> response = render_view_to_response(
...    context, request, name="images_logo.png")
>>> response.status
'200 OK'
>>> response.content_type
'image/png'

The page template view first renders the template before returning the response.

>>> response = render_view_to_response(
...    context, request, name="index")
>>> response.status
'200 OK'
>>> response.content_type
'text/html'

The response body contains the rendered page template:

>>> print response.body
<html>
  <body>
    Hello, world!
  </body>
</html>

The view directive accepts a index option; optionally use it to specify an index filename for directories, e.g.

>>> testing.configure("""
... <configure xmlns="http://namespaces.repoze.org/bfg">
...    <include package="repoze.bfg.skins" />
...    <skins path="%s">
...      <view index="index.pt" />
...    </skins>
... </configure>""" % path)

This registers index views for each directory:

>>> response = render_view_to_response(
...    context, request, name="")
>>> response.status
'200 OK'
>>> response.content_type
'text/html'

>>> response = render_view_to_response(
...    context, request, name="about")
>>> response.status
'200 OK'
>>> response.content_type
'text/html'

Routes

Now that we have views registered, let’s configure a route.

>>> testing.configure("""
... <configure xmlns="http://namespaces.repoze.org/bfg">
...    <include package="repoze.bfg.skins" />
...    <route
...       name="test"
...       path="/*subpath"
...       factory="repoze.bfg.skins.RoutesTraverserFactory"
...       />
... </configure>""")

To try it out, we’ll configure a router to use the components we’ve set up.

>>> from repoze.bfg.router import Router
>>> from zope.component import getSiteManager
>>> router = Router(getSiteManager())

We need to set the root factory to the routes mapper.

>>> from zope.component import getUtility
>>> from repoze.bfg.interfaces import IRoutesMapper
>>> router.root_factory = getUtility(IRoutesMapper)

Our “test” route lets us pass in any valid skin path:

>>> testing.DummyRequest("/images/logo.png").get_response(router)
<Response at ... 200 OK>
>>> testing.DummyRequest("/index").get_response(router)
<Response at ... 200 OK>

Templates

Included with the package is functionality to support interaction between templates registered as skin components.

An expression type skin is available for page templates to look up other skin components by name.

>>> from chameleon.zpt.template import PageTemplate
>>> template = PageTemplate("""
... <html tal:define="master skin: index"
...       metal:use-macro="master.macros['main']">
...    <body metal:fill-slot="body">
...       <h1>Welcome</h1>
...       <img src="${route: test}/images/logo.png" />
...    </body>
... </html>""")

>>> print template.render(context=context, request=request)
<html>
  <body>
    <h1>Welcome</h1>
    <img src="http://localhost/images/logo.png" />
  </body>
</html>

>>> print MyClass.index.render()
<html>
  <body>
    Hello, world!
  </body>
</html>