TracDev/ApiChanges/0.11

Note: Development of Trac 0.11 has started with r3804 and now at r6160 it has reached some stability. We're considering releasing a beta 1 soon. Please keep in mind that the information in this page is still work in progress (most notably the sections marked with TBD).

New Dependencies

Genshi

ClearSilver has proven too limited and “uncomfortable”, so research for better alternatives was done. The ​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 ​Genshi.

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

You can start porting your plugins from Clearsilver to Genshi.

jQuery

Advanced JavaScript Support

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

Modifications made to the 0.10 API

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.

Caveats for Macros 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
• new-style macros are #IWikiMacroProvider plugins. They can be written as full plugins or simple one file drop-in plugins, see source:trunk/sample-plugins for some examples (TODO source:tags/trac-0.11/sample-plugins/macros)

Modified Interfaces

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

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:

try:
    from trac.timeline.api 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:

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. Instead of a 6-tuple (kind, href, title, date, author, markup) (which still supported for compatibility reasons in 0.11), the returned value can now be a 4 or 5-tuple (kind, date, author, data[, provider]), which is far more flexible than before, especially because the data can be anything that will be used by a new render_timeline_event(context, field, event) method called when actually displaying the events.

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

ISearchSource ^{(0.11)​ (0.10)}

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:

try:
    from trac.search import ISearchSource
except ImportError:
    from trac.Search import ISearchSource

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 pertinent formatter object is now provided instead. The req object can still be obtained from the formatter, with formatter.req, but this is going to be deprecated. Instead, you should access to the following set of information:

• formatter.resource is the resource identifier which owns the text being formatted (this is a trac.resource.Resource, see below),
• formatter.context is the rendering context in which this wiki formatting takes place (this is a trac.mimeview.api.Context, see below)
• formatter.perm the permission cache which can be used in order to perform fine-grained permission checks (this is a trac.perm.PermissionCache).

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

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

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

New in the 0.11 API

Several new interfaces and modules have been added in 0.11.

TODO document the various new trac.util modules.

New Classes

trac.resource.Resource

The resource identifier class Resource is used to specify in a convenient way which Trac resources is being manipulated. A Trac resource is mostly anything in Trac that can be addressed with its own URL and to which some content is attached. A resource is mainly identified by a realm string and an id string or a number. Also, a version can be specified in a Resource object, in order to refer to the content of a resource at a particular moment of its history. A version specification of None simply refers to the latest version of the resource. Finally, a resource can be parented in another resource. This relationship usually means that a removal of the parent resource implies a removal of the children resources.

trac.mimeview.api.Context

The rendering context class is used to specify how the content should be rendered. It holds together all the needed contextual information that will be needed by individual renderer components. It is notably hodling together a Resource identifier for specifying the owning resource of the content being rendered, a PermissionCache for restricting the display of information to the authorized parts only and an Href object that can be used for creating links. Also, Context can be parented and this relationship usually correspond to some kind of embedding of the data (typical example, ticket information displayed within a Wiki page by the way of a macro).

New Interfaces

trac.resource.IResourceManager

The IResourceManager let components claim ownership of some realms. For the managed realms, the manager component will know how to build URLs to access the resources belonging to that realm and will know how to describe those resources. Various utility functions exist in the trac.resource module in order to manipulate the Resource identifier objects in a generic way.

trac.perm.IPermissionPolicy ^(0.11)​

The IPermissionPolicy components can be used to grant or reject any kind of permissions, based on the identity of the user and the targeted resource, subject of the action. The API is conceptually simple, as the permission policies are chained (using the sequence defined in the [trac] permission_policies configuration entry), and the first policy in the chain which makes a decision about the given (action, user, resource) triple wins. Making a decision consist in returning True for allowing the action, False for rejecting the action. None can also be returned to let the next policy in the chain decide. If no decision has been made in the end, the action is not allowed.

Look at the API documentation for a few more details (what to return when no resource or a "realm" resource is specified, usage of the permission cache).

trac.attachment.ILegacyAttachmentDelegate ^(0.11)​

This interface is mostly like the above IPermissionPolicy one, except that it enables attachment providers to hook automatically into the default legacy attachment policy, which is already enabled by default.

trac.ticket.api.ITicketActionController

TBD. See TracWorkflow.

trac.ticket.roadmap.ITicketGroupStatsProvider

TBD.

trac.web.ITemplateStreamFilter

TBD.

trac.prefs.api.IPreferencePanelProvider

TBD.

trac.versioncontrol.web_ui.browser.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.

trac.versioncontrol.web_ui.changeset.IPropertyDiffRenderer ^(0.11)​

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

trac.admin.api.IAdminPanelProvider

WebAdmin is now part of the core. The previously external interface webadmin.web_ui.IAdminPageProvider is now a core interface: trac.admin.api.IAdminPanelProvider. Also its get_admin_pages method became get_admin_panels.