| | 1 | == Extension Point : ''IMilestoneChangeListener'' == |
| | 2 | |
| | 3 | ||'''Interface'''||''IMilestoneChangeListener''||'''Since'''||[wiki:TracDev/ApiChanges/0.12#IMilestoneChangeListener 0.12]|| |
| | 4 | ||'''Module'''||''trac.ticket.api''||'''Source'''||[source:trunk/trac/ticket/api.py#/IMilestoneChangeListener api.py]|| |
| | 5 | |
| | 6 | The ''IMilestoneChangeListener'' allows components to listen for and to react to milestone events. |
| | 7 | |
| | 8 | == Purpose == |
| | 9 | |
| | 10 | The [TracRoadmap Trac milestone system] helps planning and managing the future development of a project. Plugins can hook into the milestone system to trigger their own actions when milestones are created, deleted or changed. |
| | 11 | |
| | 12 | The main purpose for this interface is to allow plugins to stay informed about the existing milestones and trigger appropriate actions elsewhere (e.g. sending notifications, starting indexing services, updating supplementary data structures etc.) |
| | 13 | |
| | 14 | == Usage == |
| | 15 | |
| | 16 | Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment]. |
| | 17 | |
| | 18 | When a user creates a new milestone the `milestone_created` method is called. Similarly methods are called when a user deletes a milestone (`milestone_deleted`) or changes some milestone properties (`milestone_changed`). |
| | 19 | |
| | 20 | The milestone model object is passed to each handler. So the milestone properties can be accessed as usual (i.e. `milestone.name`, `milestone.due`, `milestone.completed`, `milestone.description`) and the milestone can be updated etc. |
| | 21 | |
| | 22 | In `milestone_changed` the changed properties are available by indexing e.g. `old_values['name']`. |
| | 23 | |
| | 24 | == Examples == |
| | 25 | |
| | 26 | See [source:trunk/sample-plugins/milestone_to_version.py MilestoneToVersion] sample plugin. |
| | 27 | |
| | 28 | == Available Implementations == |
| | 29 | |
| | 30 | * [source:trunk/sample-plugins/milestone_to_version.py MilestoneToVersion] sample plugin |
| | 31 | |
| | 32 | == Additional Information and References == |
| | 33 | |
| | 34 | * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.ticket.api.IMilestoneChangeListener-class.html epydoc] |
| | 35 | * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_ticket_api.html#trac.ticket.api.IMilestoneChangeListener API Reference] |
| | 36 | * See [../trac.ticket.api.ITicketChangeListener trac.ticket.api.ITicketChangeListener], [../trac.versioncontrol.api.IRepositoryChangeListener trac.versioncontrol.api.IRepositoryChangeListener], [../trac.attachment.IAttachmentChangeListener trac.attachment.IAttachmentChangeListener], [../trac.wiki.api.IWikiChangeListener trac.wiki.api.IWikiChangeListener] |
| | 37 | * [TracDev/DatabaseSchema/TicketSystem#Tablemilestone Milestone database schema] |
| | 38 | * Related tickets: |
| | 39 | * Generic change listener replacement: #8834, #11148, #6543, Trac-dev:7737 |
| | 40 | * This interface has also been implemented [changeset:4846 twice] [changeset:4913 before] in a branch but got [changeset:4942 removed] before merging. |
| | 41 | |
| | 42 | === API History |
| | 43 | * [wiki:TracDev/ApiChanges/0.12#IMilestoneChangeListener 0.12] introduced the interface (changeset:8828, #6543) |
