===============
grokcore.layout
===============
The `grokcore.layout` package provides a simple way to write view
components which can be included into a defined layout. It turns
around two main components : the Page and the Layout.
Layout
======
The layout is a component allowing you to design your site. Often,
it's the common structure shared between all the pages. Technically,
it is a class based on the view components interface, providing a
'render' and 'update' method.
Let's implement a simple Layout:
>>> from grokcore.layout import Layout
>>> from zope.interface import Interface
>>> import grokcore.component as grok
>>> class MyLayout(Layout):
... grok.name('mylayout')
... grok.context(Interface)
...
... def render(self):
... return u"a simple layout"
We grok our component:
>>> grok_component('MyLayout', MyLayout)
True
We check it has been correctly registered:
>>> from grokcore.layout import ILayout
>>> from zope.component import getMultiAdapter
>>> from zope.publisher.browser import TestRequest
>>> layout = getMultiAdapter((TestRequest(), Interface), ILayout)
>>> isinstance(layout, MyLayout)
True
>>> print(layout.render())
a simple layout
Now let's see how to use this Layout in a specific context using a Page.
Page
====
The page is the specific code that you want to control. It is based on
the grokcore.View browser page implementation and therefore provides a
``render`` and ``update`` method. The ``render`` method will simply
return the specific HTML code generated by the template or the
``render`` method code while ``__call__`` will lookup for a Layout
component and renders itself inside it.
First, we'll create 2 models that will serve as exemples.
>>> class Aurochs(grok.Context):
... description = u'Looks like a bull'
>>> class Mammoth(grok.Context):
... description = u'Looks like an elephant'
Let's create now a page that will display their description.
>>> from grokcore.layout import Page
>>> class AnimalDisplay(Page):
... grok.name('display')
... grok.context(Interface)
...
... def render(self):
... return self.context.description
Grokking our Page will let us use it.
>>> grok_component('AnimalDisplay', AnimalDisplay)
True
>>> wooly = Mammoth()
>>> page = getMultiAdapter((wooly, TestRequest()), name='display')
>>> print(page.content())
Looks like an elephant
>>> print(page())
a simple layout
As we can see, the page is using the layout, on the __call__ to
render. Of course, this example Layout doesn't provide any interesting
feature. Let's create something more interesting, by using our page
with the help of the 'content' method:
>>> class MammothLayout(Layout):
... grok.context(Mammoth)
...
... def render(self):
... return u'Header. Page: %s. Footer' % self.view.content()
>>> grok_component('MammothLayout', MammothLayout)
True
>>> print(page())
Header. Page: Looks like an elephant. Footer
Forms & Errorpages
==================
Baseclasses for Form views (FormPage, AddFormPage, EditFormPage and DisplayFormPage) and Error
views (NotFoundPage, ExceptionPage, UnauthorizedPage) are available which are
all aware of Layout components like Page is.
Changelog
=========
4.0 (2023-08-28)
----------------
- Drop support for Python 2.7, 3.4, 3.5, 3.6.
- Add support for Python 3.7, 3.8, 3.9, 3.10, 3.11.
- Update to ``zope.component >= 5``.
3.0.3 (2018-02-08)
------------------
- Bugfix: Exception pages did not report their contents as text/html, but used
text/plain instead (from their ``zope.errorview`` base classes). Layouts and
pages are about HTML however and the sensible default content type for those
is ``text/html``.
3.0.2 (2018-01-17)
------------------
- Replace the use of ``grok.implements()`` with the ``@grok.implementer()``.
directive throughout.
3.0.1 (2018-01-12)
------------------
- Rearrange tests such that Travis CI can pick up all functional tests too.
3.0.0 (2018-01-10)
------------------
- Python 3 compatibility.
1.6.1 (2016-02-15)
------------------
- Update tests.
1.6 (2012-05-10)
----------------
- Moved the lookup for a specific layout to a helper method, so other
layout aware components can use the same lookup.
1.5.1 (2012-05-02)
------------------
- Do not require the [role] extra of grokcore.security anymore.
1.5 (2012-05-02)
----------------
- Move the layout-aware form components to the grok package where the
dependency with grokcore.formib can be mixed in.
- Add a directive ``layout`` to select a different type of layout. A layout
type is defined on a ``Layout`` component with the help of the
``grokcore.component.provides`` directive. It defaults to ``ILayout``
for compatibility.
- Change how the static resources are associated to a ``Layout``,
using the new name ``__static_name__`` set by the template grokker.
1.4 (2011-07-13)
----------------
- Rename megrok.layout to grokcore.layout. ``application_url`` and ``flash``
utilities have been removed, \*Form components have been renamed to
\*FormPage.
- Added ExceptionPage, NotFoundPage and UnauthorizedPage layout-aware
components.
- Fixed default template for grokcore.layout.Form component.
1.3 (2011-01-12)
----------------
- Compatibility with grokcore.view 2.3.
1.2.0 (2010-12-16)
------------------
- Update to use the new TemplateGrokker from grokcore.view.
1.1.0 (2010-03-03)
------------------
- ``z3c.flashmessage`` has been dropped in favor of
``grokcore.message``. This new package takes in charge the
registration of the utilities and retains the existing API. The
back-compatibility is assured.
1.0.2 (2010-02-26)
------------------
- The existence test for the `application_url` site-lookup was
wrongly using a "if not" statement. In a case of a container, the object
is evaluated to False if it's empty. We now use a proper "if .. is
None". [trollfot]
1.0.1 (2010-02-25)
------------------
- Forms now inherit from `UtilityView` and therefore get the
`application_url` and `flash` methods. Tests have been added to
garanty the behavior. [trollfot]
1.0 (2010-02-25)
----------------
- The dependencies have been heavily cleaned up. All zope.app packages
have been removed. We are now running with minimal dependencies and
using the latest ZTK. This release will probably *not* run on
`Grok 1.0`. You will need `Grok 1.1rc1` to be able to use
it. [trollfot]
- Added a component called UtilityView that provides two useful
methods : application_url, flash. These methods are almost a copy of
what can be found in the `Grok` package. The application_url is
using a simple getSite hook to get the root of the application. This
might be irrelevant for some applications and can be overriden.
[trollfot]
- Added a module called 'messages' that contains the flash messages
utilities. This module is *NOT* grokked and must be grokked
manually. This prevents conflicts with grokui.admin's own
definitions of the very same components. It also allows you to
override the `flash` method to use something else than
z3c.flashmessage and then not be bothered by useless utilities. The
flash messages utilities can be registered by including the
``messages.zcml`` file in your own project or package ZCML file.
[trollfot]
0.9 (2009-09-26)
----------------
- Add default templates to form which doesn't contain an html and body
tag.
[sylvain]
- Add an AddForm, EditForm and DisplayForm, all aware of the layout
component.
[sylvain]
0.8 (2009-09-17)
----------------
- Remove the CodePage, since CodeView have been removed from
grokcore.view.
[sylvain]
0.7 (2009-09-15)
----------------
- Add a CodePage to be compatible with the last version of
grokcore.view (higher than 1.9). This breaks compatibility with
previous release. You need to change any Page using a render method
to a CodePage.
[sylvain]
- The content property on a Page is no longer a property, but a method
as it's hidding exceptions. You might need to update your code to
reflect that change as well.
[sylvain]
- Fix MANIFEST.in.
[sylvain]
0.6 (2009-09-14)
----------------
- switch the arguments order in calling the layout
[cklinger, sylvain]
- add the CHANGES.txt
[cklinger]
0.5 (2009-07-24)
----------------
- remove the grok dependency
[cklinger trollfot]
Raw data
{
"_id": null,
"home_page": "https://github.com/zopefoundation/grokcore.layout",
"name": "grokcore.layout",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "grok layout zope3 pagelet theming",
"author": "Grok Team",
"author_email": "zope-dev@zope.dev",
"download_url": "https://files.pythonhosted.org/packages/00/7b/ce4c7607ea69a5cfe5c8f069ce8f6ee6a017437da2fd7b1c324cb664afe2/grokcore.layout-4.0.tar.gz",
"platform": null,
"description": "===============\ngrokcore.layout\n===============\n\nThe `grokcore.layout` package provides a simple way to write view\ncomponents which can be included into a defined layout. It turns\naround two main components : the Page and the Layout.\n\nLayout\n======\n\nThe layout is a component allowing you to design your site. Often,\nit's the common structure shared between all the pages. Technically,\nit is a class based on the view components interface, providing a\n'render' and 'update' method.\n\nLet's implement a simple Layout:\n\n >>> from grokcore.layout import Layout\n >>> from zope.interface import Interface\n >>> import grokcore.component as grok\n\n >>> class MyLayout(Layout):\n ... grok.name('mylayout')\n ... grok.context(Interface)\n ...\n ... def render(self):\n ... return u\"a simple layout\"\n\nWe grok our component:\n\n >>> grok_component('MyLayout', MyLayout)\n True\n\nWe check it has been correctly registered:\n\n >>> from grokcore.layout import ILayout\n >>> from zope.component import getMultiAdapter\n >>> from zope.publisher.browser import TestRequest\n\n >>> layout = getMultiAdapter((TestRequest(), Interface), ILayout)\n >>> isinstance(layout, MyLayout)\n True\n >>> print(layout.render())\n a simple layout\n\nNow let's see how to use this Layout in a specific context using a Page.\n\nPage\n====\n\nThe page is the specific code that you want to control. It is based on\nthe grokcore.View browser page implementation and therefore provides a\n``render`` and ``update`` method. The ``render`` method will simply\nreturn the specific HTML code generated by the template or the\n``render`` method code while ``__call__`` will lookup for a Layout\ncomponent and renders itself inside it.\n\nFirst, we'll create 2 models that will serve as exemples.\n\n >>> class Aurochs(grok.Context):\n ... description = u'Looks like a bull'\n\n >>> class Mammoth(grok.Context):\n ... description = u'Looks like an elephant'\n\nLet's create now a page that will display their description.\n\n >>> from grokcore.layout import Page\n >>> class AnimalDisplay(Page):\n ... grok.name('display')\n ... \t grok.context(Interface)\n ...\n ... def render(self):\n ... return self.context.description\n\nGrokking our Page will let us use it.\n\n >>> grok_component('AnimalDisplay', AnimalDisplay)\n True\n >>> wooly = Mammoth()\n >>> page = getMultiAdapter((wooly, TestRequest()), name='display')\n >>> print(page.content())\n Looks like an elephant\n >>> print(page())\n a simple layout\n\nAs we can see, the page is using the layout, on the __call__ to\nrender. Of course, this example Layout doesn't provide any interesting\nfeature. Let's create something more interesting, by using our page\nwith the help of the 'content' method:\n\n >>> class MammothLayout(Layout):\n ... grok.context(Mammoth)\n ...\n ...\t def render(self):\n ...\t return u'Header. Page: %s. Footer' % self.view.content()\n\n >>> grok_component('MammothLayout', MammothLayout)\n True\n >>> print(page())\n Header. Page: Looks like an elephant. Footer\n\nForms & Errorpages\n==================\n\nBaseclasses for Form views (FormPage, AddFormPage, EditFormPage and DisplayFormPage) and Error\nviews (NotFoundPage, ExceptionPage, UnauthorizedPage) are available which are\nall aware of Layout components like Page is.\n\n\nChangelog\n=========\n\n4.0 (2023-08-28)\n----------------\n\n- Drop support for Python 2.7, 3.4, 3.5, 3.6.\n\n- Add support for Python 3.7, 3.8, 3.9, 3.10, 3.11.\n\n- Update to ``zope.component >= 5``.\n\n\n3.0.3 (2018-02-08)\n------------------\n\n- Bugfix: Exception pages did not report their contents as text/html, but used\n text/plain instead (from their ``zope.errorview`` base classes). Layouts and\n pages are about HTML however and the sensible default content type for those\n is ``text/html``.\n\n3.0.2 (2018-01-17)\n------------------\n\n- Replace the use of ``grok.implements()`` with the ``@grok.implementer()``.\n directive throughout.\n\n3.0.1 (2018-01-12)\n------------------\n\n- Rearrange tests such that Travis CI can pick up all functional tests too.\n\n3.0.0 (2018-01-10)\n------------------\n\n- Python 3 compatibility.\n\n1.6.1 (2016-02-15)\n------------------\n\n- Update tests.\n\n1.6 (2012-05-10)\n----------------\n\n- Moved the lookup for a specific layout to a helper method, so other\n layout aware components can use the same lookup.\n\n1.5.1 (2012-05-02)\n------------------\n\n- Do not require the [role] extra of grokcore.security anymore.\n\n1.5 (2012-05-02)\n----------------\n\n- Move the layout-aware form components to the grok package where the\n dependency with grokcore.formib can be mixed in.\n\n- Add a directive ``layout`` to select a different type of layout. A layout\n type is defined on a ``Layout`` component with the help of the\n ``grokcore.component.provides`` directive. It defaults to ``ILayout``\n for compatibility.\n\n- Change how the static resources are associated to a ``Layout``,\n using the new name ``__static_name__`` set by the template grokker.\n\n1.4 (2011-07-13)\n----------------\n\n- Rename megrok.layout to grokcore.layout. ``application_url`` and ``flash``\n utilities have been removed, \\*Form components have been renamed to\n \\*FormPage.\n\n- Added ExceptionPage, NotFoundPage and UnauthorizedPage layout-aware\n components.\n\n- Fixed default template for grokcore.layout.Form component.\n\n1.3 (2011-01-12)\n----------------\n\n- Compatibility with grokcore.view 2.3.\n\n1.2.0 (2010-12-16)\n------------------\n\n- Update to use the new TemplateGrokker from grokcore.view.\n\n1.1.0 (2010-03-03)\n------------------\n\n- ``z3c.flashmessage`` has been dropped in favor of\n ``grokcore.message``. This new package takes in charge the\n registration of the utilities and retains the existing API. The\n back-compatibility is assured.\n\n1.0.2 (2010-02-26)\n------------------\n\n- The existence test for the `application_url` site-lookup was\n wrongly using a \"if not\" statement. In a case of a container, the object\n is evaluated to False if it's empty. We now use a proper \"if .. is\n None\". [trollfot]\n\n1.0.1 (2010-02-25)\n------------------\n\n- Forms now inherit from `UtilityView` and therefore get the\n `application_url` and `flash` methods. Tests have been added to\n garanty the behavior. [trollfot]\n\n1.0 (2010-02-25)\n----------------\n\n- The dependencies have been heavily cleaned up. All zope.app packages\n have been removed. We are now running with minimal dependencies and\n using the latest ZTK. This release will probably *not* run on\n `Grok 1.0`. You will need `Grok 1.1rc1` to be able to use\n it. [trollfot]\n\n- Added a component called UtilityView that provides two useful\n methods : application_url, flash. These methods are almost a copy of\n what can be found in the `Grok` package. The application_url is\n using a simple getSite hook to get the root of the application. This\n might be irrelevant for some applications and can be overriden.\n [trollfot]\n\n- Added a module called 'messages' that contains the flash messages\n utilities. This module is *NOT* grokked and must be grokked\n manually. This prevents conflicts with grokui.admin's own\n definitions of the very same components. It also allows you to\n override the `flash` method to use something else than\n z3c.flashmessage and then not be bothered by useless utilities. The\n flash messages utilities can be registered by including the\n ``messages.zcml`` file in your own project or package ZCML file.\n [trollfot]\n\n0.9 (2009-09-26)\n----------------\n\n- Add default templates to form which doesn't contain an html and body\n tag.\n [sylvain]\n\n- Add an AddForm, EditForm and DisplayForm, all aware of the layout\n component.\n [sylvain]\n\n0.8 (2009-09-17)\n----------------\n\n- Remove the CodePage, since CodeView have been removed from\n grokcore.view.\n [sylvain]\n\n0.7 (2009-09-15)\n----------------\n\n- Add a CodePage to be compatible with the last version of\n grokcore.view (higher than 1.9). This breaks compatibility with\n previous release. You need to change any Page using a render method\n to a CodePage.\n [sylvain]\n\n- The content property on a Page is no longer a property, but a method\n as it's hidding exceptions. You might need to update your code to\n reflect that change as well.\n [sylvain]\n\n- Fix MANIFEST.in.\n [sylvain]\n\n0.6 (2009-09-14)\n----------------\n\n- switch the arguments order in calling the layout\n [cklinger, sylvain]\n\n- add the CHANGES.txt\n [cklinger]\n\n0.5 (2009-07-24)\n----------------\n\n- remove the grok dependency\n [cklinger trollfot]\n",
"bugtrack_url": null,
"license": "ZPL 2.1",
"summary": "A layout component package for Grok.",
"version": "4.0",
"project_urls": {
"Homepage": "https://github.com/zopefoundation/grokcore.layout"
},
"split_keywords": [
"grok",
"layout",
"zope3",
"pagelet",
"theming"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ba0e3eebcfcceed1ad8b36fb56b9cf4dd62c5946457a0c7df14859362a90aa52",
"md5": "183497033140234558b8f26a656f1e01",
"sha256": "95b7b3e22ffee5cc49c50e2a02f6a9cfa9e74edc0585d92007b89421f7df2b5b"
},
"downloads": -1,
"filename": "grokcore.layout-4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "183497033140234558b8f26a656f1e01",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 23895,
"upload_time": "2023-08-28T11:53:00",
"upload_time_iso_8601": "2023-08-28T11:53:00.787466Z",
"url": "https://files.pythonhosted.org/packages/ba/0e/3eebcfcceed1ad8b36fb56b9cf4dd62c5946457a0c7df14859362a90aa52/grokcore.layout-4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "007bce4c7607ea69a5cfe5c8f069ce8f6ee6a017437da2fd7b1c324cb664afe2",
"md5": "5d932e8a78294bdcd3c4bed88a0b8ad1",
"sha256": "69ba32333e37cd04846e03ab854a14fb245cb0195875be404adcf0e88d76c881"
},
"downloads": -1,
"filename": "grokcore.layout-4.0.tar.gz",
"has_sig": false,
"md5_digest": "5d932e8a78294bdcd3c4bed88a0b8ad1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 18925,
"upload_time": "2023-08-28T11:53:02",
"upload_time_iso_8601": "2023-08-28T11:53:02.380806Z",
"url": "https://files.pythonhosted.org/packages/00/7b/ce4c7607ea69a5cfe5c8f069ce8f6ee6a017437da2fd7b1c324cb664afe2/grokcore.layout-4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-28 11:53:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zopefoundation",
"github_project": "grokcore.layout",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "grokcore.layout"
}
JSON
