Metadata-Version: 1.1
Name: plone.resource
Version: 1.0.3
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.
        
        Minimum zcml config example
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^
            Note::
        
              <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 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::
        
              <plone:static
                directory="/path/to/buildout/var/resources"
                />
        
            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
            ``plone.app.theming``, which provides the ``++theme++`` traverser, then
            a resource located at::
        
                ${directory}/resources/theme/my.project/logo.png
        
            would be traversable at a URL like so::
        
                http://localhost:8080/Plone/++theme++my.project/logo.png
        
        .. _`plone.recipe.zope2instance`: http://pypi.python.org/pypi/plone.recipe.zope2instance
        
        Additional traversers
        ---------------------
        
            Traversers can be registered via ZCML using an adapter like so::
        
             <adapter
               name="demo"
               for="* zope.publisher.interfaces.IRequest"
               provides="zope.traversing.interfaces.ITraversable"
               factory="my.project.traversal.MyTraverser"
               />
        
            with a corresponding factory definition of::
        
                from plone.resource.traversal import ResourceTraverser
                class MyTraverser(ResourceTraverser):
                    name = 'demo'
        
            This, when coupled with configuration like that in the
            `Files in a central resource directory`_ section above, would mean that
            resources located at::
        
                ${directory}/resources/demo/my.project/logo.png
        
            would be traversable at a URL like so::
        
                http://localhost:8080/Plone/++demo++my.project/logo.png
        
        What types of resources can be stored
        -------------------------------------
        
        
        Changelog
        =========
        
        1.0.3 (2014-10-13)
        ------------------
        
        - security hardening: we don't want the anonymous user to look at our fs
          [giacomos]
        
        
        1.0.2 (2013-01-01)
        ------------------
        
        - Nothing changed yet.
        
        
        1.0.1 (2012-05-25)
        ------------------
        
        - Make sure text/html files imported as persistent files will be
          served with a utf-8 encoding. This fixes
          https://dev.plone.org/ticket/12838
          [davisagli]
        
        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
