TracDev/ApiChanges/0.11

Note: Development of Trac 0.11 has started with r3804 and the trunk now uses ​Genshi instead of ClearSilver, for its template engine. Nevertheless, you should have in mind that the information in this page corresponds to a work in progress.

Caveats for Plugin Developers

The Trac macros will need to be adapted:

• the old-style wiki-macros are not supported anymore (due to the drop of ClearSilver and the HDF); they need to be converted to the new-style macros

Migrating away from Clearsilver

ClearSilver has proven a bit uncomfortable to work with, and search for better alternatives were done a few months ago. The ​Kid templating language was unanimously found appealing, to the point cmlenz did a porting of Trac to Kid, during the DrProject fork. This in turn was found painful, and prompted Christopher to start his own, enhanced, version of Kid currently maturing as ​Genshi.

The migration from ClearSilver to Genshi was done on trunk in r3832.

You can start porting your plugins from Clearsilver to Genshi.

Advanced JavaScript Support

​jQuery 1.1.1 is included in Trac, and it is advised to use this library when writing JavaScript code.

Date and Time Manipulations

Since r3935, Trac uses datetime objects internally, instead of timestamps. More precisely, the database layer still uses int timestamps, but manipulation of time values is now done on datetime objects as soon as possible, see e.g. the Timeline module.

Those datetime values are directly added by the controllers to the data model, and it's the responsibility of the templates to pick up the appropriate time representation, using one of the built-in date formatting utilities: format_date, format_datetime, http_date, pretty_timedelta (see chrome.py), or even the $dateinfo() macro.

Those utilities automatically take into account the timezone information set by the user, so that the dates are presented in a meaningful way to him.

Interface Changes

ITimelineEventProvider ^{(0.11)​ (0.10)}

First thing, the timeline module has now its own package (trac.timeline), so the ITimelineEventProvider interface itself should now be imported from trac.timeline.api.

Then, the return type for the get_timeline_events event has changed. It can now be a TimelineEvent object instead of a tuple, though the tuple return value will still be supported for compatibility reasons in 0.11.

Note: support for #1198 and #2293 will likely require adding other methods to that interface

IWikiMacroProvider ^{(0.11)​ (0.10)​}

• render_macro(req, name, content) has been deprecated (see r4621)

• expand_macro(formatter, name, content) has been added and supersedes render_macro.

The req was not enough for most of the macros, which needed to resort to various hacks to get more information about the formatting at work. The more adequate formatter object is now provided instead. The req object can still be obtained from the formatter, with formatter.req. Better yet, the formatter now always know about the WikiContext in which it operates (use formatter.context to retrieve it). The context object provides the information about the Trac resource which "owns" the text being processed.

render_macro(req, name, content) will removed in 0.12.

IHTMLPreviewRenderer ^{(0.11)​ (0.10)​}

Similar to the above change, render(req, mimetype ...) is now render(context, mimetype ...). It doesn't matter that much however, as it looks like that this interface is going to be integrated in IContentConverter anyway (see #3332).

New Interfaces

Several new interfaces have been added in 0.11.

IPropertyRenderer ^(0.11)​

The presentation of version control properties for files and directories can be customized to a great extent. The revision properties can be customized in a similar way.

IPropertyDiffRenderer ^(0.11)​

Likewise, the presentation of changes for version control properties can be customized.

Renaming

[This section could probably be done better, but I figure getting the info in here is better than having it left out]

• webadmin.web_ui.IAdminPageProvider → trac.admin.api.IAdminPanelProvider. Also its get_admin_pages method became get_admin_panels.
• some module names, such as trac.Timeline and trac.Search, were de-capitalized, e.g. trac.timeline