Changes between Version 20 and Version 21 of TracDev/ApiChanges/0.11

Timestamp:

Jul 25, 2007, 1:47:38 PM (17 years ago)

Author:

Christopher Lenz

Comment:

Some additional notes about the timeline changes

TracDev/ApiChanges/0.11

@@ -2 +2 @@
 = !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''.'''
-
+'''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 ==
@@ -13 +11 @@
 == 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].
+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.
@@ -21 +19 @@
 == 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.
+[http://jquery.org jQuery] is included in Trac, and it is advised to use this library when writing JavaScript code.
 
 
@@ -35 +33 @@
 == 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
+=== `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`.
+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
@@ -52 +84 @@
 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].
+`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
@@ -77 +109 @@
  * {{{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}}}
-