Metadata-Version: 2.4
Name: grokcore.layout
Version: 5.0
Summary: A layout component package for Grok.
Home-page: https://github.com/zopefoundation/grokcore.layout
Author: Grok Team
Author-email: zope-dev@zope.dev
License: ZPL-2.1
Keywords: grok layout zope3 pagelet theming
Classifier: Development Status :: 6 - Mature
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Framework :: Zope :: 3
Requires-Python: >=3.9
License-File: LICENSE.txt
Requires-Dist: grokcore.component>=2.5
Requires-Dist: grokcore.security>=1.6
Requires-Dist: grokcore.view>=3.0.3
Requires-Dist: martian>=0.14
Requires-Dist: setuptools
Requires-Dist: zope.authentication
Requires-Dist: zope.component>=3.9.1
Requires-Dist: zope.errorview
Requires-Dist: zope.interface
Requires-Dist: zope.publisher
Provides-Extra: test
Requires-Dist: zope.annotation; extra == "test"
Requires-Dist: zope.app.wsgi[test]; extra == "test"
Requires-Dist: zope.container; extra == "test"
Requires-Dist: zope.login; extra == "test"
Requires-Dist: zope.schema; extra == "test"
Requires-Dist: zope.security; extra == "test"
Requires-Dist: zope.session; extra == "test"
Requires-Dist: zope.site; extra == "test"
Requires-Dist: zope.testbrowser; extra == "test"
Requires-Dist: zope.testing; extra == "test"
Requires-Dist: zope.traversing; extra == "test"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

===============
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
=========

5.0 (2025-06-18)
----------------

- Replace ``pkg_resources`` namespace with PEP 420 native namespace.


4.1 (2025-05-27)
----------------

- Add support for Python 3.12, 3.13.

- Drop support for Python 3.7, 3.8.


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]
