Metadata-Version: 1.0
Name: plone.resource
Version: 1.0b4
Summary: UNKNOWN
Home-page: https://svn.plone.org/svn/plone/plone.resource
Author: UNKNOWN
Author-email: UNKNOWN
License: GPL
Description: Introduction
        ============
        
        ``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::
        
        /++theme++mytheme/<subpath>
        /++sitelayout++mylayout/<subpath>
        /++templatelayout++mylayout<subpath>
        
        
        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
        ++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, as it could
        allow unwanted file access.
        
        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 should have the
        same subdirectory structure as the in-ZODB resources directory (i.e.,
        top-level directories are resource types and 2nd-level directories are
        resource directory names).
        
        For example, the following in site.zcml would register the path
        var/resources within the buildout root::
        
        <plone:static
        directory="/path/to/buildout/var/resources"
        />
        
        Typically, this could be injected into site.zcml by specifying the
        zcml-additional option in the `plone.recipe.zope2instance`_
        buildout recipe, like this::
        
        zcml-additional =
        <configure xmlns="http://namespaces.zope.org/zope"
        xmlns:plone="http://namespaces.plone.org/plone">
        <plone:static directory="${buildout:directory}/resources" />
        </configure>
        
        
        
        .. _`plone.recipe.zope2instance`: http://pypi.python.org/pypi/plone.recipe.zope2instance
        
        
        What types of resources can be stored
        -------------------------------------
        
        
        Changelog
        =========
        
        1.0b4 (2011-05-29)
        ------------------
        
        - Add queryResourceDirectory() helper method.
        [optilude]
        
        1.0b3 (2011-05-23)
        ------------------
        
        - Fix resource directory download bug with subdirectories.
        [elro]
        
        1.0b2 (2011-05-16)
        ------------------
        
        - Add a more compatible filestream iterator for filesystem files that allows
        coercion to string or unicode. This fixes possible compatibility issues
        with resource merging through Resource Registries.
        [optilude]
        
        1.0b1 (2011-04-22)
        ------------------
        
        - Initial release
        
Platform: UNKNOWN
Classifier: Framework :: Plone
Classifier: Programming Language :: Python
