[[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. Please keep in mind that the information in this page is 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 too limited and “uncomfortable”, so research for better alternatives was done. The [http://kid-templating.org/ Kid] templating language was unanimously found appealing, to the point that ChristopherLenz did a port of Trac to Kid during the development of DrProject (a fork of Trac). 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.com jQuery] 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`), and the ITimelineEventProvider interface itself should now be imported from `trac.timeline`. However, note that the case has changed here, as you would previously have imported `trac.Timeline`. If you want to support both versions, try something like this:

{{{
#!python
try:
    from trac.timeline import ITimelineEventProvider
except ImportError:
    from trac.Timeline import ITimelineEventProvider
}}}

Also note that the `start` and `stop` arguments to the `get_timeline_events` method are now `datetime` objects where they previously were floats/ints. Again, if you want to support both Trac 0.11 and previous versions, use something like the following code:

{{{
#!python
def get_timeline_events(self, req, start, stop, filters):
    if isinstance(start, datetime): # Trac>=0.11
        from trac.util.datefmt import to_timestamp
        start = to_timestamp(start)
        stop = to_timestamp(stop)
    ...
}}}

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.

(Please note that this API hasn't been 100% agreed on yet, so you probably want to stick to just returning tuples for now.)

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

=== `ISearchSource` ^[source:trunk/trac/search/api.py@head#L17 (0.11)] [source:tags/trac-0.10/trac/search.py@head#L30 (0.10)]^ === #ISearchSource

Similar to the timeline package, the search module has also been migrated to a package (`trac.search`), with the same case change. Again, if you want to support both versions, try something like this:

{{{
#!python
try:
    from trac.search import ISearchSource
except ImportError:
    from trac.Search import ISearchSource
}}}

=== `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 likely be 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}}}