== Extension Point : ''IAttachmentChangeListener'' ==

||'''Interface'''||''IAttachmentChangeListener''||'''Since'''||0.10||
||'''Module'''||''trac.attachment''||'''Source'''||[source:trunk/trac/attachment.py#/IAttachmentChangeListener 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 reparented (i.e. moved to another parent resource or with a renamed parent resource).

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 [../trac.attachment.IAttachmentManipulator IAttachmentManipulator] instead.)

== Usage ==

Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki: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_reparented` is called when a user moves an attachment to a new parent resource or renames 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 [wiki:WikiMacros#Image-macro Image macro] to the wiki page.
The following minimal example IAttachmentChangeListener implementation could implement such a feature:
{{{#!python
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_reparented(self, attachment, old_parent_realm, old_parent_id):
        pass
}}}

== Available Implementations ==

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

== Additional Information and References ==

 * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.attachment.IAttachmentChangeListener-class.html epydoc]
 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_attachment.html#trac.attachment.IAttachmentChangeListener API Reference]
 * See [../trac.attachment.IAttachmentManipulator trac.attachment.IAttachmentManipulator]
 * See [../trac.ticket.api.IMilestoneChangeListener trac.ticket.api.IMilestoneChangeListener], [../trac.versioncontrol.api.IRepositoryChangeListener trac.versioncontrol.api.IRepositoryChangeListener],  [../trac.ticket.api.ITicketChangeListener trac.ticket.api.ITicketChangeListener], [../trac.wiki.api.IWikiChangeListener trac.wiki.api.IWikiChangeListener]
 * Introduced in changeset:3399
 * [TracDev/DatabaseSchema/Attachments Attachments database schema]
 * Related tickets:
  * [query:status!=closed&component=attachment attachment component]
  * Generic change listener replacement: #8834, #11148
  * #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)