Edgewall Software

Extension Point : ITimelineEventProvider

InterfaceITimelineEventProviderSince0.9
Moduletrac.timeline.apiSourceapi.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.

Additional Information and References

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.
Last modified 10 years ago Last modified on Nov 9, 2014, 1:04:40 PM
Note: See TracWiki for help on using the wiki.