Changes between Version 2 and Version 3 of TracDev/ApiChanges/0.10

Timestamp:

Aug 30, 2006, 3:49:55 PM (18 years ago)

Author:

Christian Boos

Comment:

Introduce the new trac.util.html.Element API

TracDev/ApiChanges/0.10

@@ -3 +3 @@
 
 This page is aimed to help plugin developers to port their 0.9 plugin to Trac 0.10.
+Most of the initial examples are coming from the migration of the [trachacks:DoxygenPlugin] (#TH662).
 
 == General Changes ==
@@ -45 +46 @@
 By using the [WikiMacros#TracIni-macro TracIni(doxygen)] macro, you'll get the documentation for all your settings.
 
+=== New API for Generating HTML fragments ===
+
+Since Trac [milestone:0.9.3], the generation of HTML using ClearSilver has been modified so that by default, every string content will get HTML-escaped (e.g. "<br />" replaced by "&lt;br /&gt;").
+Most plugin developers discovered this change the hard way ;)
+The recommended way for avoiding this escaping was to wrap the strings containing markup in a `Markup` instance.
+While this is still valid in 0.10, you should note that `Markup` is now defined in the `trac.util.html` module, though importing from `trac.util` will still work.
+
+More importantly, there's now a new way to programmatically generate markup content, using the `html` object, also defined in that `trac.util.html` module.
+That object will dynamically generate `Element` objects, that can be nested.
+The way to use it is:
+{{{
+  html.<elementname>(*other_elements_or_strings, **attributes)
+}}}
+
+Example: (from the [trachacks:DoxygenPlugin])
+{{{
+#!diff
+--- a/doxygentrac/doxygentrac.py        Tue Aug 29 14:05:15 2006 +0200
++++ b/doxygentrac/doxygentrac.py        Wed Aug 30 14:35:12 2006 +0200
+@@ -40,43 +69,36 @@ class DoxygenPlugin(Component):
+ 
+     def get_active_navigation_item(self, req):
+         return 'doxygen'
++
+     def get_navigation_items(self, req):
+         if req.perm.has_permission('DOXYGEN_VIEW'):
+-            # Get config variables.
+-            title = self.env.config.get('doxygen', 'title', 'Doxygen')
+-
+             # Return mainnav buttons.
+-            yield 'mainnav', 'doxygen', Markup('<a href="%s">%s</a>' % \
+-              (self.env.href.doxygen() + '/', title))
++            yield 'mainnav', 'doxygen', \
++                  html.a(self.title, href=req.href.doxygen())
+}}}
+
+For more details, refer to the [source:trunk/trac/util/html.py@head#L324 Element] docstring.
+
 
 == Interface Changes ==
@@ -52 +91 @@
 The `get_search_results(self, req, terms, filters)` now takes a list of `terms` instead of the full `query`, as it used to do for its second argument.
 
-Example: [trachacks:DoxygenPlugin]
+Example: (from the [trachacks:DoxygenPlugin])
 {{{
 #!diff