PyPI - plone.tiles - Versions diffs - 3.0.0__py3-none-any.whl - Mend

plone.tiles 3.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

plone/tiles/__init__.py +7 -0
plone/tiles/absoluteurl.py +101 -0
plone/tiles/configure.zcml +184 -0
plone/tiles/data.py +422 -0
plone/tiles/data.rst +179 -0
plone/tiles/directives.py +13 -0
plone/tiles/directives.rst +221 -0
plone/tiles/esi.py +214 -0
plone/tiles/esi.rst +325 -0
plone/tiles/fieldtypeconverters.py +39 -0
plone/tiles/interfaces.py +172 -0
plone/tiles/meta.py +162 -0
plone/tiles/meta.zcml +16 -0
plone/tiles/test.pt +1 -0
plone/tiles/testing.py +59 -0
plone/tiles/tests/__init__.py +0 -0
plone/tiles/tests/test_data.py +83 -0
plone/tiles/tests/test_doctests.py +30 -0
plone/tiles/tile.py +186 -0
plone/tiles/tiles.rst +783 -0
plone/tiles/type.py +39 -0
plone.tiles-3.0.0-py3.13-nspkg.pth +1 -0
plone_tiles-3.0.0.dist-info/LICENSE.GPL +339 -0
plone_tiles-3.0.0.dist-info/LICENSE.txt +16 -0
plone_tiles-3.0.0.dist-info/METADATA +1990 -0
plone_tiles-3.0.0.dist-info/RECORD +29 -0
plone_tiles-3.0.0.dist-info/WHEEL +5 -0
plone_tiles-3.0.0.dist-info/namespace_packages.txt +1 -0
plone_tiles-3.0.0.dist-info/top_level.txt +1 -0

plone/tiles/esi.rst ADDED Viewed

