grokcore.viewlet 5.1
Grok-like configuration for zope viewlets
Requires Python: >=3.10

This package provides support to write and register Zope Viewlets
directly in Python (without ZCML). It's designed to be used with
`grokcore.view`_ which let you write and register Zope Views.

.. contents::

Setting up ``grokcore.viewlet``
===============================

This package is set up like the `grokcore.component`_
package. Please refer to its documentation for more details. The
additional ZCML lines you will need are::

  <include package="grokcore.viewlet" file="meta.zcml" />
  <include package="grokcore.viewlet" />

Put the first line somewhere near the top of your root ZCML file.

Examples
========

First we need a view to call our viewlet manager::

   from grokcore import viewlet

   class Index(viewlet.View):
       pass

   index = viewlet.Page Template("""
   <html>
     <head>Test</head>
     <body>
       <div tail:content="structure provider:content">
       </div>
     </body>
   </html>
   """)

After that we could define only a manager which display something::

   class Content(viewlet.ViewletManager):
       viewlet.View(Index)

       def render(self):
           return u'<h1>Hello World</h1>'


Or a completely different example::

   class AdvancedContent(viewlet.ViewletManager):
       viewlet.name('content')
       viewlet.view(Index)

And some viewlets for that one::

   class StaticData(viewlet.Viewlet):
       viewlet.view(Index)
       viewlet.viewletmanager(AdvancedContent)

       def render(self):
           return f'<p> Data from {self.context.id}</p>'

Or::

   class SecretData(viewlet.Viewlet):
       viewlet.view(Index)
       viewlet.viewletmanager(AdvancedContent)
       viewlet.require('agent.secret')

   secretdata = viewlet.PageTemplate("""
     <p>Nothing to see here.</p>
   """)

The way templates are bound to components works exactly the way as
in `grokcore.view`_, for more information refer to its
documentation.

API Overview
============

Base classes
------------

``ViewletManager``
  Define a new viewlet manager. You can either provide a render
  method, a template, which can or not use registered viewlets.

  If you define a template, ``view`` is added as a reference to the
  current view for which the manager is rendering in the template's
  namespace. It is available as well as an attribute on the manager
  object.

``Viewlet``
  Define a new viewlet. You can either provide a template or a render
  method on it. Like in views, you can define an update method to
  process needed data.

  Like for manager, ``view`` is added to the template namespace if
  used. ``viewletmanager`` is defined as well as a reference to the
  manager in the template's namespace and as an attribute on the
  viewlet object.

Directives
----------

You can use directives from `grokcore.view`_ to register your
viewlet or viewlet manager: ``name``, ``context``, ``layer`` and
``require`` (for security on a viewlet).

To that is added:

``view``
   Select for which view is registered a viewlet or a viewlet manager.

``viewletmanager``
   Select for which viewlet manager is registered a viewlet.

``order``
   Define a rendering order for viewlets in a viewlet manager. This
   should be a number, the smaller order render first, bigger last.


Additionally, the ``grokcore.viewlet`` package exposes the
`grokcore.component`_, `grokcore.security`_ and `grokcore.view`_ APIs.

.. _grokcore.component: https://pypi.org/project/grokcore.component
.. _grokcore.viewlet: https://pypi.org/project/grokcore.viewlet
.. _grokcore.security: https://pypi.org/project/grokcore.security
.. _grokcore.view: https://pypi.org/project/grokcore.view

Changes
=======

5.1 (2026-02-18)
----------------

* Move package metadata from setup.py to pyproject.toml.

* Add support for Python 3.14.

* Drop support for Python 3.9.


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

* Add support for Python 3.7, 3.8, 3.9, 3.10, 3.11.

* Drop support for Python 2.7, 3.4, 3.5, 3.6.


3.1.0 (2018-02-05)
------------------

* viewletmanager.viewlets should be a list so we can iterate over it several
  times in consumer code instead of having to remember it's an iterable we can
  only list once.

3.0.1 (2018-01-12)
------------------

* Rearrange tests such that Travis CI can pick up all functional tests too.

3.0.0 (2018-01-04)
------------------

* Python 3 compatibility.

1.11 (2012-09-04)
-----------------

* Make the ``has_render()`` and ``has_no_render()`` symmetrical to those
  in grokcore.view, grokcore.layout and grokcore.formlib, where a
  ``render.base_method`` attribute is checked.

1.10.1 (2012-05-02)
-------------------

* Do not require the role extra from grokcore.security.

1.10 (2012-05-02)
-----------------

* Use the component registration api from grokcore.component.

* Update how the static resources are found on a ``ViewletManager``
  and a ``Viewlet``, following the new name ``__static_name__`` set by
  the template association.

1.9 (2011-06-28)
----------------

* Introduce the `available()` method on viewlet component. The viewlet
  manager will filter out unavailable viewlet by calling this method. The
  `available()` method is called *after* the viewlet's `update()` is called,
  but *before* the `render()` is called.

1.8 (2010-12-16)
----------------

* Update to use TemplateGrokker from grokcore.view to associate
  viewlet and viewletmanager templates.

1.7 (2010-11-03)
----------------

* The computed default value for the viewletmanager directive is now defined
  in the directiv itself, not as a separate function that needs to be passed
  along.

1.6 (2010-11-01)
----------------

* Upped version requirements for martian, grokcore.component, and grokcore.view.

* Move the order directive to grokcore.component.

* Move the view directive to grokcore.view.

1.5 (2010-10-18)
----------------

* Make package comply to zope.org repository policy.

* Update functional tests to use Browser implementation of zope.app.wsgi
  instead of zope.app.testing.

* Reduce dependencies (zope.app.pagetemplate no longer necessary).

1.4.1 (2010-02-28)
------------------

* Dropped the dependency on ``zope.app.zcmlfiles``.

* Cleaned the code to remove unused imports and ensure the pep8 syntax.

* Updated tests to have a return value consistency. The
  grokcore.viewlet viewlet manager implementation requires viewlets to
  return unicode strings. Now, viewlets return unicode strings in the
  test packages.

1.4 (2010-02-19)
----------------

* Define test requires.

1.3 (2009-09-17)
----------------

* Reverted the use of grokcore.view.CodeView. We now require
  ``grokcore.view`` 1.12.1 or newer. As of ``grokcore.view`` 1.12, the
  CodeView/View separation has been undone.

1.2 (2009-09-16)
----------------

* Remove the reference to the grok.View permission that is no longer in
  grokcore.security 1.2

* Use the grok.zope.org/releaseinfo information instead of our own
  copy of ``versions.cfg``, for easier maintenance.


1.1 (2009-07-20)
----------------

* Adapted tests to new grokcore.view release: switched from View to CodeView.

* Add grok.View permissions to functional tests (requires grokcore.security
  1.1)

1.0 (2008-11-15)
----------------

* Created ``grokcore.viewlet`` in November 2008 by factoring
  ``zope.viewlet``-based components, grokkers and directives out of
  Grok.