This package provides rendering snippets of markup organized as tiles for the
pyramid framework.
A tile is a piece of web application, i.e. a form, a navigation, etc.
Splitting your application in such small and logic application parts makes it
easy to re-use this application, simplifies application AJAXification and
the use of same application parts in different manners.
.. image:: https://img.shields.io/pypi/v/cone.tile.svg
:target: https://pypi.python.org/pypi/cone.tile
:alt: Latest PyPI version
.. image:: https://img.shields.io/pypi/dm/cone.tile.svg
:target: https://pypi.python.org/pypi/cone.tile
:alt: Number of PyPI downloads
.. image:: https://travis-ci.org/bluedynamics/cone.tile.svg?branch=master
:target: https://travis-ci.org/bluedynamics/cone.tile
.. image:: https://coveralls.io/repos/github/bluedynamics/cone.tile/badge.svg?branch=master
:target: https://coveralls.io/github/bluedynamics/cone.tile?branch=master
Usage
=====
Register tiles
--------------
A tile is registered similar to a pyramid view. Registration is done with the
the ``cone.tile.tile`` decorator on classes.
.. code-block:: python
from cone.tile import tile
from cone.tile import Tile
@tile(
name='b_tile',
path='package:browser/templates/b_tile.pt',
permission='view',
strict=False)
class BTile(Tile):
pass
There also exists a ``cone.tile.register_tile`` function. It should not be used
directly any more. ``tile`` decorator attaches this function to venusian for
deferred tile registration.
.. code-block:: python
from cone.tile import register_tile
register_tile(
name='a_tile',
path='package:browser/templates/a_tile.pt',
permission='view')
``tile`` decorator accepts the following arguments:
**name**
Identifier of the tile (for later lookup).
**path**
Either relative path to the template or absolute path or path prefixed
by the absolute package name delimeted by ':'. If ``path`` is used
``attribute`` is ignored.
**attribute**
Attribute on the given _class to be used to render the tile. Defaults to
``render``.
**interface**
Interface or class of the pyramid model the tile is registered for.
**class_**
Class to be used to render the tile. usally ``cone.tile.Tile`` or a
subclass of. Promises to implement ``cone.tile.ITile``. When the ``tile``
decorator is used, the decorated class is expected as tile implementation.
**permission**
Enables security checking for this tile. Defaults to ``view``. If set to
``None`` security checks are disabled.
**strict**
Wether to raise ``Forbidden`` or not if rendering is not permitted.
Defaults to ``True``. If set to ``False`` the exception is consumed and an
empty unicode string is returned.
Tiles can be overwritten later while application initialization by just
registering it again. This is useful for application theming and customization.
Rendering tiles
---------------
Tile rendering with the ``render_tile`` function
.. code-block:: python
from cone.tile import render_tile
rendered = render_tile(model, request, name)
Inside templates which are bound to the tile, more tiles can be rendered on
current model and request via ``tile``
.. code-block:: html
<tal:sometile replace="structure tile('tilename')" />
The Tile
--------
A tile is similar to what's known in the zope world as content provider.
Before rendering of the tile is done, the ``prepare`` function is called which
can be used to load data or whatever.
Further, the ``show`` flag is considered (which might have been set in the
``prepare`` function) and rendering is skipped if it evaluates to ``False``.
More on rendering
-----------------
There are helper functions for rendering which pass the tile renderer to
templates for invoking child tiles and consider redirections.
The tile class provides a redirect function, which expects either a string
containing a URL or a ``webob.exc.HTTPFound`` instance. This causes rendering
of remaining tiles to be skipped and ``request.environ['redirect']`` to be set.
**cone.tile.render_template**
Render template. Passes tile renderer to template. Considers redirection.
Returns empty string if redirection found.
**cone.tile.render_template_to_response**
Render template to response. Passes tile renderer to template. Considers
redirection. Returns HTTPFound instance if redirection found, otherwise
rendered response.
**cone.tile.render_to_response**
Renders some result to the response considering redirection. Returns
HTTPFound instance if redirection found, otherwise rendered response.
Contributors
============
- Robert Niederreiter
- Jens Klein
- Attila Olah
Changes
=======
1.1 (2022-12-05)
----------------
- Release wheel.
[rnix]
1.0 (2019-11-07)
----------------
- Drop pyramid support < 1.5.
[rnix, 2019-03-24]
- Python 3 compatibility.
[rnix, 2019-03-24]
- Do not use ``cgi`` module if replacement module ``html`` available.
[rnix, 2019-03-24]
- Convert doctests to unittests.
[rnix, 2019-03-21]
- ``tile`` decorator uses ``venusian`` to defer tile registration now.
[rnix, 2015-11-06]
- Accept ``name`` as keyword instead of positional argument in
``register_tile`` and ``tile`` decorator.
[rnix, 2015-11-06]
- ``registerTile`` has been renamed to ``register_tile``.
[rnix, 2015-11-06]
- Update to pyramid 1.5
[rnix, 2015-11-02]
- Remove useless test case due to this change.
https://github.com/Pylons/pyramid/commit/4b552e539a1725356b9982261b73fd88de7d59a1#diff-bcda6948340ab38542fe18fd2365ac70R144
[rnix, 2015-11-02]
0.9.6
-----
- Use ``traceback`` module instead of ``zope.exceptions`` to format
exceptions in ``render_template``.
[rnix, 2017-10-06]
0.9.5
-----
- Remove ``log_exception`` utility and use registered ``IDebugLogger`` in
``cone.tile._api.render_template`` for exception logging.
[rnix, 2017-03-24]
0.9.4
-----
- Tile registration ``name`` is taken from ``Tile`` subclass if not given
in ``registerTile`` function and ``tile`` decorator.
[rnix, 2017-02-17]
- ``name`` is now optional in ``registerTile`` function and ``tile`` decorator.
[rnix, 2017-02-17]
- Default ``attribute`` is now ``None`` in ``registerTile`` function and
``tile`` decorator to ensure considering ``attribute`` from ``Tile`` subclass
if set.
[rnix, 2017-02-17]
- ``Tile.name``, ``Tile.path`` and ``Tile.attribute`` can be set on ``Tile``
subclass directly without being overwritten at tile registration if not
given.
[rnix, 2017-02-17]
0.9.3
-----
- Errors caught in ``render_tile`` may contain umlaute. Properly decode error
string.
[rnix, 2017-02-13]
0.9.2
-----
- Using and depending now on zope.exceptions to format tracebacks with
supplements.
[jensens, 2012-06-06]
- Improved visibility of tracebacks, they appear now in the error log.
even if an expression like ```tal:replace="structure tile('editform')"```
ate it, the traceback is logged. traceback supplements are rendered.
[jensens, 2012-06-05]
- Removed superfluos try except
[jensens, 2012-06-05]
- Fixed dependencies for integrated tests
[jensens, 2012-06-05]
0.9.1
-----
- Tiles can be overwritten.
[rnix, 2012-05-22]
- Use ``zope.interface.implementer`` instead of ``zope.interface.implements``.
[rnix, 2012-05-18]
0.9
---
- Fit for pyramid 1.1 + 1.2
[rnix, 2011-09-08]
- Documentation
[rnix, 2011-09-08]
- Make it work
[jensens, rnix, et. al]
License
=======
Copyright (c) 2009-2021, BlueDynamics Alliance, Austria
Copyright (c) 2021-2022, Cone Contributors
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Raw data
{
"_id": null,
"home_page": "http://github.com/conestack/cone.tile",
"name": "cone.tile",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Cone Contributors",
"author_email": "dev@conestack.org",
"download_url": "https://files.pythonhosted.org/packages/2f/bb/2ba4786bf5d802279df2bae8a377c3db79c64dfd00889c6983185c918246/cone.tile-1.1.tar.gz",
"platform": null,
"description": "This package provides rendering snippets of markup organized as tiles for the\npyramid framework.\n\nA tile is a piece of web application, i.e. a form, a navigation, etc.\n\nSplitting your application in such small and logic application parts makes it\neasy to re-use this application, simplifies application AJAXification and\nthe use of same application parts in different manners.\n\n.. image:: https://img.shields.io/pypi/v/cone.tile.svg\n :target: https://pypi.python.org/pypi/cone.tile\n :alt: Latest PyPI version\n\n.. image:: https://img.shields.io/pypi/dm/cone.tile.svg\n :target: https://pypi.python.org/pypi/cone.tile\n :alt: Number of PyPI downloads\n\n.. image:: https://travis-ci.org/bluedynamics/cone.tile.svg?branch=master\n :target: https://travis-ci.org/bluedynamics/cone.tile\n\n.. image:: https://coveralls.io/repos/github/bluedynamics/cone.tile/badge.svg?branch=master\n :target: https://coveralls.io/github/bluedynamics/cone.tile?branch=master\n\n\nUsage\n=====\n\n\nRegister tiles\n--------------\n\nA tile is registered similar to a pyramid view. Registration is done with the\nthe ``cone.tile.tile`` decorator on classes.\n\n.. code-block:: python\n\n from cone.tile import tile\n from cone.tile import Tile\n\n @tile(\n name='b_tile',\n path='package:browser/templates/b_tile.pt',\n permission='view',\n strict=False)\n class BTile(Tile):\n pass\n\nThere also exists a ``cone.tile.register_tile`` function. It should not be used\ndirectly any more. ``tile`` decorator attaches this function to venusian for\ndeferred tile registration.\n\n.. code-block:: python\n\n from cone.tile import register_tile\n\n register_tile(\n name='a_tile',\n path='package:browser/templates/a_tile.pt',\n permission='view')\n\n``tile`` decorator accepts the following arguments:\n\n**name**\n Identifier of the tile (for later lookup).\n\n**path**\n Either relative path to the template or absolute path or path prefixed\n by the absolute package name delimeted by ':'. If ``path`` is used\n ``attribute`` is ignored.\n\n**attribute**\n Attribute on the given _class to be used to render the tile. Defaults to\n ``render``.\n\n**interface**\n Interface or class of the pyramid model the tile is registered for.\n\n**class_**\n Class to be used to render the tile. usally ``cone.tile.Tile`` or a\n subclass of. Promises to implement ``cone.tile.ITile``. When the ``tile``\n decorator is used, the decorated class is expected as tile implementation.\n\n**permission**\n Enables security checking for this tile. Defaults to ``view``. If set to\n ``None`` security checks are disabled.\n\n**strict**\n Wether to raise ``Forbidden`` or not if rendering is not permitted.\n Defaults to ``True``. If set to ``False`` the exception is consumed and an\n empty unicode string is returned.\n\nTiles can be overwritten later while application initialization by just\nregistering it again. This is useful for application theming and customization.\n\n\nRendering tiles\n---------------\n\nTile rendering with the ``render_tile`` function\n\n.. code-block:: python\n\n from cone.tile import render_tile\n rendered = render_tile(model, request, name)\n\nInside templates which are bound to the tile, more tiles can be rendered on\ncurrent model and request via ``tile``\n\n.. code-block:: html\n\n <tal:sometile replace=\"structure tile('tilename')\" />\n\n\nThe Tile\n--------\n\nA tile is similar to what's known in the zope world as content provider.\n\nBefore rendering of the tile is done, the ``prepare`` function is called which\ncan be used to load data or whatever.\n\nFurther, the ``show`` flag is considered (which might have been set in the\n``prepare`` function) and rendering is skipped if it evaluates to ``False``.\n\n\nMore on rendering\n-----------------\n\nThere are helper functions for rendering which pass the tile renderer to\ntemplates for invoking child tiles and consider redirections.\n\nThe tile class provides a redirect function, which expects either a string\ncontaining a URL or a ``webob.exc.HTTPFound`` instance. This causes rendering\nof remaining tiles to be skipped and ``request.environ['redirect']`` to be set.\n\n**cone.tile.render_template**\n Render template. Passes tile renderer to template. Considers redirection.\n Returns empty string if redirection found.\n\n**cone.tile.render_template_to_response**\n Render template to response. Passes tile renderer to template. Considers\n redirection. Returns HTTPFound instance if redirection found, otherwise\n rendered response.\n\n**cone.tile.render_to_response**\n Renders some result to the response considering redirection. Returns\n HTTPFound instance if redirection found, otherwise rendered response.\n\n\nContributors\n============\n\n- Robert Niederreiter\n- Jens Klein\n- Attila Olah\n\n\nChanges\n=======\n\n1.1 (2022-12-05)\n----------------\n\n- Release wheel.\n [rnix]\n\n\n1.0 (2019-11-07)\n----------------\n\n- Drop pyramid support < 1.5.\n [rnix, 2019-03-24]\n\n- Python 3 compatibility.\n [rnix, 2019-03-24]\n\n- Do not use ``cgi`` module if replacement module ``html`` available.\n [rnix, 2019-03-24]\n\n- Convert doctests to unittests.\n [rnix, 2019-03-21]\n\n- ``tile`` decorator uses ``venusian`` to defer tile registration now.\n [rnix, 2015-11-06]\n\n- Accept ``name`` as keyword instead of positional argument in\n ``register_tile`` and ``tile`` decorator.\n [rnix, 2015-11-06]\n\n- ``registerTile`` has been renamed to ``register_tile``.\n [rnix, 2015-11-06]\n\n- Update to pyramid 1.5\n [rnix, 2015-11-02]\n\n- Remove useless test case due to this change.\n https://github.com/Pylons/pyramid/commit/4b552e539a1725356b9982261b73fd88de7d59a1#diff-bcda6948340ab38542fe18fd2365ac70R144\n [rnix, 2015-11-02]\n\n\n0.9.6\n-----\n\n- Use ``traceback`` module instead of ``zope.exceptions`` to format\n exceptions in ``render_template``.\n [rnix, 2017-10-06]\n\n\n0.9.5\n-----\n\n- Remove ``log_exception`` utility and use registered ``IDebugLogger`` in\n ``cone.tile._api.render_template`` for exception logging.\n [rnix, 2017-03-24]\n\n\n0.9.4\n-----\n\n- Tile registration ``name`` is taken from ``Tile`` subclass if not given\n in ``registerTile`` function and ``tile`` decorator.\n [rnix, 2017-02-17]\n\n- ``name`` is now optional in ``registerTile`` function and ``tile`` decorator.\n [rnix, 2017-02-17]\n\n- Default ``attribute`` is now ``None`` in ``registerTile`` function and\n ``tile`` decorator to ensure considering ``attribute`` from ``Tile`` subclass\n if set.\n [rnix, 2017-02-17]\n\n- ``Tile.name``, ``Tile.path`` and ``Tile.attribute`` can be set on ``Tile``\n subclass directly without being overwritten at tile registration if not\n given.\n [rnix, 2017-02-17]\n\n\n0.9.3\n-----\n\n- Errors caught in ``render_tile`` may contain umlaute. Properly decode error\n string.\n [rnix, 2017-02-13]\n\n\n0.9.2\n-----\n\n- Using and depending now on zope.exceptions to format tracebacks with\n supplements.\n [jensens, 2012-06-06]\n\n- Improved visibility of tracebacks, they appear now in the error log.\n even if an expression like ```tal:replace=\"structure tile('editform')\"```\n ate it, the traceback is logged. traceback supplements are rendered.\n [jensens, 2012-06-05]\n\n- Removed superfluos try except\n [jensens, 2012-06-05]\n\n- Fixed dependencies for integrated tests\n [jensens, 2012-06-05]\n\n\n0.9.1\n-----\n\n- Tiles can be overwritten.\n [rnix, 2012-05-22]\n\n- Use ``zope.interface.implementer`` instead of ``zope.interface.implements``.\n [rnix, 2012-05-18]\n\n\n0.9\n---\n\n- Fit for pyramid 1.1 + 1.2\n [rnix, 2011-09-08]\n\n- Documentation\n [rnix, 2011-09-08]\n\n- Make it work\n [jensens, rnix, et. al]\n\n\nLicense\n=======\n\nCopyright (c) 2009-2021, BlueDynamics Alliance, Austria\nCopyright (c) 2021-2022, Cone Contributors\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this\n list of conditions and the following disclaimer.\n\n* Redistributions in binary form must reproduce the above copyright notice, this\n list of conditions and the following disclaimer in the documentation and/or\n other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND\nANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\nWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR\nANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\n(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;\nLOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND\nON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\nSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n\n",
"bugtrack_url": null,
"license": "Simplified BSD",
"summary": "Tiles for use in pyramid framework.",
"version": "1.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "1cff8e8f7978263e94807e1195e8ea50",
"sha256": "4474513776b7d5da2057a4346f51c142040ff1394def0459037cb4deb0433346"
},
"downloads": -1,
"filename": "cone.tile-1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1cff8e8f7978263e94807e1195e8ea50",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 17533,
"upload_time": "2022-12-05T11:47:33",
"upload_time_iso_8601": "2022-12-05T11:47:33.581986Z",
"url": "https://files.pythonhosted.org/packages/2a/2c/9f4407c59850c04b6a071b0cb078570ac5c89b15c8bb9aac406fca961dc2/cone.tile-1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "89e3333513914c75f83b304ed5e0e307",
"sha256": "b5eb55d3c95e3ca4cebfa77431a2722c1ac26627f14f4d888fd8e8a7c9b7c71b"
},
"downloads": -1,
"filename": "cone.tile-1.1.tar.gz",
"has_sig": false,
"md5_digest": "89e3333513914c75f83b304ed5e0e307",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18874,
"upload_time": "2022-12-05T11:47:35",
"upload_time_iso_8601": "2022-12-05T11:47:35.923289Z",
"url": "https://files.pythonhosted.org/packages/2f/bb/2ba4786bf5d802279df2bae8a377c3db79c64dfd00889c6983185c918246/cone.tile-1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-05 11:47:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "conestack",
"github_project": "cone.tile",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "cone.tile"
}
JSON
