Overview

This package provides an implementation of browser resources. It also provides directives for defining those resources using ZCML.

Resources are static files and directories that are served to the browser directly from the filesystem. The most common example are images, CSS style sheets, or JavaScript files.

Resources are be registered under a symbolic name and can later be referred to by that name, so their usage is independent from their physical location.

Registering Resources

You can register a single file with the <browser:resource> directive, and a whole directory with the <browser:resourceDirectory> directive, for example:

<browser:resource
  file="/path/to/static.file"
  name="myfile"
  />

<browser:resourceDirectory
  directory="/path/to/images"
  name="main-images"
  />

This causes a named default adapter to be registered that adapts the request to zope.interface.Interface so to later retrieve a resource, use zope.component.getAdapter(request, name='myfile').

Note

The default adapter (the one that adapts to zope.interface.Interface) is used to reduce coupling between projects, specifically between this project and zope.traversing.namespace.

Internationalization

Resources can also be internationalized, which means that a single resource name can refer to any one of a number of files that are specific to different languages. When the resource is retrieved and served, the file that corresponds to the request’s language is automatically sent:

<browser:i18n-resource
  name="myfile"
  defaultLanguage="en">
  <browser:translation
    language="en"
    file="path/to/static.file"
    />
  <browser:translation
    language="de"
    file="path/to/static.file.de"
    />
</browser:i18n-resource>

Using Resources

There are two ways to traverse to a resource:

  1. with the ‘empty’ view on a site, e. g. http://localhost/@@/myfile (This is declared by zope.browserresource’s configure.zcml to be Resources.)
  2. with the ++resource++ namespace, e. g. http://localhost/++resource++myfile (This is declared by zope.traversing.namespace)

In case of resource-directories traversal simply continues through its contents, e. g. http://localhost/@@/main-images/subdir/sample.jpg

Rather than putting together the URL to a resource manually, you should use zope.traversing.browser.interfaces.IAbsoluteURL to get the URL, or for a shorthand, call the resource object. This has an additional benefit:

If you want to serve resources from a different URL, for example because you want to use a web server specialized in serving static files instead of the appserver, you can register an IAbsoluteURL adapter for the site under the name resource that will be used to compute the base URLs for resources. (See AbsoluteURL for the implementation.)

For example, if you register http://static.example.com/ as the base resource URL, the resources from the above example would yield the following absolute URLs: http://static.example.com/@@/myfile and http://static.example.com/@@/main-images.