collective.behavior.relatedmedia

A Plone Dexterity behavior that lets editors upload, manage, and display related images and file attachments directly on content items — without leaving the edit form.

Features

• Dexterity behavior — attach the behavior to any content type via the control panel or ZCML; no custom content type required.
• Dedicated edit tab — a Related Media tab appears on every content item that has the behavior enabled.
• Inline upload & selection — editors can upload new files or pick existing Plone content objects through the relation widget; relation type (image vs. attachment) is determined automatically from the file's MIME type.
• Drag-and-drop ordering — items inside the widget can be reordered via drag-and-drop; titles are editable inline.
• Configurable media container — uploaded files are stored in a dedicated folder whose path is defined in the Related Media Settings control panel. Supports plone.app.multilingual (language-independent assets folder) and per-object sub-containers.
• Viewlets for display — two viewlets render the media on the content view:
  • collective.behavior.related_images (default: plone.belowcontenttitle)
  • collective.behavior.related_attachments (default: plone.belowcontentbody)
• Inline gallery via TinyMCE — a toolbar button lets editors embed an image gallery directly inside the rich-text body; placement, image selection, and order are fully configurable without leaving the editor.
• Configurable image scales — default scales for thumbnails, preview images, and overlay images are set globally in the control panel.
• Gallery CSS classes — a registry-controlled vocabulary provides the available CSS classes for galleries; a default class can be preselected.

Installation

pip install collective.behavior.relatedmedia

or add the egg to your buildout configuration, then enable the add-on in the Plone Add-ons control panel.

Configuration

Open Site Setup → Add-on Configuration → Related Media Settings and:

1. Set a valid Media Container path (relative to the site root or navigation root) where uploaded files will be stored.
2. Optionally enable Create Media Container in Assets Folder if you use plone.app.multilingual and want language-independent storage.
3. Adjust the default image scales and gallery CSS classes to match your theme.

Usage

Adding media to a content item

1. Open the content item in edit mode.
2. Switch to the Related Media tab.
3. Use the Related Images widget to upload new images or select existing ones. Use the Related Attachments widget for non-image files.
4. Reorder items by dragging, edit titles inline, then save.

Embedding a gallery in the rich-text body

1. Place the cursor in the text where the gallery should appear.
2. Click the Gallery icon in the TinyMCE toolbar.
3. Select the images and choose a gallery style; drag-and-drop to reorder.
4. To modify an existing gallery, click inside the preview block and open the toolbar icon again.

Note: If you embed a gallery in the text body, disable the Show images in viewlet checkbox to avoid rendering images twice. Images added to the behavior after inserting the gallery must be added to the TinyMCE gallery manually.

Overriding viewlet placement

<include package="collective.behavior.relatedmedia" />
<configure package="collective.behavior.relatedmedia">
    <browser:viewlet
        name="collective.behavior.related_images"
        for="*"
        manager="plone.app.layout.viewlets.interfaces.IAboveContentTitle"
        template="widget_images_display.pt"
        permission="zope2.View" />
</configure>

Authors

• Peter Mathis [petschki]

Contributors

• Peter Holzer [agitator]

Changelog

3.10.0 (2026-10-13)

• Module federation: the remote entry exports its bundle import as default (export default import("./bundle")), so the Patternslib Module Federation helper of @patternslib/dev >= 4.1 (plone.staticresources >= 3.0.8) waits for the pattern and component registrations before the host's initial DOM scan. Bundles rebuilt against plone.staticresources 3.0.9 (mockup 5.6.14, Svelte runtime 5.57.0, @patternslib/dev 4.3). @petschki

3.9.1 (2026-09-03)

• Open the related images of the viewlet in Fancybox: bind the lightbox globally and load its CSS in the bundle, not only inside the pat-related-images gallery pattern. @petschki

• Fix the "crop" options of the gallery: they produced uncropped scales and vice versa, because plone.scale's contain mode crops while cover fits. @petschki

• Nothing changed yet.

3.9.0 (2026-09-02)

• Rebuild the JavaScript bundle against mockup 5.6.9 / Svelte 5 so the selected items of the related media widget show up again in Plone 6.2: the custom SelectedItem components are Svelte 5 (runes) components now and consume the Svelte runtime shared by the Plone bundle. Requires plone.staticresources >= 3.0.5 (Plone 6.2.1 pins 3.0.2, override it in your project). The Svelte compiler is pinned to the runtime version of that release; a newer compiler emits helpers the shared runtime does not have. @petschki
• Switch the JavaScript build from yarn to pnpm. @petschki
• tox/CI install with the committed constraints-mxdev.txt (plone/meta use_mxdev), generated with mxdev -c mx.ini from the Plone 6.2 constraints plus the plone.staticresources override; robot test adapted to the content browser markup of mockup 5.6.9. Test matrix covers Python 3.10 to 3.14. @petschki
• Related Media Statistics view including a purge method to cleanup unused media. @petschki

3.8.0 (2025-12-01)

• Deduplicate lead image in gallery viewlet. Auto-add leadimage if not already in related images. @petschki

3.7.5 (2025-05-05)

