Metadata-Version: 2.1
Name: plone.resource
Version: 2.1.4
Summary: Static files for Plone
Home-page: https://pypi.org/project/plone.resource
Author: David Glick, Plone Foundation
Author-email: davidglick@groundwire.org
License: GPL version 2 or later
Keywords: plone resource
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: 5.2
Classifier: Framework :: Plone :: Core
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Dist: plone.caching
Requires-Dist: python-dateutil
Requires-Dist: setuptools
Requires-Dist: z3c.caching
Requires-Dist: zope.component
Requires-Dist: zope.configuration
Requires-Dist: zope.filerepresentation
Requires-Dist: zope.interface
Requires-Dist: zope.publisher
Requires-Dist: zope.schema
Requires-Dist: zope.traversing
Requires-Dist: Zope2
Requires-Dist: six
Provides-Extra: test
Requires-Dist: plone.app.testing ; extra == 'test'

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 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``

.. TODO (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" 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

.. _`plone.recipe.zope2instance`: http://pypi.python.org/pypi/plone.recipe.zope2instance

Additional traversers
---------------------

Custom 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 simple 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::

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

would be traversable at a URL like so::

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

.. TODO: What types of resources can be stored


Changelog
=========

.. You should *NOT* be adding new change log entries to this file.
   You should create a file in the news directory instead.
   For helpful instructions, please see:
   https://github.com/plone/plone.releaser/blob/master/ADD-A-NEWS-ITEM.rst

.. towncrier release notes start

2.1.4 (2021-06-14)
------------------

Bug fixes:


- Do not throw an error when traversing to a FilesystemResourceDirectory (#31)


2.1.3 (2020-09-28)
------------------

Bug fixes:


- Fixed various warnings.
  [maurits] (#3130)


2.1.2 (2020-04-22)
------------------

Bug fixes:


- Minor packaging updates. (#1)


2.1.1 (2019-02-08)
------------------

Bug fixes:


- Fix deprecation and resource warnings. [gforcada] (#29)


2.1.0 (2018-11-02)
------------------

Bug fixes:

- Fix tests in py3.
  [pbauer, jensens]

- Change name of IResourceDirectoryDirective to TextLine to work with zope.configuration >= 4.2.
  See https://github.com/plone/Products.CMFPlone/issues/2591
  [pbauer]

2.0.2 (2018-06-04)
------------------

Bug fixes:

- More Python 3 fixes.
  [ale, pbauer]


2.0.1 (2018-02-05)
------------------

New features:

- Add python 2 / 3 compatibility


2.0.0 (2018-01-17)
------------------

Breaking changes:

- Remove Python2.6 support.
  [ale-rt]

Bug fixes:

- Fixed 'ValueError: substring not found' in ``FilesystemResourceDirectory`` representation.
  This happens when you register a directory with a name that differs from the directory name.
  Visiting the ``/++theme++myname`` url would then give this error.
  We also avoid listing a longer part of the path in case the directory name happens to be in the path multiple times.
  [maurits]


1.2.1 (2016-12-30)
------------------

Bug fixes:

- 'unittest2' is a test dependency, make this explicit in setup.py.
  [jensens]


1.2 (2016-11-09)
----------------

New features:

- Fire events on resources creation/modification
  [jpgimenez, ebrehault]


1.1 (2016-10-04)
----------------

New features:

- Use ``mimetypes_registry`` utility to dertermine mimetype if available.
  [jensens]

Bug fixes:

- Remove duplicte import
  [jensens]

- Add coding headers on python files.
  [gforcada]

1.0.7 (2016-09-08)
------------------

Bug fixes:

- Applied 20160830 security hotfix.  [maurits]


1.0.6 (2016-08-10)
------------------

Fixes:

- Do not leave an ``.svn`` file behind when running the tests.  [maurits]

- Use zope.interface decorator.
  [gforcada]


1.0.5 (2016-02-26)
------------------

Fixes:

- Test fix: ``clearZCML`` was removed from ``zope.component.tests``.
  [thet]

- Cleanup: PEP8, plone-coding conventions, ReST fixes, documentation
  overhaul, et al.
  [jensens]


1.0.4 (2015-03-21)
------------------

- use utf-8 encoding when writing more than just text/html
  [vangheem]

- provides a proper __contains__ method in FilesystemResourceDirectory
  [ebrehault]


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