@@ -0,0 +1,325 @@
+ESI support
+===========
+Some sites may choose to render tiles in a delayed fashion using Edge Side Includes or some similar mechanism.
+``plone.tiles`` includes some support to help render ESI placeholders.
+This is used in ``plone.app.blocks`` to facilitate ESI rendering.
+Since ESI normally involves a "dumb" replacement operation,
+``plone.tiles`` also provides a means of accessing just the head and/or just the body of a tile.
+To use the package, you should first load its ZCML configuration.
+.. code-block:: python
+    >>> configuration = """\
+    ... <configure
+    ...      xmlns="http://namespaces.zope.org/zope"
+    ...      xmlns:plone="http://namespaces.plone.org/plone"
+    ...      i18n_domain="plone.tiles.tests">
+    ...
+    ...     <include package="zope.component" file="meta.zcml" />
+    ...     <include package="zope.browserpage" file="meta.zcml" />
+    ...
+    ...     <include package="plone.tiles" file="meta.zcml" />
+    ...     <include package="plone.tiles" />
+    ...
+    ... </configure>
+    ... """
+    >>> from io import StringIO
+    >>> from zope.configuration import xmlconfig
+    >>> xmlconfig.xmlconfig(StringIO(configuration))
+Marking a tile as ESI-rendered
+------------------------------
+For ESI rendering to be available, the tile must be marked with the ``IESIRendered`` marker interface.
+We can create a dummy tile with this interface like so:
+.. code-block:: python
+    >>> from zope.interface import implementer
+    >>> from plone.tiles.interfaces import IESIRendered
+    >>> from plone.tiles import Tile
+    >>> @implementer(IESIRendered)
+    ... class SampleTile(Tile):
+    ...
+    ...     __name__ = 'sample.tile' # would normally be set by ZCML handler
+    ...
+    ...     def __call__(self):
+    ...         return '<html><head><title>Title</title></head><body><b>My tile</b></body></html>'
+Above, we have created a simple HTML string.
+This would normally be rendered using a page template.
+We'll register this tile manually here.
+Ordinarily, of course, it would be registered via ZCML.
+.. code-block:: python
+    >>> from plone.tiles.type import TileType
+    >>> from zope.security.permission import Permission
+    >>> permission = Permission('dummy.Permission')
+    >>> sampleTileType = TileType(
+    ...     name=u'sample.tile',
+    ...     title=u'Sample tile',
+    ...     description=u'A tile used for testing',
+    ...     add_permission='dummy.Permission',
+    ...     view_permission='dummy.Permission',
+    ...     schema=None)
+    >>> from zope.component import provideAdapter, provideUtility
+    >>> from zope.interface import Interface
+    >>> from plone.tiles.interfaces import IBasicTile
+    >>> provideUtility(permission, name=u'dummy.Permission')
+    >>> provideUtility(sampleTileType, name=u'sample.tile')
+    >>> provideAdapter(SampleTile, (Interface, Interface), IBasicTile, name=u'sample.tile')
+ESI lookup
+----------
+When a page is rendered
+(for example by a system like ``plone.app.blocks``, but see below),
+a tile placeholder may be replaced by a link such as:
+.. code-block:: xml
+    <esi:include src="/path/to/context/@@sample.tile/tile1/@@esi-body" />
+When this is resolved, it will return the body part of the tile.
+Equally, a tile in the head can be replaced by:
+.. code-block:: xml
+    <esi:include src="/path/to/context/@@sample.tile/tile1/@@esi-head" />
+To illustrate how this works,
+let's create a sample context,
+look up the view as it would be during traversal,
+and instantiate the tile,
+before looking up the ESI views and rendering them.
+.. code-block:: python
+    >>> from zope.interface import implementer
+    >>> from zope.publisher.browser import TestRequest
+    >>> class IContext(Interface):
+    ...     pass
+    >>> @implementer(IContext)
+    ... class Context(object):
+    ...     pass
+    >>> class IntegratedTestRequest(TestRequest):
+    ...     @property
+    ...     def environ(self):
+    ...         return self._environ
+    >>> context = Context()
+    >>> request = IntegratedTestRequest()
+The following simulates traversal to ``context/@@sample.tile/tile1``
+.. code-block:: python
+    >>> from zope.interface import Interface
+    >>> from zope.component import getMultiAdapter
+    >>> tile = getMultiAdapter((context, request), name=u'sample.tile')
+    >>> tile = tile['tile1'] # simulates sub-path traversal
+This tile should be ESI rendered:
+.. code-block:: python
+    >>> IESIRendered.providedBy(tile)
+    True
+At this point, we can look up the ESI views:
+.. code-block:: python
+    >>> head = getMultiAdapter((tile, request), name='esi-head')
+    >>> head()
+    Traceback (most recent call last):
+    ...
+    zExceptions.unauthorized.Unauthorized: Unauthorized()
+But we can only render them when we have the required permissions:
+    >>> from AccessControl.SecurityManagement import newSecurityManager
+    >>> from AccessControl.User import Super
+    >>> newSecurityManager(None, Super('manager', '', ['Manager'], []))
+    >>> print(head())
+    <title>Title</title>
+    >>> body = getMultiAdapter((tile, request), name='esi-body')
+    >>> print(body())
+    <b>My tile</b>
+Tiles without heads or bodies
+-----------------------------
+In general, tiles are supposed to return full HTML documents.
+The ``esi-head`` and ``esi-body`` views are tolerant of tiles that do not.
+If they cannot find a ``<head />`` or ``<body />`` element, respectively, they will return the underlying tile output unaltered.
+For example:
+.. code-block:: python
+    >>> from plone.tiles.esi import ESITile
+    >>> class LazyTile(ESITile):
+    ...     __name__ = 'sample.esi1' # would normally be set by ZCML handler
+    ...     def __call__(self):
+    ...         return '<title>Page title</title>'
+We won't bother to register this for this test, instead just instantiating it directly:
+.. code-block:: python
+    >>> tile = LazyTile(context, request)['tile1']
+    >>> IESIRendered.providedBy(tile)
+    True
+    >>> head = getMultiAdapter((tile, request), name='esi-head')
+    >>> print(head())
+    <title>Page title</title>
+Of course, the ESI body renderer would return the same thing,
+since it can't extract a specific body either:
+.. code-block:: python
+    >>> body = getMultiAdapter((tile, request), name='esi-body')
+    >>> print(body())
+    <title>Page title</title>
+In this case, we would likely end up with invalid HTML,
+since the ``<title />`` tag is not allowed in the body.
+Whether and how to resolve this is left up to the ESI interpolation implementation.
+Convenience classes and placeholder rendering
+---------------------------------------------
+Two convenience base classes can be found in the ``plone.tiles.esi`` module.
+These extend the standard ``Tile`` and ``PersistentTile`` classes to provide the ``IESIRendered`` interface.
+* ``plone.tiles.esi.ESITile``, a transient, ESI-rendered tile
+* ``plone.tiles.esi.ESIPersistentTile``, a persistent, ESI-rendered tile
+These are particularly useful if you are creating a template-only tile and want ESI rendering.
+For example:
+.. code-block:: xml
+    <plone:tile
+        name="sample.esitile"
+        title="An ESI-rendered tile"
+        add_permission="plone.tiles.tests.DummyAdd"
+        template="esitile.pt"
+        class="plone.tiles.esi.ESITile"
+        for="*"
+        permission="zope.View"
+        />
+Additionally,
+these base classes implement a ``__call__()`` method that will render a tile placeholder,
+if the request contains an ``X-ESI-Enabled`` header set to the literal 'true'.
+The placeholder is a simple HTML ``<a />`` tag,
+which can be transformed into an ``<esi:include />`` tag using the helper function ``substituteESILinks()``.
+The reason for this indirection is that the ``esi`` namespace is not allowed in HTML documents,
+and are liable to be stripped out by transforms using the ``libxml2`` / ``lxml`` HTML parser.
+Let us now create a simple ESI tile. To benefit from the default rendering,
+we should implement the ``render()`` method instead of ``__call__()``. Setting
+a page template as the ``index`` class variable or using the ``template``
+attribute to the ZCML directive will work also.
+.. code-block:: python
+    >>> from plone.tiles.esi import ESITile
+    >>> class SampleESITile(ESITile):
+    ...     __name__ = 'sample.esitile' # would normally be set by ZCML handler
+    ...
+    ...     def render(self):
+    ...         return '<html><head><title>Title</title></head><body><b>My ESI tile</b></body></html>'
+    >>> sampleESITileType = TileType(
+    ...     name=u'sample.esitile',
+    ...     title=u'Sample ESI tile',
+    ...     description=u'A tile used for testing ESI',
+    ...     add_permission='dummy.Permission',
+    ...     view_permission='dummy.Permission',
+    ...     schema=None)
+    >>> provideUtility(sampleESITileType, name=u'sample.esitile')
+    >>> provideAdapter(SampleESITile, (Interface, Interface), IBasicTile, name=u'sample.esitile')
+The following simulates traversal to ``context/@@sample.esitile/tile1``
+.. code-block:: python
+    >>> tile = getMultiAdapter((context, request), name=u'sample.esitile')
+    >>> tile = tile['tile1'] # simulates sub-path traversal
+By default, the tile renders as normal:
+.. code-block:: python
+    >>> print(tile())
+    <html><head><title>Title</title></head><body><b>My ESI tile</b></body></html>
+However, if we opt into ESI rendering via a request header, we get a different view:
+.. code-block:: python
+    >>> from plone.tiles.interfaces import ESI_HEADER_KEY
+    >>> request.environ[ESI_HEADER_KEY] = 'true'
+    >>> print(tile()) # doctest: +NORMALIZE_WHITESPACE
+    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+    <html xmlns="http://www.w3.org/1999/xhtml">
+        <body>
+            <a class="_esi_placeholder"
+               rel="esi"
+               href="http://127.0.0.1/@@esi-body?"></a>
+        </body>
+    </html>
+This can be transformed into a proper ESI tag with ``substituteESILinks()``:
+.. code-block:: python
+    >>> from plone.tiles.esi import substituteESILinks
+    >>> print(substituteESILinks(tile())) # doctest: +NORMALIZE_WHITESPACE
+    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+    <html xmlns:esi="http://www.edge-delivery.org/esi/1.0" xmlns="http://www.w3.org/1999/xhtml">
+        <body>
+            <esi:include src="http://127.0.0.1/@@esi-body?" />
+        </body>
+    </html>
+It is also possible to render the ESI tile for the head.
+This is done with a class variable 'head'
+(which would of course normally be set within the class):
+.. code-block:: python
+    >>> SampleESITile.head = True
+    >>> print(tile()) # doctest: +NORMALIZE_WHITESPACE
+    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+    <html xmlns="http://www.w3.org/1999/xhtml">
+        <body>
+            <a class="_esi_placeholder"
+               rel="esi"
+               href="http://127.0.0.1/@@esi-head?"></a>
+        </body>
+    </html>

