Version 23 (modified by 17 years ago) ( diff ) | ,
---|
- Caveats for Plugin Developers
- Migrating away from Clearsilver
- Advanced JavaScript Support
- Date and Time Manipulations
- Interface Changes
-
New Interfaces, Modules and Classes
-
trac.resource.Resource
-
trac.resource.IResourceManager
-
trac.mimeview.api.Context
-
trac.perm.IPermissionPolicy
-
trac.ticket.api.ITicketActionController
-
trac.ticket.roadmap.ITicketGroupStatsProvider
-
trac.web.ITemplateStreamFilter
-
trac.prefs.api.IPreferencePanelProvider
-
IPropertyRenderer
… -
IPropertyDiffRenderer
… - WebAdmin is now part of the core
-
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. 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 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.
Advanced JavaScript Support
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 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
), 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 supersedesrender_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 atrac.resource.Resource
, see below),formatter.context
is the rendering context in which this wiki formatting takes place (this is atrac.mimeview.api.Context
, see below)formatter.perm
the permission cache which can be used in order to perform fine-grained permission checks (this is atrac.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 Interfaces, Modules and Classes
Several new interfaces and modules have been added in 0.11.
TODO document the various new trac.util modules.
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.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.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).
trac.perm.IPermissionPolicy
TBD.
trac.ticket.api.ITicketActionController
TBD. See TracWorkflow.
trac.ticket.roadmap.ITicketGroupStatsProvider
TBD.
trac.web.ITemplateStreamFilter
TBD.
trac.prefs.api.IPreferencePanelProvider
TBD.
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.
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 itsget_admin_pages
method becameget_admin_panels
.