The flexible skinning solution

This package provides an extension to the Pyramid framework for integrating code with templates and resources – what’s known as the application skin.

You can use the package in a variety of ways. It’s designed to be immediately useful for most applications and flexible enough to scale to complex use-cases.

Some examples:

  • Make it easy for users of your package to override one or more included resources.
  • Provide flexibility for your site’s content section by using HTML templates instead of static HTML.
  • Use custom templates or resources for a particular subset of pages.
  • Use automatic discovery to integrate with external applications [1].

Integration is available for templates, routes and views.

First look

Skin objects live in a global namespace. You can organize the space using directory nesting and/or request types.

The following example illustrates the mapping from the file system to the skin object space (where ./ corresponds to some package path):

./skins/index.pt          =>  "index"
./skins/images/logo.png   =>  "images/logo.png"

       ↳ mount point

The mount point constitutes a skin directory. You can register as many skin directories as you need. The files found under each directory will be entered into the global skin object space. In this way, new registrations can override previous ones.

Note in the example that index.pt appears without its file extension. This is a behavior of the skin factory for template files (with the .pt extension).

Here’s how you would configure this using Pyramid’s imperative configurator:

from pyramid.config import Configurator
config = Configurator()

import pyramid_skins
config.include(pyramid_skins)
config.register_path("pyramid_skins:tests/skins")

If you’re instead using the pyramid_zcml extension to configure your application using ZCML, this is supported through the skins directive. We come back to this in much more detail, but here’s how you would register the same skin directory using ZCML:

<configure xmlns="http://pylonshq.com/pyramid">
  <include package="pyramid_skins" />
  <skins path="tests/skins" />
</configure>

That’s it! This is all you need to start using skin objects in Python code. The index name now maps to the ./skins/index.pt file on disk:

from pyramid_skins import SkinObject
index = SkinObject("index")

This is a callable; it renders the template and returns an HTTP response object. If you provide keyword arguments, they will be passed into the template. Note that for skin templates (like "index"), the optional first two positional arguments are mapped to context and request.

Support and development

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 #pyramid channel on Freenode IRC or write to the pylons mailinglist.

The package has 100% test coverage. This documentation itself is tested using the manuel library which works with the standard testrunner. You can run all tests from the command-line using:

$ python setup.py test

This allows you to make sure the package is compatible with your platform.

Indices and tables

[1]Available on Mac OS 10.5+ (requires MacFSEvents library) and Linux 2.6.13+ with Libc >= 2.4 (requires pyinotify library)

Table Of Contents

Next topic

Registration

This Page