== Extension Point : ''ITimelineEventProvider'' ==

||'''Interface'''||''ITimelineEventProvider''||'''Since'''||0.9||
||'''Module'''||''trac.timeline.api''||'''Source'''||[source:trunk/trac/timeline/api.py#/ITimelineEventProvider api.py]||

The ''ITimelineEventProvider'' allows components to provide events listed in the TracTimeline.

== Purpose ==
The timeline provides a historic view of the project in a single report. It lists all Trac events that have occurred in chronological order, a brief description of each event and if applicable, the person responsible for the change. Plugins can hook into the timeline system to extend the set of events that can be viewed.

The main purpose for this interface is to allow plugins to query any source (e.g. new DB tables) for such new event types (e.g. for changes of new resources).

== Usage ==

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

Trac automatically calls the `get_timeline_filters` method to retrieve a list of filters displayed in the option panel.

Trac then calls `get_timeline_events` to query the set of events of a given filter in the selected time frame.

Finally `render_timeline_event` is called for each event field separately.

== Examples ==

The following example uses the pypi:feedparser library to parse the RSS feed of the ''Trac-Announce'' MailingList.

{{{#!python
import feedparser

from genshi.builder import tag

from trac.core import Component, implements
from trac.timeline.api import ITimelineEventProvider
from trac.util.datefmt import parse_date


class TracAnnounceFeedTimelineProvider(Component):
    implements(ITimelineEventProvider)

    url = 'https://groups.google.com/forum/feed/trac-announce/msgs/rss_v2_0.xml?num=50'

    def get_timeline_filters(self, req):
        yield 'trac-announce-feed', "Trac announcements"

    def get_timeline_events(self, req, start, stop, filters):
        if 'trac-announce-feed' in filters:
            feed = feedparser.parse(self.url)
            for post in feed.entries:
                date = parse_date(post.published)
                if start <= date and date <= stop:
                    yield 'feed-event', date, post.author, post

    def render_timeline_event(self, context, field, event):
        post = event[3]
        if field == 'url':
            return post.links[0]['href']
        elif field == 'title':
            return tag.em(post.title)
        elif field == 'description':
            return post.summary
}}}

== Available Implementations ==

* `trac.ticket.roadmap.MilestoneModule`: Provides ''milestone completed'' and ''milestone attachment'' events.
* `trac.ticket.web_ui.TicketModule`: Provides ''ticket opened'' and ''closed'', ''ticket updated'' and ''ticket attachment'' events.
* `trac.versioncontrol.web_ui.changeset.ChangesetModule`: Provides ''changeset'' events.
* `trac.wiki.web_ui.WikiModule`: Provides ''wiki page changed'' and ''wiki page attachment'' events.

* th:FullBlogPlugin: Provides ''new blog post'', ''blog comment'' and ''blog attachment'' events.
* th:DiscussionPlugin: Provides ''new forum'', ''new discussion'' and ''new reply'' events.
* th:DownloadsPlugin: Provides ''new download'' events.
* th:ScreenshotsPlugin: Provides ''new screenshot'' events.
* th:PeerReviewPlugin: Provides ''new code review'' events.
* th:ExoWebCodeReviewPlugin: Provides ''code review created'', ''edited'' and ''completed'' events.
* th:TracPastePlugin: Provides ''pastebin change'' events.
* th:SensitiveTicketsPlugin: Provides ''sensitive ticket'' events (only to users with relevant permissions).
* th:WorkLogPlugin: Provides ''work started'' and ''ended'' events.
* th:BambooTracPlugin: Provides ''Bamboo build successful'' and ''failed'' events.
* th:TeamcityPluginIntegration: Provides ''Teamcity build successful'' and ''failed'' events.
* th:LuntbuildTracIntegration: Provides ''Luntbuild build successful'' and ''failed'' events.

== Additional Information and References ==

 * [apiref:trac.timeline.api.ITimelineEventProvider-class epydoc]
 * [apidoc:api/trac_timeline_api#trac.timeline.api.ITimelineEventProvider API Reference]

=== API History
 * 0.9 introduced the interface
 * [wiki:TracDev/ApiChanges/0.11#ITimelineEventProvider 0.11] changed the interface considerably
    * Moved to the `trac.timeline` (all lowercase) package.
    * Changed `start` and `stop` arguments to `datetime` objects.
    * Changed return value to tuple with `data` dictionary.
    * Introduced `render_timeline_event()` method.