plone.resource 1.1

Files in the ZODB

Installing plone.resource creates a Zope-folder called portal_resources. It can be used to store resource directories persistently. By convention:

• the top-level folders under this folder correspond to resource types,

• the second-level folders correspond to the resource directory name.

So, the file traversable at /++theme++mytheme/myfile could be physically located at some_site/++etc++site/resources/theme/mytheme

Files in Python distributions

A folder in a Python distribution (e.g. egg) can be registered as a resource directory of a particular type and name using the plone:static ZCML directive. For example, this registers a directory named “theme” as a resource directory of type “theme” under the name “mytheme”. It would be accessible at ++theme++mytheme:

  <plone:static
      directory="theme"
      type="theme"
      name="mytheme"
  />

.. note::
   You must do ``<include package="plone.resource" file="meta.zcml"/>``
   before you can use the plone:static directive.

The name of the resource directory defaults to the name of the package, so can be omitted. E.g. the following directive in a package named “mytheme” would result in the same registration as above:

<plone:static
    directory="resources"
    type="theme"
/>

Traversing upward in directory paths using .. is not supported for security reasons, as it could allow unwanted file access.

Minimum zcml config example

<configure xmlns:plone="http://namespaces.plone.org/plone">
  <include package="plone.resource" file="meta.zcml"/>
  <plone:static
      directory="resources"
      type="theme"
      name="myproject"
    />
</configure>

..

Files in a central resource directory

If the plone:static directive is used from site.zcml (i.e., with no active package in the ZCML import context), then it may specify the absolute path to a top-level resources directory.

This directory should have the same sub-directory structure as explained above (in-ZODB resources directory):

• the top-level folders under this folder correspond to resource types,

• the second-level folders correspond to the resource directory name.

In addition, in order for resources to be available, the top-level directories require a traverser to be registered!

For example, the following in site.zcml registers the given path within the buildout root:

<plone:static
    directory="/path/to/buildout/resources"
/>

In order to automate this at buildout time, plone.recipe.zope2instance recipe has the option resources. It injects the above zcml snippet with into site.zcml by specifying the option like this:

[instance]
...
resources = ${buildout:directory}/resources
...

Example: Using plone.app.theming - which provides the ++theme++ traverser - given an image file located in filesystem at:

${buildout:directory}/resources/theme/my.project/logo.png``

This would be traversable at a URL like so:

http://localhost:8080/Plone/++theme++my.project/logo.png