Changes between Version 4 and Version 5 of WikiMacros


Ignore:
Timestamp:
Apr 13, 2010, 3:53:03 AM (10 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiMacros

    v4 v5  
    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 =||
    27 {{{#!td
    28   {{{
    29   [[RecentChanges(Trac,3)]]
    30   }}}
     18{{{
     19 [[RecentChanges(Trac,3)]]
    3120}}}
    32 {{{#!td style="padding-left: 2em;"
    33 [[RecentChanges(Trac,3)]]
    34 }}}
    35 |-----------------------------------
    36 {{{#!td
    37   {{{
    38   [[RecentChanges?(Trac,3)]]
    39   }}}
    40 }}}
    41 {{{#!td style="padding-left: 2em;"
    42 [[RecentChanges?(Trac,3)]]
    43 }}}
    44 |-----------------------------------
    45 {{{#!td
    46   {{{
    47   [[?]]
    48   }}}
    49 }}}
    50 {{{#!td style="padding-left: 2em; font-size: 80%"
    51 [[?]]
    52 }}}
     21
     22Display:
     23 [[RecentChanges(Trac,3)]]
    5324
    5425== Available Macros ==
     
    6334
    6435== Developing Custom Macros ==
    65 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].
    6637
    6738For more information about developing macros, see the [trac:TracDev development resources] on the main project site.
    6839
     40
     41== Implementation ==
    6942
    7043Here are 2 simple examples showing how to create a Macro with Trac 0.11.
     
    7346
    7447=== Macro without arguments ===
    75 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
    7649{{{
    7750#!python
     
    9063    url = "$URL$"
    9164
    92     def expand_macro(self, formatter, name, text):
     65    def expand_macro(self, formatter, name, args):
    9366        t = datetime.now(utc)
    9467        return tag.b(format_datetime(t, '%c'))
     
    9669
    9770=== Macro with arguments ===
    98 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
    9972{{{
    10073#!python
    101 from genshi.core import Markup
    102 
    10374from trac.wiki.macros import WikiMacroBase
    10475
     
    11889    url = "$URL$"
    11990
    120     def expand_macro(self, formatter, name, text, args):
     91    def expand_macro(self, formatter, name, args):
    12192        """Return some output that will be displayed in the Wiki content.
    12293
    12394        `name` is the actual name of the macro (no surprise, here it'll be
    12495        `'HelloWorld'`),
    125         `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.
    12697          Note that if there are ''no'' parenthesis (like in, e.g.
    127           [[HelloWorld]]), then `text` is `None`.
    128         `args` are the arguments passed when HelloWorld is called using a
    129         `#!HelloWorld` code block.
     98          [[HelloWorld]]), then `args` is `None`.
    13099        """
    131         return 'Hello World, text = %s, args = %s' % \
    132             (Markup.escape(text), Markup.escape(repr(args)))
    133 
     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.
    134104}}}
    135105
    136 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'').
    137106
    138 For example, when writing:
    139 {{{
    140 {{{#!HelloWorld style="polite"
    141 <Hello World!>
    142 }}}
     107=== {{{expand_macro}}} details ===
     108{{{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}}}.
    143109
    144 {{{#!HelloWorld
    145 <Hello World!>
    146 }}}
    147 
    148 [[HelloWorld(<Hello World!>)]]
    149 }}}
    150 One should get:
    151 {{{
    152 Hello World, text = <Hello World!> , args = {'style': u'polite'}
    153 Hello World, text = <Hello World!> , args = {}
    154 Hello World, text = <Hello World!> , args = None
    155 }}}
    156 
    157 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`). 
    158 
    159 You can also recursively use a wiki Formatter (`from trac.wiki import Formatter`) to process the `text` as wiki markup, for example by doing:
     110If your macro creates wiki markup instead of HTML, you can convert it to HTML like this:
    160111
    161112{{{
    162113#!python
    163     text = "whatever wiki markup you want, even containing other macros"
    164     # Convert Wiki markup to HTML, new style
    165     out = StringIO()
    166     Formatter(self.env, formatter.context).format(text, out)
    167     return Markup(out.getvalue())
     114  text = "whatever wiki markup you want, even containing other macros"
     115  # Convert Wiki markup to HTML, new style
     116  out = StringIO()
     117  Formatter(self.env, formatter.context).format(text, out)
     118  return Markup(out.getvalue())
    168119}}}

Search

Context Navigation

ZOO Sponsors

http://www.zoo-project.org/trac/chrome/site/img/geolabs-logo.pnghttp://www.zoo-project.org/trac/chrome/site/img/neogeo-logo.png http://www.zoo-project.org/trac/chrome/site/img/apptech-logo.png http://www.zoo-project.org/trac/chrome/site/img/3liz-logo.png http://www.zoo-project.org/trac/chrome/site/img/gateway-logo.png

Become a sponsor !

Knowledge partners

http://www.zoo-project.org/trac/chrome/site/img/ocu-logo.png http://www.zoo-project.org/trac/chrome/site/img/gucas-logo.png http://www.zoo-project.org/trac/chrome/site/img/polimi-logo.png http://www.zoo-project.org/trac/chrome/site/img/fem-logo.png http://www.zoo-project.org/trac/chrome/site/img/supsi-logo.png http://www.zoo-project.org/trac/chrome/site/img/cumtb-logo.png

Become a knowledge partner

Related links

http://zoo-project.org/img/ogclogo.png http://zoo-project.org/img/osgeologo.png