Changes between Version 4 and Version 5 of WikiMacros


Ignore:
Timestamp:
Sep 10, 2014, 10:00:04 PM (7 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiMacros

    v4 v5  
    33[[PageOutline]]
    44
    5 Trac macros are plugins to extend the Trac engine with custom 'functions' written in Python. A macro inserts dynamic HTML data in any context supporting WikiFormatting.
     5Trac macros are plugins to extend the Trac engine with custom 'functions' written in Python. A macro inserts dynamic HTML data in any context supporting WikiFormatting. Its syntax is `[[macro-name(optional-arguments)]]`.
    66
    7 Another kind of macros are WikiProcessors. They typically deal with alternate markup formats and representation of larger blocks of information (like source code highlighting).
     7The WikiProcessors are another kind of macros. They typically deal with alternate markup formats and transformation of larger "blocks" of information (like source code highlighting). They are used for processing the multiline `{{{#!wiki-processor-name ... }}}` blocks.
    88
    99== Using Macros ==
     
    1414The list of available macros and the full help can be obtained using the !MacroList macro, as seen [#AvailableMacros below].
    1515
    16 A brief list can be obtained via ![[MacroList(*)]] or ![[?]].
     16A brief list can be obtained via `[[MacroList(*)]]` or `[[?]]`.
    1717
    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?]].
     18Detailed 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?]]`.
    1919
    2020
     
    4848  }}}
    4949}}}
    50 {{{#!td style="padding-left: 2em; font-size: 80%"
    51 [[?]]
     50{{{#!td style="padding-left: 2em"
     51{{{#!html
     52<div style="font-size: 80%" class="trac-macrolist">
     53<h3><code>[[Image]]</code></h3>Embed an image in wiki-formatted text.
     54
     55The first argument is the file …
     56<h3><code>[[InterTrac]]</code></h3>Provide a list of known <a class="wiki" href="/wiki/InterTrac">InterTrac</a> prefixes.
     57<h3><code>[[InterWiki]]</code></h3>Provide a description list for the known <a class="wiki" href="/wiki/InterWiki">InterWiki</a> prefixes.
     58<h3><code>[[KnownMimeTypes]]</code></h3>List all known mime-types which can be used as <a class="wiki" href="/wiki/WikiProcessors">WikiProcessors</a>.
     59Can be …</div>
     60}}}
     61etc.
    5262}}}
    5363
     
    134144}}}
    135145
    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 (''since 0.12'').
    137 
    138 '''FIXME''' when called as a macro, `args` should be `None`.
     146Note 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'').
    139147
    140148For example, when writing:
    141149{{{
    142 {{{#!HelloWorld style="polite"
     150{{{#!HelloWorld style="polite" -silent verbose
    143151<Hello World!>
    144152}}}
     
    152160One should get:
    153161{{{
    154 Hello World, text = <Hello World!> , args = {'style': u'polite'}
     162Hello World, text = <Hello World!> , args = {'style': u'polite', 'silent': False, 'verbose': True}
    155163Hello World, text = <Hello World!> , args = {}
    156164Hello World, text = <Hello World!> , args = None
     
    163171{{{
    164172#!python
    165     text = "whatever wiki markup you want, even containing other macros"
    166     # Convert Wiki markup to HTML, new style
    167     out = StringIO()
    168     Formatter(self.env, formatter.context).format(text, out)
    169     return Markup(out.getvalue())
     173from genshi.core import Markup
     174from trac.wiki.macros import WikiMacroBase
     175from trac.wiki import Formatter
     176import StringIO
     177
     178class HelloWorldMacro(WikiMacroBase):
     179        def expand_macro(self, formatter, name, text, args):
     180                text = "whatever '''wiki''' markup you want, even containing other macros"
     181                # Convert Wiki markup to HTML, new style
     182                out = StringIO.StringIO()
     183                Formatter(self.env, formatter.context).format(text, out)
     184                return Markup(out.getvalue())
    170185}}}