Bringing it all back home

In Zope 2, the application "skin" is comprised of a set of ordered layers, each containing a number of skin objects. These could be Python scripts (running in restricted mode), templates, form controller scripts and static files such as images.

The upshot is that you get to dump files in there and have them immediately working with no additional configuration needed (the file extension is used to infer the type); the downside is that it's a global namespace, there's no restriction on adaptation (any object can be the context and every request type is valid) and there's no permission check.

To contrast, in Zope 3, skin objects have been replaced with browser pages and resources, which are typically configured using the ZCML component configuration language. The Zope 3 way essentially boils down to configuration over convention, and a dose of "explicit is better than implicit".

We can play around with these words and relate to even other ways; one of them is "implicit configuration", and this is partly where Grok finds itself.

In this little writeup, I'd like to introduce two packages that try to be "explicit and conventional", ``repoze.bfg.skins`` and ``repoze.bfg.static``.

Although they can very well be used on their own, it makes sense to combine them. The latter provides "configure once, use everywhere" static resource serving (we're in a WSGI Paste application here).

Static resources are served from mount points that map a URL to a directory on the file-system. The mount points are just adapters registered as views, but they are also responsible for handing out a URL for a particular file-system path (if applicable).

Assuming skin_path is file-system path passed to the WSGI application constructor as a configuration option and app is the Router-object, we can use a statement such as:

  app.registry.registerAdapter(
   repoze.bfg.static.static_view_factory(skin_path),
   name='static')

Note that multiple static views are allowed; the library will go through the available views until it finds a mount point that's applicable to serve up a given static resource. We can now serve any static resources in or below the skin path using the ``repoze.bfg.static.get_url`` function.

This integrates with the skins package, but a quick introduction is in order before we continue.

The skins package provides a ZCML-directive to register a directory of "skin templates" (see the PyPi-page for a more thorough description).

  <bfg:templates
   for="..." request_type="..." permission="..."
   directory="templates" />

Skin templates are registered individually as view components. From inside a skin template (which is essentially a page template that gets passed two special symbols), it's easy to include other skin templates. And if the directory where the templates is located, lies within a mount point to serve static resources, we can link to resources local to the template like so:

  <img src="${api.static.url('logo.png')}" />

This can also be used to link to stylesheets and javascript. This way, using just these two packages, one could create the frontend for a simple web application, complete with images.