plone.tiles 3.0.0__py3-none-any.whl

plone/tiles/directives.rst

@@ -0,0 +1,221 @@
+ZCML directive
+==============
+
+A tile is really just a browser view providing ``IBasicTile``
+(or, more commonly, ``ITile`` or ``IPersistentTile``)
+coupled with a named utility providing ``ITileType``.
+The names of the browser view and the tile should match.
+
+To make it easier to register these components,
+this package provides a ``<plone:tile />`` directive that sets up both.
+It supports several use cases:
+
+* Registering a new tile from a class
+* Registering a new tile from a template only
+* Registering a new tile form a class and a template
+* Registering a new tile for an existing tile type (e.g. for a new layer)
+
+To test this,
+we have created a dummy schema and a dummy tile in ``testing.py``,
+and a dummy template in ``test.pt``.
+
+Let's show how these may be used by registering several tiles:
+
+.. code-block:: python
+
+    >>> configuration = """\
+    ... <configure package="plone.tiles"
+    ...      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.security" file="meta.zcml" />
+    ...     <include package="zope.browserpage" file="meta.zcml" />
+    ...
+    ...     <include package="plone.tiles" file="meta.zcml" />
+    ...     <include package="plone.tiles" />
+    ...
+    ...     <permission
+    ...         id="plone.tiles.testing.DummyAdd"
+    ...         title="Dummy add permission"
+    ...         />
+    ...     <permission
+    ...         id="plone.tiles.testing.DummyView"
+    ...         title="Dummy view permission"
+    ...         />
+    ...
+    ...     <!-- A tile configured with all available attributes -->
+    ...     <plone:tile
+    ...         name="dummy1"
+    ...         title="Dummy tile 1"
+    ...         description="This one shows all available options"
+    ...         add_permission="plone.tiles.testing.DummyAdd"
+    ...         schema="plone.tiles.testing.IDummySchema"
+    ...         class="plone.tiles.testing.DummyTileWithTemplate"
+    ...         template="test.pt"
+    ...         for="plone.tiles.testing.IDummyContext"
+    ...         layer="plone.tiles.testing.IDummyLayer"
+    ...         permission="plone.tiles.testing.DummyView"
+    ...         />
+    ...
+    ...     <!-- A class-only tile -->
+    ...     <plone:tile
+    ...         name="dummy2"
+    ...         title="Dummy tile 2"
+    ...         add_permission="plone.tiles.testing.DummyAdd"
+    ...         class="plone.tiles.testing.DummyTile"
+    ...         for="*"
+    ...         permission="plone.tiles.testing.DummyView"
+    ...         />
+    ...
+    ...     <!-- A template-only tile -->
+    ...     <plone:tile
+    ...         name="dummy3"
+    ...         title="Dummy tile 3"
+    ...         add_permission="plone.tiles.testing.DummyAdd"
+    ...         template="test.pt"
+    ...         for="*"
+    ...         permission="plone.tiles.testing.DummyView"
+    ...         />
+    ...
+    ...     <!-- Use the PersistentTile class directly with a template-only tile -->
+    ...     <plone:tile
+    ...         name="dummy4"
+    ...         title="Dummy tile 4"
+    ...         add_permission="plone.tiles.testing.DummyAdd"
+    ...         schema="plone.tiles.testing.IDummySchema"
+    ...         class="plone.tiles.PersistentTile"
+    ...         template="test.pt"
+    ...         for="*"
+    ...         permission="plone.tiles.testing.DummyView"
+    ...         />
+    ...
+    ...     <!-- Override dummy3 for a new layer -->
+    ...     <plone:tile
+    ...         name="dummy3"
+    ...         class="plone.tiles.testing.DummyTile"
+    ...         for="*"
+    ...         layer="plone.tiles.testing.IDummyLayer"
+    ...         permission="plone.tiles.testing.DummyView"
+    ...         />
+    ...
+    ... </configure>
+    ... """
+
+    >>> from io import StringIO
+    >>> from zope.configuration import xmlconfig
+    >>> xmlconfig.xmlconfig(StringIO(configuration))
+
+Let's check how the tiles were registered:
+
+.. code-block:: python
+
+    >>> from zope.component import getUtility
+    >>> from plone.tiles.interfaces import ITileType
+
+    >>> tile1_type = getUtility(ITileType, name=u'dummy1')
+    >>> tile1_type
+    <TileType dummy1 (Dummy tile 1)>
+    >>> tile1_type.description
+    'This one shows all available options'
+
+    >>> tile1_type.add_permission
+    'plone.tiles.testing.DummyAdd'
+
+    >>> tile1_type.view_permission
+    'plone.tiles.testing.DummyView'
+
+    >>> tile1_type.schema
+    <InterfaceClass plone.tiles.testing.IDummySchema>
+
+    >>> tile2_type = getUtility(ITileType, name=u'dummy2')
+    >>> tile2_type
+    <TileType dummy2 (Dummy tile 2)>
+    >>> tile2_type.description is None
+    True
+    >>> tile2_type.add_permission
+    'plone.tiles.testing.DummyAdd'
+    >>> tile2_type.schema is None
+    True
+
+    >>> tile3_type = getUtility(ITileType, name=u'dummy3')
+    >>> tile3_type
+    <TileType dummy3 (Dummy tile 3)>
+    >>> tile3_type.description is None
+    True
+    >>> tile3_type.add_permission
+    'plone.tiles.testing.DummyAdd'
+    >>> tile3_type.schema is None
+    True
+
+    >>> tile4_type = getUtility(ITileType, name=u'dummy4')
+    >>> tile4_type
+    <TileType dummy4 (Dummy tile 4)>
+    >>> tile4_type.description is None
+    True
+    >>> tile4_type.add_permission
+    'plone.tiles.testing.DummyAdd'
+    >>> tile4_type.schema
+    <InterfaceClass plone.tiles.testing.IDummySchema>
+
+Finally, let's check that we can look up the tiles:
+
+.. code-block:: python
+
+    >>> from zope.publisher.browser import TestRequest
+    >>> from zope.interface import implementer, alsoProvides
+
+    >>> from plone.tiles.testing import IDummyContext, IDummyLayer
+
+    >>> @implementer(IDummyContext)
+    ... class Context(object):
+    ...     pass
+
+    >>> context = Context()
+    >>> request = TestRequest()
+    >>> layer_request = TestRequest(skin=IDummyLayer)
+
+    >>> from zope.component import getMultiAdapter
+    >>> from plone.tiles import Tile, PersistentTile
+    >>> from plone.tiles.testing import DummyTile, DummyTileWithTemplate
+
+    >>> tile1 = getMultiAdapter((context, layer_request), name='dummy1')
+    >>> isinstance(tile1, DummyTileWithTemplate)
+    True
+    >>> print(tile1().strip())
+    <b>test!</b>
+    >>> tile1.__name__
+    'dummy1'
+
+    >>> tile2 = getMultiAdapter((context, request), name='dummy2')
+    >>> isinstance(tile2, DummyTile)
+    True
+    >>> print(tile2())
+    dummy
+    >>> tile2.__name__
+    'dummy2'
+
+    >>> tile3 = getMultiAdapter((context, request), name='dummy3')
+    >>> isinstance(tile3, Tile)
+    True
+    >>> print(tile3().strip())
+    <b>test!</b>
+    >>> tile3.__name__
+    'dummy3'
+
+    >>> tile4 = getMultiAdapter((context, request), name='dummy4')
+    >>> isinstance(tile4, PersistentTile)
+    True
+    >>> print(tile4().strip())
+    <b>test!</b>
+    >>> tile4.__name__
+    'dummy4'
+
+    >>> tile3_layer = getMultiAdapter((context, layer_request), name='dummy3')
+    >>> isinstance(tile3_layer, DummyTile)
+    True
+    >>> print(tile3_layer())
+    dummy
+    >>> tile3_layer.__name__
+    'dummy3'