plone/tiles/fieldtypeconverters.py ADDED Viewed

@@ -0,0 +1,39 @@
+from plone.tiles.interfaces import IFieldTypeConverter
+from zope.interface import implementer
+@implementer(IFieldTypeConverter)
+class NoConverter:
+    def __init__(self, field):
+        self.field = field
+    token = None
+class TextConverter(NoConverter):
+    token = "text"
+class LongConverter(NoConverter):
+    token = "long"
+class FloatConverter(NoConverter):
+    token = "float"
+class BoolConverter(NoConverter):
+    token = "boolean"
+class TupleConverter(NoConverter):
+    token = "tuple"
+class ListConverter(NoConverter):
+    token = "list"
+class DictConverter(NoConverter):
+    token = "record"

plone/tiles/interfaces.py ADDED Viewed

@@ -0,0 +1,172 @@
+from zope.interface import Interface
+from zope.interface.common.mapping import IMapping
+from zope.interface.interfaces import IInterface
+from zope.publisher.interfaces.browser import IBrowserView
+import zope.schema
+ESI_HEADER = "X-ESI-Enabled"
+ESI_HEADER_KEY = "HTTP_" + ESI_HEADER.replace("-", "_").upper()
+class ITileType(Interface):
+    """A utility that describes a type of tile"""
+    __name__ = zope.schema.DottedName(title="Tile name (same as utility name)")
+    title = zope.schema.TextLine(title="Title")
+    description = zope.schema.Text(title="Description", required=False)
+    icon = zope.schema.Text(title="Icon", required=False)
+    add_permission = zope.schema.Id(title="Zope 3 IPermission utility name")
+    schema = zope.schema.Object(
+        title="Tile schema",
+        description="Describes configurable data for this tile and allows a "
+        "form to be rendered to edit it. Set to None if the tile "
+        "has no configurable schema",
+        schema=IInterface,
+        required=False,
+    )
+class IBasicTile(IBrowserView):
+    """A tile is a publishable resource that can be inserted into a site or
+    page layout.
+    The tile should be a named multi adapter on (<context>, <layer>)
+    providing IBasicTile.
+    It will normally be traversed to like this::
+        http://localhost:8080/plone-site/object/@@my.tile/tile1
+    In this case:
+    * The tile context is the content object at /plone-site/object.
+    * The ``__name__`` of the tile instance is 'my.tile'
+    * The ``id`` of the tile instance is 'tile1'
+    * The ``url`` of the tile instance is the URL as above
+    """
+    __name__ = zope.schema.DottedName(
+        title="The name of the type of this tile",
+        description="This should be a dotted name prefixed with the "
+        "package that defined the tile",
+    )
+    id = zope.schema.DottedName(
+        title="Tile instance id",
+        description="The id is normally set using sub-path traversal"
+        "A given tile type may be used multiple times on "
+        "the same page, each with a unique id. The id must "
+        "be unique even across multiple layouts for the "
+        "same context.",
+    )
+class ITile(IBasicTile):
+    """A tile with some data (probably from a query string)."""
+    data = zope.schema.Dict(
+        title="The tile's configuration data",
+        description="This attribute cannot be set, but the dictionary may "
+        "be updated",
+        key_type=zope.schema.Id(title="The data element name"),
+        value_type=zope.schema.Field(title="The value"),
+        required=True,
+        readonly=True,
+        default={},
+    )
+    url = zope.schema.URI(
+        title="Tile URL",
+        description="This is the canonical URL for the tile. In the "
+        "case of transient tiles with data, this may "
+        "include a query string with parameters. Provided "
+        "that the `id` attribute is set, it will also "
+        "include a sub-path with this in it.",
+    )
+class IPersistentTile(ITile):
+    """A tile with full-blown persistent data (stored in annotations)."""
+class IESIRendered(Interface):
+    """Marker interface for tiles which are to be rendered via ESI.
+    Two corresponding views, @@esi-body and @@esi-head, will be made available
+    on the tile itself. This will return the children of the <head /> or
+    <body /> of the tile, respectively.
+    Thus, a tile marked with this interface may be replaced with an ESI
+    instruction like::
+        <esi:include src="./@@my.tile/tile-id/@@esi-body" />
+    When fetched, this placeholder will be replaced by the body of the tile.
+    """
+class ITileDataManager(Interface):
+    """Support for getting and setting tile data dicts.
+    This is an adapter on a tile. The tile's id must be set.
+    """
+    def get():
+        """Get a dictionary with tile data for this tile. The dictionary is
+        disconnected from the underlying storage.
+        """
+    def set(data):
+        """Persist the given data dict."""
+    def delete():
+        """Delete the data record for this tile."""
+class ITileDataContext(Interface):
+    """Indirection to help determine where persistent tiles store their data.
+    This is a multi-adapter on ``(context, request, tile)``. The context and
+    request are the same as ``tile.context`` and ``tile.request``, but these
+    discriminators allow the data context to be customised depending on
+    the context or request.
+    The default implementation simply returns ``tile.context``. That must
+    be annotatable for the default tile data storage adapter and
+    persistent tile ``ITileDataManager`` to work.
+    """
+class ITileDataStorage(IMapping):
+    """Indirection to help determine how persistent tiles store their data.
+    This is a multi-adapter on ``(context, request, tile)``. The context and
+    request are the same as ``tile.context`` and ``tile.request``, but these
+    discriminators allow the data context to be customised depending on
+    the context or request.
+    The default implementation simply returns the configured zope.annotation
+    storage for the given context.
+    The adapter is expected to provide IMapping interface and be accessed
+    by tile data managers similarly to zope.annotation storage.
+    """
+class IFieldTypeConverter(Interface):
+    """Field type converter for querystring parameters for Zope."""
+    token = zope.schema.TextLine(
+        title="Token",
+        description="""
+                                 String parameter appended to the field id
+                                 for the Zope Publisher to cast it.
+                                 """,
+    )

