Edgewall Software

Extension Point : ITicketChangeListener

InterfaceITicketChangeListenerSince0.10
Moduletrac.ticket.apiSourceapi.py

The ITicketChangeListener allows components to listen for and to react to ticket events.

Purpose

The Trac ticket system provides simple but effective tracking of issues and bugs. Plugins can hook into the tickets module to trigger their own actions when tickets are created, deleted, changed etc.

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

(For ticket validation and manipulation use ITicketManipulator instead.)

Usage

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

When a user creates a new ticket the ticket_created method is called. Similarly methods are called when a user deletes a ticket (ticket_deleted), changes some ticket properties and / or comments on a ticket (ticket_changed), edits an existing ticket comment (ticket_comment_modified) or deletes / reverts a property change or comment (ticket_change_deleted).

The Ticket data can as always be accessed by indexing (e.g. ticket['reporter'], ticket['milestone'] etc.). In ticket_changed the changed properties are also available (e.g. in old_values['reporter']).

Examples

The following minimal example ITicketChangeListener implementation arbitrarily defines the criteria as editing five properties at once without (butcher) or with (gnome) a comment:

from trac.core import Component, implements
from trac.ticket.api import ITicketChangeListener
from trac.wiki.model import WikiPage

class TicketButcherTicketGnomeAchievements(Component):
    implements(ITicketChangeListener)

    def ticket_created(self, ticket):
        pass

    def ticket_changed(self, ticket, comment, author, old_values):
        if len(old_values) >= 5:
            if comment:
                self._unlock_achievement(author, 'TicketGnome')
            else:
                self._unlock_achievement(author, 'TicketButcher')

    def ticket_deleted(self, ticket):
        pass

    def ticket_comment_modified(self, ticket, cdate, author, comment, old_comment):
        pass

    def ticket_change_deleted(self, ticket, cdate, changes):
        pass

    def _unlock_achievement(self, user, name):
        page = WikiPage(self.env, name)
        page.text += ' * %s\n' % (user,)
        page.save(user, 'Achievement unlocked', None)

Save it as TicketButcherTicketGnomeAchievementsPlugin.py in the environment plugins directory and restart TracStandalone or your web server. See TracPlugins for more information.

Available Implementations

Additional Information and References

API History

  • 0.10 introduced the interface (changeset:3145, #2176, #3029)
    • Parameter author was added to ticket_changed (#3520)
  • 1.0.2 added ticket_comment_modified and ticket_change_deleted methods (#11377)
    • Note: Not available in 1.1.1
Last modified 3 years ago Last modified on Feb 3, 2016, 11:20:01 PM
Note: See TracWiki for help on using the wiki.