Changes between Version 3 and Version 4 of WikiMacros


Ignore:
Timestamp:
Apr 4, 2012, 2:28:19 PM (13 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiMacros

    v3 v4  
    88
    99== Using Macros ==
     10Macro calls are enclosed in two ''square brackets''. Like Python functions, macros can also have arguments, a comma separated list within parentheses.
    1011
    11 Macro calls are enclosed in two ''square brackets''. Like Python functions, macros can also have arguments, a comma separated list within parentheses.
    12 
    13 === Getting Detailed Help ===
    14 The list of available macros and the full help can be obtained using the !MacroList macro, as seen [#AvailableMacros below].
    15 
    16 A brief list can be obtained via ![[MacroList(*)]] or ![[?]].
    17 
    18 Detailed help on a specific macro can be obtained by passing it as an argument to !MacroList, e.g. ![[MacroList(MacroList)]], or, more conveniently, by appending a question mark (?) to the macro's name, like in ![[MacroList?]].
    19 
    20 
     12Trac macros can also be written as TracPlugins. This gives them some capabilities that macros do not have, such as being able to directly access the HTTP request.
    2113
    2214=== Example ===
    … …  
    2416A list of 3 most recently changed wiki pages starting with 'Trac':
    2517
    26 ||= Wiki Markup =||= Display =||
    2718{{{
    28 #!td
    29   {{{
    30   [[RecentChanges(Trac,3)]]
    31  
     19 [[RecentChanges(Trac,3)]]
    3220}}}
    33 }}}
    34 {{{
    35 #!td style="padding-left: 2em;"
    36 [[RecentChanges(Trac,3)]]
    37 }}}
    38 |-----------------------------------
    39 {{{
    40 #!td
    41   {{{
    42   [[RecentChanges?(Trac,3)]]
    43  
    44 }}}
    45 }}}
    46 {{{
    47 #!td style="padding-left: 2em;"
    48 [[RecentChanges?(Trac,3)]]
    49 }}}
    50 |-----------------------------------
    51 {{{
    52 #!td
    53   {{{
    54   [[?]]
    55  
    56 }}}
    57 }}}
    58 {{{
    59 #!td style="padding-left: 2em; font-size: 80%"
    60 [[?]]
    61 }}}
     21
     22Display:
     23 [[RecentChanges(Trac,3)]]
    6224
    6325== Available Macros ==
    … …  
    7234
    7335== Developing Custom Macros ==
    74 Macros, like Trac itself, are written in the [http://python.org/ Python programming language] and are developed as part of TracPlugins.
     36Macros, like Trac itself, are written in the [http://python.org/ Python programming language].
    7537
    7638For more information about developing macros, see the [trac:TracDev development resources] on the main project site.
    7739
     40
     41== Implementation ==
    7842
    7943Here are 2 simple examples showing how to create a Macro with Trac 0.11.
    … …  
    8246
    8347=== Macro without arguments ===
    84 To test the following code, you should saved it in a `timestamp_sample.py` file located in the TracEnvironment's `plugins/` directory.
     48It should be saved as `TimeStamp.py` as Trac will use the module name as the Macro name
    8549{{{
    8650#!python
    … …  
    9963    url = "$URL$"
    10064
    101     def expand_macro(self, formatter, name, text):
     65    def expand_macro(self, formatter, name, args):
    10266        t = datetime.now(utc)
    10367        return tag.b(format_datetime(t, '%c'))
    … …  
    10569
    10670=== Macro with arguments ===
    107 To test the following code, you should saved it in a `helloworld_sample.py` file located in the TracEnvironment's `plugins/` directory.
     71It should be saved as `HelloWorld.py` (in the plugins/ directory) as Trac will use the module name as the Macro name
    10872{{{
    10973#!python
    110 from genshi.core import Markup
    111 
    11274from trac.wiki.macros import WikiMacroBase
    11375
    … …  
    12789    url = "$URL$"
    12890
    129     def expand_macro(self, formatter, name, text, args):
     91    def expand_macro(self, formatter, name, args):
    13092        """Return some output that will be displayed in the Wiki content.
    13193
    13294        `name` is the actual name of the macro (no surprise, here it'll be
    13395        `'HelloWorld'`),
    134         `text` is the text enclosed in parenthesis at the call of the macro.
     96        `args` is the text enclosed in parenthesis at the call of the macro.
    13597          Note that if there are ''no'' parenthesis (like in, e.g.
    136           [[HelloWorld]]), then `text` is `None`.
    137         `args` are the arguments passed when HelloWorld is called using a
    138         `#!HelloWorld` code block.
     98          [[HelloWorld]]), then `args` is `None`.
    13999        """
    140         return 'Hello World, text = %s, args = %s' % \
    141             (Markup.escape(text), Markup.escape(repr(args)))
    142 
     100        return 'Hello World, args = ' + unicode(args)
     101   
     102    # Note that there's no need to HTML escape the returned data,
     103    # as the template engine (Genshi) will do it for us.
    143104}}}
    144105
    145 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. On the contrary, when called as a macro, `args` is  `None`. (''since 0.12'').
    146106
    147 For example, when writing:
     107=== {{{
     108expand_macro
     109}}} details ===
    148110{{{
    149 {{{
    150 #!HelloWorld style="polite"
    151 <Hello World!>
    152 }}}
     111expand_macro
     112}}} should return either a simple Python string which will be interpreted as HTML, or preferably a Markup object (use {{{
     113from trac.util.html import Markup
     114}}}).  {{{
     115Markup(string)
     116}}} 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 {{{
     117from trac.wiki import Formatter
     118}}}.
    153119
    154 {{{
    155 #!HelloWorld
    156 <Hello World!>
    157 }}}
    158 
    159 [[HelloWorld(<Hello World!>)]]
    160 }}}
    161 One should get:
    162 {{{
    163 Hello World, text = <Hello World!> , args = {'style': u'polite'}
    164 Hello World, text = <Hello World!> , args = {}
    165 Hello World, text = <Hello World!> , args = None
    166 }}}
    167 
    168 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`). 
    169 
    170 You can also recursively use a wiki Formatter (`from trac.wiki import Formatter`) to process the `text` as wiki markup, for example by doing:
     120If your macro creates wiki markup instead of HTML, you can convert it to HTML like this:
    171121
    172122{{{
    173123#!python
    174     text = "whatever wiki markup you want, even containing other macros"
    175     # Convert Wiki markup to HTML, new style
    176     out = StringIO()
    177     Formatter(self.env, formatter.context).format(text, out)
    178     return Markup(out.getvalue())
     124  text = "whatever wiki markup you want, even containing other macros"
     125  # Convert Wiki markup to HTML, new style
     126  out = StringIO()
     127  Formatter(self.env, formatter.context).format(text, out)
     128  return Markup(out.getvalue())
    179129}}}
    180130