Author: David Glick, Plone Foundation



``plone.resource`` publishes directories of static files via the ZPublisher.
These directories may be located either in the ZODB (as OFS folders and
files), or on the filesystem.

Each resource directory has a type and a name. When combined, these are used
to traverse to the resource directory. For example::


Where resources can be stored

Resource directory contents can be found by the traverser in several different
places. The following locations are tried in order.

Files in the ZODB

  Installing ``plone.resource`` creates a folder called portal_resources which
  can be used to store resource directories persistently. By convention, the
  top-level folders under this folder correspond to resource types, and 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

  (XXX: provide a helper to upload a tarball/zip)

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". It would be accessible at


  .. 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::


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

Minimum zcml config example

      <configure xmlns:plone="">
      <include package="plone.resource" file="meta.zcml"/>


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 the in-ZODB resources directory in
    that top-level directories are resource types, and 2nd-level directories
    are resource directory names.  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`` would register the given path
    within the buildout root::


    Typically, this can be injected into ``site.zcml`` by specifying the
    ``resources option`` in the `plone.recipe.zope2instance`_
    buildout recipe, like this::

      resources = ${buildout:directory}/resources

    As a worked example, if one wanted to serve resources for use with
    ````, which provides the ``++theme++`` traverser, then
    a resource located at::


    would be traversable at a URL like so::


.. _`plone.recipe.zope2instance`:

Additional traversers

    Traversers can be registered via ZCML using an adapter like so::