Changes between Version 2 and Version 3 of 0.12/WikiMacros

Timestamp:

Feb 2, 2010, 5:19:22 PM (14 years ago)

Author:

Christian Boos

Comment:

document #8204

0.12/WikiMacros

@@ -68 +68 @@
 
 
-== Implementation ==
-
 Here are 2 simple examples showing how to create a Macro with Trac 0.11. 
 
@@ -75 +73 @@
 
 === Macro without arguments ===
-It should be saved as `TimeStamp.py` (in the TracEnvironment's `plugins/` directory) as Trac will use the module name as the Macro name.
+To test the following code, you should saved it in a `timestamp_sample.py` file located in the TracEnvironment's `plugins/` directory.
 {{{
 #!python
@@ -92 +90 @@
     url = "$URL$"
 
-    def expand_macro(self, formatter, name, args):
+    def expand_macro(self, formatter, name, text):
         t = datetime.now(utc)
         return tag.b(format_datetime(t, '%c'))
@@ -98 +96 @@
 
 === Macro with arguments ===
-It should be saved as `HelloWorld.py` (in the TracEnvironment's `plugins/` directory) as Trac will use the module name as the Macro name.
+To test the following code, you should saved it in a `helloworld_sample.py` file located in the TracEnvironment's `plugins/` directory.
 {{{
 #!python
+from genshi.core import Markup
+
 from trac.wiki.macros import WikiMacroBase
 
@@ -118 +118 @@
     url = "$URL$"
 
-    def expand_macro(self, formatter, name, args):
+    def expand_macro(self, formatter, name, text, args):
         """Return some output that will be displayed in the Wiki content.
 
         `name` is the actual name of the macro (no surprise, here it'll be
         `'HelloWorld'`),
-        `args` is the text enclosed in parenthesis at the call of the macro.
+        `text` is the text enclosed in parenthesis at the call of the macro.
           Note that if there are ''no'' parenthesis (like in, e.g.
-          [[HelloWorld]]), then `args` is `None`.
+          [[HelloWorld]]), then `text` is `None`.
+        `args` are the arguments passed when HelloWorld is called using a
+        `#!HelloWorld` code block.
         """
-        return 'Hello World, args = ' + unicode(args)
-    
-    # Note that there's no need to HTML escape the returned data,
-    # as the template engine (Genshi) will do it for us.
+        return 'Hello World, text = %s, args = %s' % \
+            (Markup.escape(text), Markup.escape(repr(args)))
+
 }}}
 
+Note that `expand_macro` optionally takes a 4^th^ parameter ''`args`''. When the macro is called as a [WikiProcessors WikiProcessor], it's also possible to pass `key=value` [WikiProcessors#UsingProcessors processor parameters]. If given, those are stored in a dictionary and passed in this extra `args` parameter (''since 0.12'').
 
-=== {{{expand_macro}}} details ===
-{{{expand_macro}}} should return either a simple Python string which will be interpreted as HTML, or preferably a Markup object (use {{{from trac.util.html import Markup}}}).  {{{Markup(string)}}} just annotates the string so the renderer will render the HTML string as-is with no escaping. You will also need to import Formatter using {{{from trac.wiki import Formatter}}}.
+'''FIXME''' when called as a macro, `args` should be `None`.
 
-If your macro creates wiki markup instead of HTML, you can convert it to HTML like this:
+For example, when writing:
+{{{
+{{{#!HelloWorld style="polite"
+<Hello World!>
+}}}
+
+{{{#!HelloWorld
+<Hello World!>
+}}}
+
+[[HelloWorld(<Hello World!>)]]
+}}}
+One should get:
+{{{
+Hello World, text = <Hello World!> , args = {'style': u'polite'}
+Hello World, text = <Hello World!> , args = {}
+Hello World, text = <Hello World!> , args = None
+}}}
+
+Note that the return value of `expand_macro` is '''not''' HTML escaped. Depending on the expected result, you should escape it by yourself (using `return Markup.escape(result)`) or, if this is indeed HTML, wrap it in a Markup object (`return Markup(result)`) with `Markup` coming from Genshi, (`from genshi.core import Markup`).  
+
+You can also recursively use a wiki Formatter (`from trac.wiki import Formatter`) to process the `text` as wiki markup, for example by doing:
 
 {{{
 #!python
-  text = "whatever wiki markup you want, even containing other macros"
-  # Convert Wiki markup to HTML, new style
-  out = StringIO()
-  Formatter(self.env, formatter.context).format(text, out)
-  return Markup(out.getvalue())
+    text = "whatever wiki markup you want, even containing other macros"
+    # Convert Wiki markup to HTML, new style
+    out = StringIO()
+    Formatter(self.env, formatter.context).format(text, out)
+    return Markup(out.getvalue())
 }}}