Extension Point : IAttachmentChangeListener

Interface	IAttachmentChangeListener	Since	0.10
Module	trac.attachment	Source	attachment.py​

The IAttachmentChangeListener allows components to listen for and to react to attachment events.

Purpose

Trac allows users to attach arbitrary files to e.g. tickets or wiki pages. Plugins can hook into the attachment module to trigger their own actions when attachments are added, deleted or moved (i.e. moved to another parent resource and / or renamed).

The main purpose for this interface is to allow plugins to stay informed about the existing attachments and trigger appropriate actions elsewhere (e.g. sending notifications, starting indexing services, updating supplementary data structures etc.)

(For attachment validation and manipulation use IAttachmentManipulator instead.)

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

When a user adds a new attachment the attachment_added method is called. Similarly attachment_deleted is called when a user deletes an attachment or its parent resource, and attachment_moved is called when a user moves an attachment to a new parent resource or renames the attachment or the parent resource.

Examples

A common use case for attachments is to attach images to wiki pages. For convenience you might want to automatically append an Image macro to the wiki page. The following minimal example IAttachmentChangeListener implementation could implement such a feature:

from trac.core import Component, implements
from trac.attachment import IAttachmentChangeListener
from trac.mimeview.api import get_mimetype
from trac.wiki.model import WikiPage

class ImageAutoAppender(Component):
    implements(IAttachmentChangeListener)

    def attachment_added(self, attachment):
        if attachment.parent_realm != 'wiki':
            return
        mimetype = get_mimetype(attachment.filename)
        if not mimetype.startswith('image/'):
            return
        page = WikiPage(self.env, attachment.parent_id)
        page.text += '[[Image(%s)]]' % (attachment.filename,)
        page.save(attachment.author, 'Auto-append image', attachment.ipnr)

    def attachment_deleted(self, attachment):
        pass

    def attachment_moved(attachment, old_parent_realm, old_parent_id, old_filename):
        pass

Available Implementations

• ​th:SearchAttachmentsPlugin: Search attachments
• ​th:ImageTracPlugin: Attach a ticket image
• ​th:TracCiaPlugin: CIA integration

Additional Information and References

• ​epydoc
• ​API Reference
• See trac.attachment.IAttachmentManipulator
• See trac.ticket.api.IMilestoneChangeListener, trac.versioncontrol.api.IRepositoryChangeListener, trac.ticket.api.ITicketChangeListener, trac.wiki.api.IWikiChangeListener
• Introduced in changeset:3399
• Attachments database schema
• Related tickets:
  • attachment component
  • Generic change listener replacement: #8834, #11148, #6543
  • #1278 Listen for attachments to record wiki page change
  • #2259 Notification when adding attachment to ticket

API History

• 0.10 introduced the interface (changeset:3399)
• 0.12 added method attachment_reparented (#1106, changeset:9362)
• 1.3.2 added method attachment_moved (#12870, changeset:16160)
• 1.5.1 will remove method attachment_reparented (deprecated since #12870)