plone/tiles/esi.py

@@ -0,0 +1,214 @@
+from plone.tiles.interfaces import ESI_HEADER
+from plone.tiles.interfaces import ESI_HEADER_KEY
+from plone.tiles.interfaces import IESIRendered
+from plone.tiles.interfaces import ITileType
+from plone.tiles.tile import PersistentTile
+from plone.tiles.tile import Tile
+from Products.Five import BrowserView
+from zExceptions import Unauthorized
+from zope.component import queryUtility
+from zope.interface import implementer
+
+import os
+import re
+import transaction
+
+
+try:
+    from AccessControl.security import checkPermission
+except ImportError:
+    from zope.security import checkPermission
+
+
+X_FRAME_OPTIONS = os.environ.get("PLONE_X_FRAME_OPTIONS", "SAMEORIGIN")
+
+HEAD_CHILDREN = re.compile(r"<head[^>]*>(.*)</head>", re.I | re.S)
+BODY_CHILDREN = re.compile(r"<body[^>]*>(.*)</body>", re.I | re.S)
+
+ESI_NAMESPACE_MAP = {"esi": "http://www.edge-delivery.org/esi/1.0"}
+_ESI_HREF = 'href="{url}/@@{esiMode}?{queryString}"'
+ESI_TEMPLATE = (
+    """\
+<!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" """
+    + _ESI_HREF
+    + """></a>
+    </body>
+</html>
+"""
+)
+
+
+def substituteESILinks(rendered):
+    """Turn ESI links like <a class="_esi_placeholder" rel="esi" href="..." />
+    into <esi:include /> links.
+
+    ``rendered`` should be an HTML string.
+    """
+
+    rendered = re.sub(
+        r"<html", '<html xmlns:esi="{}"'.format(ESI_NAMESPACE_MAP["esi"]), rendered, 1
+    )
+    return re.sub(
+        r'<a class="_esi_placeholder" rel="esi" href="([^"]+)"></a>',
+        r'<esi:include src="\1" />',
+        rendered,
+    )
+
+
+class ConditionalESIRendering:
+    head = False
+
+    def render(self):
+        raise NotImplementedError(
+            "Override render() or set a class variable 'index' to point to "
+            "a view page template file"
+        )
+
+    def __call__(self, *args, **kwargs):
+        if self.request.getHeader(ESI_HEADER, "false").lower() == "true":
+            mode = "esi-body"
+            if self.head:
+                mode = "esi-head"
+            return ESI_TEMPLATE.format(
+                url=(
+                    self.request.get("PATH_INFO")
+                    and self.request.get("PATH_INFO").replace(" ", "%20")
+                    or self.request.getURL()
+                ),
+                queryString=self.request.get("QUERY_STRING", ""),
+                esiMode=mode,
+            )
+        # Do not hide AttributeError inside index()
+        try:
+            self.index
+        except AttributeError:
+            return self.render()
+        return self.index(*args, **kwargs)
+
+
+# Convenience base classes
+
+
+@implementer(IESIRendered)
+class ESITile(ConditionalESIRendering, Tile):
+    """Convenience class for tiles using ESI rendering.
+
+    Set ``head`` to True if this tile renders <head /> content. The
+    default is to render <body /> content.
+    """
+
+    head = False
+
+
+@implementer(IESIRendered)
+class ESIPersistentTile(ConditionalESIRendering, PersistentTile):
+    """Convenience class for tiles using ESI rendering.
+
+    Set ``head`` to True if this tile renders <head /> content. The
+    default is to render <body /> content.
+    """
+
+    head = False
+
+
+# ESI views
+
+
+class ESIHead(BrowserView):
+    """Render the head portion of a tile independently."""
+
+    def __call__(self):
+        """Return the children of the <head> tag as a fragment."""
+        # Check for the registered view permission
+        try:
+            type_ = queryUtility(ITileType, self.context.__name__)
+            permission = type_.view_permission
+        except AttributeError:
+            permission = None
+        if permission:
+            if not checkPermission(permission, self.context):
+                raise Unauthorized()
+
+        if self.request.getHeader(ESI_HEADER):
+            del self.request.environ[ESI_HEADER_KEY]
+
+        document = self.context()  # render the tile
+
+        # Disable the theme so we don't <html/>-wrapped
+        self.request.response.setHeader("X-Theme-Disabled", "1")
+
+        match = HEAD_CHILDREN.search(document)
+        if not match:
+            return document
+        return match.group(1).strip()
+
+
+class ESIBody(BrowserView):
+    """Render the head portion of a tile independently."""
+
+    def __call__(self):
+        """Return the children of the <head> tag as a fragment."""
+        # Check for the registered view permission
+        try:
+            type_ = queryUtility(ITileType, self.context.__name__)
+            permission = type_.view_permission
+        except AttributeError:
+            permission = None
+        if permission:
+            if not checkPermission(permission, self.context):
+                raise Unauthorized()
+
+        if self.request.getHeader(ESI_HEADER):
+            del self.request.environ[ESI_HEADER_KEY]
+
+        document = self.context()  # render the tile
+
+        # Disable the theme so we don't <html/>-wrapped
+        self.request.response.setHeader("X-Theme-Disabled", "1")
+
+        match = BODY_CHILDREN.search(document)
+        if not match:
+            return document
+        return match.group(1).strip()
+
+
+class ESIProtectTransform:
+    """Replacement transform for plone.protect's ProtectTransform,
+    because ESI tile responses' HTML should not be transformed to
+    avoid wrapping them with <html>-tag
+    """
+
+    order = 9000
+
+    def __init__(self, published, request):
+        self.published = published
+        self.request = request
+
+    def transform(self, result, encoding):
+        from plone.protect.interfaces import IDisableCSRFProtection
+
+        # clickjacking protection from plone.protect
+        if X_FRAME_OPTIONS:
+            if not self.request.response.getHeader("X-Frame-Options"):
+                self.request.response.setHeader("X-Frame-Options", X_FRAME_OPTIONS)
+        # drop X-Tile-Url
+        if "x-tile-url" in self.request.response.headers:
+            del self.request.response.headers["x-tile-url"]
+        # ESI requests are always GET request and should not mutate DB
+        # unless they provide IDisableCSRFProtection
+        if not IDisableCSRFProtection.providedBy(self.request):
+            transaction.abort()
+        return None
+
+    def transformBytes(self, result, encoding):
+        return self.transform(result, encoding)
+
+    def transformUnicode(self, result, encoding):
+        return self.transform(result, encoding)
+
+    def transformIterable(self, result, encoding):
+        return self.transform(result, encoding)