plone/tiles/meta.py ADDED Viewed

@@ -0,0 +1,162 @@
+from plone.tiles.interfaces import ITileType
+from plone.tiles.tile import Tile
+from plone.tiles.type import TileType
+from Products.Five.browser.metaconfigure import page
+from zope import schema
+from zope.component.zcml import utility
+from zope.configuration.exceptions import ConfigurationError
+from zope.configuration.fields import GlobalInterface
+from zope.configuration.fields import GlobalObject
+from zope.configuration.fields import MessageID
+from zope.configuration.fields import Path
+from zope.interface import Interface
+from zope.publisher.interfaces.browser import IDefaultBrowserLayer
+from zope.security.zcml import Permission
+class ITileDirective(Interface):
+    """Directive which registers a new type of tile"""
+    name = schema.DottedName(
+        title="Name",
+        description="A unique, dotted name for the tile",
+        required=True,
+    )
+    title = MessageID(
+        title="Title",
+        description="A user friendly title, used when configuring the tile",
+        required=False,
+    )
+    description = MessageID(
+        title="Description",
+        description="A longer summary of the tile's purpose and function",
+        required=False,
+    )
+    icon = MessageID(
+        title="Icon",
+        description="Image that represents tile purpose and function",
+        required=False,
+    )
+    add_permission = Permission(
+        title="Add permission",
+        description="Name of the permission required to instantiate " "this tile",
+        required=False,
+    )
+    edit_permission = Permission(
+        title="Edit permission",
+        description="Name of the permission required to edit this tile",
+        required=False,
+    )
+    delete_permission = Permission(
+        title="Delete permission",
+        description="Name of the permission required to delete this tile",
+        required=False,
+    )
+    schema = GlobalInterface(
+        title="Configuration schema for the tile",
+        description="This is used to create standard add/edit forms",
+        required=False,
+    )
+    for_ = GlobalObject(
+        title="The interface or class this tile is available for",
+        required=False,
+    )
+    layer = GlobalInterface(title="The layer the tile is available for", required=False)
+    class_ = GlobalObject(
+        title="Class", description="Class implementing this tile", required=False
+    )
+    template = Path(
+        title="The name of a template that renders this tile",
+        description="Refers to a file containing a page template",
+        required=False,
+    )
+    permission = Permission(
+        title="View permission",
+        description="Name of the permission required to view this item",
+        required=True,
+    )
+def tile(
+    _context,
+    name,
+    title=None,
+    description=None,
+    icon=None,
+    add_permission=None,
+    edit_permission=None,
+    delete_permission=None,
+    schema=None,
+    for_=None,
+    layer=None,
+    class_=None,
+    template=None,
+    permission=None,
+):
+    """Implements the <plone:tile /> directive"""
+    if (
+        title is not None
+        or description is not None
+        or icon is not None
+        or add_permission is not None
+        or schema is not None
+    ):
+        if title is None or add_permission is None:
+            raise ConfigurationError(
+                "When configuring a new type of tile, 'title' and "
+                "'add_permission' are required"
+            )
+        type_ = TileType(
+            name,
+            title,
+            add_permission,
+            permission,
+            edit_permission=edit_permission,
+            delete_permission=delete_permission,
+            description=description,
+            icon=icon,
+            schema=schema,
+        )
+        utility(_context, provides=ITileType, component=type_, name=name)
+    if (
+        for_ is not None
+        or layer is not None
+        or class_ is not None
+        or template is not None
+    ):
+        if class_ is None and template is None:
+            raise ConfigurationError(
+                "'class' or 'template' must be given when configuring a tile."
+            )
+        if for_ is None:
+            for_ = Interface
+        if layer is None:
+            layer = IDefaultBrowserLayer
+        if class_ is None:
+            class_ = Tile
+        page(
+            _context,
+            name=name,
+            permission=permission,
+            for_=for_,
+            layer=layer,
+            template=template,
+            class_=class_,
+        )