Metadata-Version: 2.4
Name: plone.portlets
Version: 5.0.0a1
Summary: Portlet infrastructure, the Plone portlet user interface and the standard portlets of Plone
Author-email: Plone Foundation <plone-developers@lists.sourceforge.net>
Maintainer-email: Plone Foundation and contributors <plone-developers@lists.sourceforge.net>
License-Expression: GPL-2.0-only
Project-URL: Source, https://github.com/plone/plone.portlets
Project-URL: Issues, https://github.com/plone/Products.CMFPlone/issues
Project-URL: Changelog, https://github.com/plone/plone.portlets/blob/master/CHANGES.rst
Keywords: plone,portlet,viewlet
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: 6.3
Classifier: Framework :: Plone :: Core
Classifier: Framework :: Zope :: 5
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
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 :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
Requires-Dist: BTrees
Requires-Dist: ExtensionClass
Requires-Dist: feedparser
Requires-Dist: five.customerize
Requires-Dist: persistent
Requires-Dist: plone.app.i18n
Requires-Dist: plone.app.layout
Requires-Dist: plone.app.querystring
Requires-Dist: plone.app.textfield
Requires-Dist: plone.app.uuid
Requires-Dist: plone.app.vocabularies
Requires-Dist: plone.app.z3cform
Requires-Dist: plone.autoform
Requires-Dist: plone.base
Requires-Dist: plone.i18n
Requires-Dist: plone.memoize
Requires-Dist: plone.protect
Requires-Dist: plone.registry
Requires-Dist: Products.GenericSetup
Requires-Dist: Products.MimetypesRegistry
Requires-Dist: Products.PluggableAuthService
Requires-Dist: Products.PythonScripts
Requires-Dist: Products.statusmessages
Requires-Dist: requests
Requires-Dist: z3c.form
Requires-Dist: ZODB
Requires-Dist: Zope
Requires-Dist: zope.annotation
Requires-Dist: zope.browser
Requires-Dist: zope.component
Requires-Dist: zope.container
Requires-Dist: zope.contentprovider
Requires-Dist: zope.interface
Requires-Dist: zope.location
Requires-Dist: zope.publisher
Requires-Dist: zope.schema
Provides-Extra: test
Requires-Dist: five.intid; extra == "test"
Requires-Dist: lxml; extra == "test"
Requires-Dist: plone.app.contenttypes[test]; extra == "test"
Requires-Dist: plone.app.testing; extra == "test"
Requires-Dist: plone.namedfile; extra == "test"
Requires-Dist: plone.testing; extra == "test"
Requires-Dist: plone.z3cform; extra == "test"
Requires-Dist: zope.browserpage; extra == "test"
Requires-Dist: zope.configuration; extra == "test"
Requires-Dist: zope.intid; extra == "test"
Requires-Dist: zope.security; extra == "test"
Requires-Dist: zope.site; extra == "test"
Requires-Dist: zope.testing; extra == "test"

Overview
========

``plone.portlets`` contains the complete portlet implementation of Plone:

``plone.portlets``
    A generic infrastructure for managing portlets.
    Portlets are a bit like viewlets, except they can be manipulated at runtime,
    using local components.

``plone.app.portlets``
    The Plone-specific user interface for ``plone.portlets``,
    as well as the standard set of portlets that ship with Plone.

``plone.portlet.collection``
    A portlet that fetches results from a collection.

``plone.portlet.static``
    A portlet providing a rich-text field for more or less static text.

Until version 4.x these were four separate distributions.
Since version 5.0.0 (Plone 6.3) they are shipped together in this distribution,
see `PLIP 4137 <https://github.com/plone/Products.CMFPlone/issues/4137>`_.
The import paths did not change.
The distributions ``plone.app.portlets``, ``plone.portlet.collection`` and
``plone.portlet.static`` are kept on PyPI as empty packages that depend on
``plone.portlets``, so existing dependencies keep working.
The code for Plone 6.2 and earlier stays in the former repositories.


Call one portlet by URL
=======================

To call a portlet by its URL, for example, to update it via an AJAX call, use
the ``@@render-portlet`` view in your portlet renderer with ``portlethash`` as a
query parameter.

The following example shows how to construct a reload URL for a portlet::

    from plone.app.portlets.portlets.base import Renderer
    from Products.CMFPlone.utils import safe_unicode


    class BasePortletRenderer(Renderer):
        @property
        def hash(self):
            portlethash = self.request.form.get(
                "portlethash", getattr(self, "__portlet_metadata__", {}).get("hash", "")
            )
            return portlethash

        @property
        def reload_url(self):
            base_url = self.context.absolute_url()
            hash = safe_unicode(self.hash)
            return f"{base_url}/@@render-portlet?portlethash={hash}"


Git history
===========

All four former repositories were merged with their complete history.
The code was moved into ``src/`` shortly before the merge,
so to see the history of a package before that move,
pass the old path as well, for example::

    git log -- src/plone/app/portlets plone/app/portlets

``git log --follow`` (for single files) and ``git blame`` cross the move on their own.


Compatibility
=============

- ``plone.portlets`` 5.x is for Plone 6.3.
- Plone 6.2 uses ``plone.portlets`` 4.x, ``plone.app.portlets`` 7.x,
  ``plone.portlet.collection`` 5.x and ``plone.portlet.static`` 5.x.

Changelog
=========

.. You should *NOT* be adding new change log entries to this file.
   You should create a file in the news directory instead.
   For helpful instructions, please see:
   https://github.com/plone/plone.releaser/blob/master/ADD-A-NEWS-ITEM.rst

.. towncrier release notes start

5.0.0a1 (2026-10-19)
--------------------

Breaking changes:


- Merge ``plone.app.portlets``, ``plone.portlet.collection`` and ``plone.portlet.static`` into this distribution, with their complete git history.
  Import paths do not change.
  The three former distributions are continued as empty packages that depend on ``plone.portlets``.
  See `PLIP 4137 <https://github.com/plone/Products.CMFPlone/issues/4137>`_.
  @jensens (#4137)


Internal:


- Move package metadata from ``setup.py`` to ``pyproject.toml``.
  [plone devs]


The changelog starts fresh with version 5.0.0, when ``plone.app.portlets``,
``plone.portlet.collection`` and ``plone.portlet.static`` were merged into this
distribution.
The changelogs of the four former distributions are kept in ``docs/archive/``.
