Package: collective.themefragments
Diazo Rules may operate on content that is fetched from somewhere other than
the current page being rendered by Plone, by using the href attribute to
specify a path of a resource relative to the root of the Plone site:<!-- Pull in extra navigation from a browser view on the Plone site root -->
<after
    css:theme-children="#leftnav"
    css:content=".navitem"
    href="/@@extra-nav"
    />Thehrefattribute can be used with any rule apart from<drop />and<strip />, and can reference any URL, for example to an existing browser
view configured for your site. However, it is often desirable to generate some
dynamic content specifically for the purpose of constructing a particular theme.
In this scenario, you can usefragments.Fragment templatesFragments are Zope Page Template files bundled with your theme. You can create
them by adding a folder calledfragmentsto your theme resource directory
(i.e. the directory containingrules.xml), either through the web or on the
filesystem, and creating one or more files with a.ptextension in this
directory.For example, you could create a filefragments/customnav.ptin your theme
directory, containing:<ul id="nav">
  <li tal:repeat="item context/@@folderListing">
    <img tal:replace="structure item/getIcon" />
    <span tal:replace="item/Title" tal:attributes="titile item/Description">Title</span>
  </li>
</ul>This uses Zope Page Template TAL syntax (the same syntax you might use to create
a template for a browser view if you are doing filesystem Python development,
say) to generate some markup based on the attributes and helper views available
relative to the current context.The following variables are available to the page template used to build a
fragment:contextThe context in which the fragment was looked up. This is usually either the
portal root (when using anhrefwith an absolute path, i.e. one starting
with a/) or the current content object (when using anhrefwith a
relative path).requestThe request used to render the fragment. When using a fragment from thehrefof a rule, this is a clone of the request used to render the page,
but with the path to the fragment view, not the original content object.
Note that form parameters from the original request are not available in this
request.portalThe portal root object.portal_urlThe URL to the portal root.You can learn more about Zope Page Template syntaxhere.Fragment modulesFragment modules are Restricted Python Script modules bundled with your themes.
Availability of methods is limited to specific fragment by naming the module
after the fragment base name (with.pyextension). Each module could
contain any number Python function definitions, which are then made available
as instance methods of the fragment view.For example, you could create a filefragments/customnav.pyin your
theme directory, containing:def getnav(self):
    return [{
        'Title': u'My title',
        'Description': u'My description',
        'getIcon': 'document_icon.png'
    }]And call it in your fragmentfragments/customnav.ptlike a view method:<ul id="nav">
  <li tal:repeat="item view/getnav">
    <img tal:replace="structure item/getIcon" />
    <span tal:replace="item/Title" tal:attributes="titile item/Description">Title</span>
  </li>
</ul>Fragment methodsNoteFragment methods preceded fragment modules and support for them
may be removed in the future.Fragment methods are Restricted Python Script files bundled with your themes.
Availability of methods is limited to specific fragment by prefixing the
method filename with the fragment name. Each script should contain code
for a single method and end by returning a value for the template.For example, you could create a filefragments/customnav.getnav.pyin your
theme directory, containing:return [{
    'Title': u'My title',
    'Description': u'My description',
    'getIcon': 'document_icon.png'
}]And call it in your fragmentfragments/customnav.ptlike a view method:<ul id="nav">
  <li tal:repeat="item view/getnav">
    <img tal:replace="structure item/getIcon" />
    <span tal:replace="item/Title" tal:attributes="titile item/Description">Title</span>
  </li>
