Metadata-Version: 1.0
Name: plone.resource
Version: 1.0
Summary: UNKNOWN
Home-page: https://svn.plone.org/svn/plone/plone.resource
Author: David Glick, Plone Foundation
Author-email: davidglick@groundwire.org
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 
            resources option in the `plone.recipe.zope2instance`_
            buildout recipe, like this::
        
              resources = ${buildout:directory}/resources
        
        .. _`plone.recipe.zope2instance`: http://pypi.python.org/pypi/plone.recipe.zope2instance
         
        
        What types of resources can be stored
        -------------------------------------
        
        
        Changelog
        =========
        
        1.0 (2012-04-15)
        ----------------
        
        - Add __setitem__() support for writeable resource directories.
          [optilude]
        
        1.0b6 (2011-11-24)
        ------------------
        
        - Added rename() method for writable resource directories
          [optilude]
        
        - Added cloneResourceDirectory() helper method in the utils module
          [optilude]
        
        - Add a ++unique++ resource traverser for resource directories to cache as
          'plone.stableResource'.
          [elro]
        
        1.0b5 (2011-06-08)
        ------------------
        
        - Ensure any files are skipped in iterDirectoriesOfType.
          [elro]
        
        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
