Changes between Version 1 and Version 2 of TracWikiMacros


Ignore:
Timestamp:
03/11/08 05:24:52 (18 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • TracWikiMacros

    v1 v2  
    1212Trac 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.
    1313
    14 === Examples ===
     14=== Example ===
     15
     16A list of 3 most recently changed wiki pages starting with 'Trac':
    1517
    1618{{{
    17  [[Timestamp]]
     19 [[RecentChanges(Trac,3)]]
    1820}}}
     21
    1922Display:
    20  [[Timestamp]]
    21 
    22 {{{
    23  [[HelloWorld(Testing)]]
    24 }}}
    25 Display:
    26  [[HelloWorld(Testing)]]
     23 [[RecentChanges(Trac,3)]]
    2724
    2825== Available Macros ==
    … …  
    4441== Implementation ==
    4542
    46 Here are 2 simple examples on how to create a Macro with [wiki:0.11 Trac 0.11] have a look at source:trunk/sample-plugins/Timestamp.py for an example that shows the difference between old style and new style macros and also source:trunk/wiki-macros/README which Provides a little more insight.
     43Here are 2 simple examples on how to create a Macro with [wiki:0.11 Trac 0.11] have a look at source:trunk/sample-plugins/Timestamp.py for an example that shows the difference between old style and new style macros and also source:trunk/wiki-macros/README which provides a little more insight about the transition.
    4744
    4845=== Macro without arguments ===
    4946It should be saved as `TimeStamp.py` as Trac will use the module name as the Macro name
    5047{{{
    51 from trac.core import *
     48#!python
     49from datetime import datetime
     50# Note: since Trac 0.11, datetime objects are used internally
     51
     52from genshi.builder import tag
     53
     54from trac.util.datefmt import format_datetime, utc
    5255from trac.wiki.macros import WikiMacroBase
    53 from StringIO import StringIO
    54 import time
    55 
    56 __all__ = ['TimestampMacro']
    5756
    5857class TimestampMacro(WikiMacroBase):
    59         """
    60         Macro for inserting timestamp
     58    """Inserts the current time (in seconds) into the wiki page."""
    6159
    62         {{{
    63         [[Timestamp]]
    64         }}}
    65         """
    66         def expand_macro(self, formatter, name, args):
    67                 buf = StringIO()
    68                 t = time.localtime()
    69                 buf = "<b>%s</b>" % time.strftime('%c', t)
    70                 return buf
     60    revision = "$Rev$"
     61    url = "$URL$"
     62
     63    def expand_macro(self, formatter, name, args):
     64        t = datetime.now(utc)
     65        return tag.b(format_datetime(t, '%c'))
    7166}}}
    7267
    … …  
    7469It should be saved as `HelloWorld.py` (in the plugins/ directory) as Trac will use the module name as the Macro name
    7570{{{
    76 """Example macro."""
    77 from trac.core import *
     71#!python
    7872from trac.wiki.macros import WikiMacroBase
    79 from trac.util import escape
    80 
    81 __all__ = ['HelloWorldMacro']
    8273
    8374class HelloWorldMacro(WikiMacroBase):
     75    """Simple HelloWorld macro.
     76
     77    Note that the name of the class is meaningful:
     78     - it must end with "Macro"
     79     - what comes before "Macro" ends up being the macro name
     80
     81    The documentation of the class (i.e. what you're reading)
     82    will become the documentation of the macro, as shown by
     83    the !MacroList macro (usually used in the TracWikiMacros page).
     84    """
     85
     86    revision = "$Rev$"
     87    url = "$URL$"
     88
     89    def expand_macro(self, formatter, name, args):
     90        """Return some output that will be displayed in the Wiki content.
     91
     92        `name` is the actual name of the macro (no surprise, here it'll be
     93        `'HelloWorld'`),
     94        `args` is the text enclosed in parenthesis at the call of the macro.
     95          Note that if there are ''no'' parenthesis (like in, e.g.
     96          [[HelloWorld]]), then `args` is `None`.
    8497        """
    85         Demo macro for a greeting with an argument.
    86 
    87         {{{
    88         [[HelloWorld(args)]]
    89         }}}
    90 
    91         """
    92         def expand_macro(self, formatter, name, args):
    93                 # args will be `None` if the macro is called without parenthesis.
    94                 txt = args or 'No arguments'
    95 
    96                 # then, as `txt` comes from the user, it's important to guard against
    97                 # the possibility to inject malicious HTML/Javascript, by using `escape()`:
    98                 return 'Hello World, args = ' + escape(txt)
     98        return 'Hello World, args = ' + unicode(args)
     99   
     100    # Note that there's no need to HTML escape the returned data,
     101    # as the template engine (Genshi) will do it for us.
    99102}}}
    100103
    … …  
    106109
    107110{{{
     111#!python
    108112  text = "whatever wiki markup you want, even containing other macros"
    109113  # Convert Wiki markup to HTML, new style