[[PageOutline(2-4)]]
= !TracDev/ApiChanges/0.11 =

'''Note: Development of Trac [milestone:0.11] has started with r3804 and the trunk now uses ''[http://genshi.edgewall.org/ 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 [http://kid-templating.org/ 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 [http://genshi.edgewall.org/ Genshi].

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

You can start porting your plugins [TracDev/PortingFromClearSilverToGenshi from Clearsilver to Genshi].

== Advanced JavaScript Support ==

[http://jquery.org 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 [source:trunk/trac/Timeline.py 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 [source:trunk/trac/chrome.py 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` ^[source:trunk/trac/timeline/api.py@head#L87 (0.11)] [source:tags/trac-0.10/trac/timeline.py@head#L32 (0.10)]^ === #ITimelineEventProvider

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` ^[source:trunk/trac/wiki/api.py@head#L73 (0.11)] [source:tags/trac-0.10/trac/wiki/api.py@head#L70 (0.10)]^ === #IWikiMacroProvider

 - `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 [milestone:0.12].

=== `IHTMLPreviewRenderer` ^[source:trunk/trac/wiki/api.py@head#L213 (0.11)] [source:tags/trac-0.10/trac/wiki/api.py@head#L209 (0.10)]^ === #IHTMLPreviewRenderer

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` ^[source:trunk/trac/versioncontrol/web_ui/browser.py@head#L46 (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` ^[source:trunk/trac/versioncontrol/web_ui/changeset.py@head#L51 (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}}}
 * {{{IAdminConsoleProvider}}} is gone, to who knows where?