• Do not break if the lead image adapter cannot be initialized (fixes #25). @ale-rt

3.7.4 (2025-04-03)

• Fix "display" templates of RelatedMediaWidgets -> use FormBrowserLayer to override p.a.z3cform. @petschki

3.7.3 (2025-03-21)

• Refactor default settings value lookup. @petschki
• Fix REQUEST during object removal. @petschki

3.7.2 (2025-03-05)

Bug fixes:

• Fix SelectedItem component "unselect" [petschki]

3.7.1 (2025-02-28)

Bug fixes:

• Cleanup obsolete pattern templates and upload viewlet. Upload is done now only in Contentbrowser.
• Add CSS for TinyMCE to make inline galleries better editable. [petschki]

3.7.0 (2025-02-20)

• Use ContentBrowserWidget if Plone 6.1. [petschki]

3.6.6 (2024-11-13)

• Configurable large overlay images scale [petschki]

3.6.5 (2024-10-28)

• Inject slickSliderOptions via data-attributes. [petschki]

3.6.4 (2024-10-28)

• Fix Fancybox initialization problems. [petschki]

3.6.3 (2024-10-25)

• Initialize "slick-slider" automatically inside TinyMCE image gallery. [petschki]

3.6.2 (2024-06-14)

• Fix broken attachments. [petschki]

3.6.1 (2024-06-14)

• Hide image/attachment viewlet when no content available. [petschki]
• update JS resources. [petschki]

3.6.0 (2024-05-14)

• Enhanced Attachment viewlet. [petschki]

3.5.4 (2024-04-08)

• Fixed upgrade step for TinyMCE gallery tool. Cleanup settings for old template. [petschki]

3.5.3 (2024-03-22)

• Fixed upgrade step for migrating "base_path" relations. [petschki]

3.5.2 (2024-02-29)

• Remove old obsolete JS resource from upload viewlet. [petschki]

3.5.1 (2024-02-27)

• packaging updates. [petschki]

3.5.0 (2024-02-27)

Features:

• New gallery editor plugin for TinyMCE replacing the gallery template and adds possibility to select/reorder gallery images inside TinyMCE. [petschki]

3.4.0 (2024-01-25)

Features:

• Outputfilter and pattern for related image gallery.
• TinyMCE template for gallery placement inside richtext. [petschki]

3.3.5 (2023-11-16)

• Do not fail in update script when broken catalog brains exists. [petschki]

3.3.4 (2023-10-09)

• Fix syncing review_state of (deprecated) related media container. [petschki]

3.3.3 (2023-09-27)

• Fix error when invalid attachment is uploaded. [petschki]

3.3.2 (2023-09-21)

• Added upgrade tep for renamed behavior. [petschki]

3.3.1 (2023-07-19)

• Fix default behavior assignment for "Page". [petschki]

3.3.0 (2023-07-17)

Feature:

• Mark base_path concept as deprecated and add a migration script for it. [petschki]

• Convenience short name for behavior. [petschki]

• Use plone.base.utils.human_readable_size for attachment size and implement mimetype icons for attachment list. [petschki]

3.2.0 (2022-07-20)

• Fixed customized selection.xml template for pat-relateditems. [petschki]

• CI Test setup with mxdev. [petschki]

• Remove related-media widget and enable "upload" for related widget. [petschki]

3.1.1 (2022-07-04)

• Fix moved utility. import now from plone.base [petschki]

3.1.0 (2022-04-23)

• remove requireJS from JS resource (Plone 6 compatibility) [petschki]

3.0.4 (2022-03-16)

• Add browserlayer for viewlets. (fixes #7) [petschki]

3.0.3 (2022-03-14)

• Fix related media container utility permissions [petschki]

3.0.2 (2022-03-09)

• Fix bug in memoized utility [petschki]

3.0.1 (2022-03-09)

• Fix adding leadimage to the gallery
• Fix media container determination when in language independent Assets [petschki]

3.0.0 (2022-01-18)

Breaking changes:

• 3.x is Plone6/py3 only version. Use 2.x for Plone5/py2/3 compatibility [petschki]

• Change strategy for optional media base_path container creation. This is a registry setting.

• inline title editing for related items

• Plone6 / Classic Theme updates [petschki]

2.1.3 (2020-07-22)

• Fix bug in util method when related base_path is missing. fixes #2 [petschki]

2.1.2 (2020-07-02)

• Fix issue with unauthorized media folder [petschki]

• Update/enhance default settings in controlpanel [petschki]

• bugfix in workflow synchronization of related media base path [petschki]

2.1.1 (2020-05-27)

• Fix imports to support plone.app.contenttypes < 2.0 [petschki]

2.1 (2020-05-27)

Features:

• global setting to always update first related image as leadimage. This is disabled per default. [petschki]

2.0.3 (2020-05-26)

• fix attachment viewlet to be hidden when no files are related [petschki]

2.0.2 (2019-12-13)

• Fix bug in workflow sync event when pasting objects [petschki]

2.0.1 (2019-11-22)

• merged HISTORY.txt and CHANGES.rst [petschki]

2.0.0 (2019-11-22)

• Python 3 / Plone 5.2 compatibility [petschki]

• Media Base Path feature [petschki]

• test setup and CI [petschki]

1.1.1 (2018-05-25)

• Update documentation. [petschki]

1.1 (2018-05-25)

• fix image_size vocabulary. Plone 5 compatibility. [petschki]

1.0 (2018-05-23)

• Fix issue with disappearing images when 'include_leadimage' was deactivated [petschki]

• support for Event Occurrences. [petschki]

• add markup for fancybox library [petschki]

• Separate viewlet caption and overlay caption [petschki]

1.0b1 (2015-07-15)

• title caption toggle for gallery images [petschki]

1.0a1 (2015-07-14)

• Initial release