</ul>The following variables are available to the fragment method used to build a
fragment:selfThe fragment view, which provides access toself.context,self.requestand other available fragment methods similarly to
filesystem browser views.argsList of positional arguments for the method call.Fragment methods do not support Zope PythonScript’s way of defining
positional named arguments.kwargsDictionary of keyword arguments for the method call.Fragment methods do not support Zope PythonScript’s way of defining
named keyword arguments.contextThe context in which the fragment was looked up.This is provided as tribute to Zope PythonScript.containerThe container for the context which the fragment was looked up.This is provided as tribute to Zope PythonScript.traverse_subpathAn empty string.This is provided as tribute to Zope PythonScript.Rendering fragmentsThe special@@theme-fragmentview is used to render fragments. Before
using it in your theme, you can test it directly in your browser by going to
a URL like:http://localhost:8080/Plone/@@theme-fragment/customnavThis will cause the fragment infragments/customnav.ptto be rendered with
the Plone sitePlonerunning onlocalhost:8080as its context. You can
render fragments relative to any content object, by adjusting the URL.Note:Fragments are only available for the currently active theme. When
testing a fragment in the browser in this way, make sure the theme is enabled!To use a fragment in a theme rule, use thehrefattribute with either an
absolute or relative path. For example:<replace css:theme="#navlist" css:content="#nav" href="/@@theme-fragment/customnav" />will replace the element with idnavlistin the theme with the element with
idnavin the fragment generated by thefragments/customnav.pttemplate
in the theme, rendered with the portal root as itscontextalways (since thehrefis using an absolute path, i.e. one beginning with a/).Similarly:<replace css:theme="#navlist" css:content="#nav" href="@@theme-fragment/customnav" />will do the same, but using the current content item as itscontext(i.e.
thehrefis using a relative path).Fragments as viewsFragments can also be used as content views, by setting thelayout-attribute of a content object to++themefragment++namewherenameis the name of the fragment. Currently fragments cannot be configured to
be visible in the display menu.Note:Fragments are only available for the currently active theme. When
using fragments in your content this way, make sure the theme is enabled!Fragment securityFragments, like theme HTML mockup files, are publicly accessible by default.
Anyone with
access to the site can construct a URL containing@@theme-fragment/<name>to
render a given fragment.Alernatively, more strict permissions can be defined per tile in thememanifest.cfgwith syntax:[theme:themefragments:permissions]basename=zope2.ViewHowever, regardless of the defined permissions, the page templates used to build
fragments execute in a so-calledRestricted Pythonenvironment. This means that the are executed as the current
user (orAnonymous, if the current user is not logged in). Information (such
as content items or their attributes) not accessible to the current user cannot
be rendered, and may result in a403 Forbiddenerror when rendering the
fragment.Fragment tilesWithplone.tiles,plone.app.tilesandplone.app.blocksinstalled this
package provides an additional installation profile forTheme fragment tile,
which can be used to place theme fragments as tiles.More readable titles for theme fragments can be defined in theme manifest.cfg
with:[theme:themefragments:tiles]basename=Display titleWherebasenameis the basename of fragment filename (the part before.pt).Tiles can define their configuration schema usingplone.supermodelXML in a
fragment specific file having its matching filename ending with.xmlinstead of.pt.It’s also possible to specify fragment specific caching ruleset in
manifest.cfg with:[theme:themefragments:caching]basename=plone.content.feedChangelog2.12 (2019-07-26)Add support for Python 3 and Plone 5.2.
[pbauer]2.11.1 (2017-10-30)Fix issue where themefragment tile was unable to render head tiles with
&_mode=head query parameter as expected
[datakurre]2.11 (2017-10-18)Add ‘macros’ accessor for fragment view to make fragment view template macros
accessible and usable e.g. in classic portlets
[datakurre]2.10.2 (2017-09-24)Fix issue where theming was disabled for frament views
[datakurre]2.10.1 (2017-09-13)Fix issue where tile id and url were not accessible from tile fragment templates
[datakurre]2.10.0 (2017-08-28)Add ++themefragment++name -traverser to allow direct use of themefragments as
views
[datakurre]Add fragment Python module support for fragment tile
[datakurre]2.9.0 (2017-08-28)Add support for fragment Python modules (as PEP8 compatible single file
replacement for fragment methods support in previous versions)
[datakurre]Change to make templates owned by their creator instead to inherit owner from
their rendered context
[datakurre]2.8.0 (2017-08-21)Add traversable @@output_relative_to helper for RichTextValue object to
support rendering rich text field values in restricted templates
[datakurre]2.7.1 (2017-06-13)Fix issue where fragment tile URL did not include selected fragment itself
[datakurre]2.7.0 (2017-06-09)Fix issue where add form was unable to use fragment name from request
[datakurre]Fix to filter comments beginning with ‘#’ when reading tile titles
[datakurre]Remove incomplete support for persistent annotation storage for theme
fragment tiles
[datakurre]2.6.1 (2017-04-19)Fix to read fragment name from tile data before selecting cache rule
[datakurre]2.6.0 (2017-04-19)Change fragment tile to prefer persistent configuratio over query
string configuration when choosing the configured fragment
[datakurre]2.5.2 (2017-02-27)Fix issue where missing ‘fragment’ parameter resulted in AttributeError
[datakurre]2.5.1 (2017-02-24)Fix issue where failure in default caching ruleset lookup prevented tile ruleset lookup
[datakurre]2.5.0 (2017-02-24)Add support for fragment tile -specific caching ruleset configuration
[datakurre]2.4.0 (2017-02-03)Addmanifest.cfgbased configuration for setting more strict
permissions per each fragment
[datakurre]2.3.1 (2017-02-02)Fix issue where ESI tile rendering used public URLs breaking it
with HTTPS. Fixed by preferring the real request path before
virtual host transform.
[datakurre]2.3.0 (2017-01-30)Add theme fragment tile to use ESI rendering when ESI rendering
is enabled in plone.app.blocks; When ESI rendering is enabled, all
theme fragment tiles will be ESI rendred (it may become configurable
in the future)
[datakurre]2.2.0 (2017-01-25)Add caching of parsed TTW tile schemas with theme policy cache
[datakurre]2.1.0 (2017-01-24)Add support for fieldsest in TTW XML schemas with
plone.app.tiles >= 3.1.0
[datakurre]2.0.1 (2017-01-18)Add generic catalog source instance to be usable with TTW XML-schema tiles
[datakurre]2.0.0 (2017-01-17)Add support for fragment specific widget traversal on fragment tile forms
[datakurre]2.0.0rc5 (2016-12-16)Add minimal permission field checker for fragment tile schemas
[datakurre]2.0.0rc4 (2016-12-15)Fix to hide fragments with empty title from tile menu
[datakurre]2.0.0rc3 (2016-12-15)Fix issue where fragments didn’t render when traversed from a view context
[datakurre]2.0.0rc2 (2016-12-14)Fix issue where fragment was not properly decoded
[datakurre]2.0.0rc1 (2016-12-12)Upgrade Theme fragment tiles with custom scheme to support layout aware
tile data storage introduced in plone.app.blocks 4.0
[datakurre]1.1.0 (2016-12-12)Refactor fragment tile source into fragment tile vocabulary to
fix compatibility issue with Plone 5.1
[datakurre]1.0.1 (2016-02-21)Fix issue where plone:tile -directive was not properly included
[datakurre]1.0.0 (2015-09-16)Add fragment tile for plone.app.mosaic
[datakurre]0.10.0 (2015-04-03)Add support for restricted python view methods
(with fragments/templatename.methodname.py)
[datakurre]0.9.0 (2015-04-01)First release based on Martin Aspeli’s rejected pull for plone.app.theming.