Extension Point : ITimelineEventProvider

Interface	ITimelineEventProvider	Since	0.9
Module	trac.timeline.api	Source	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 TracDev/ComponentArchitecture and of course 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.

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

• ​epydoc
• ​API Reference

API History

• 0.9 introduced the interface
• 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.