Changes between Initial Version and Version 1 of WikiMacros


Ignore:
Timestamp:
Dec 9, 2005, 12:30:09 PM (13 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiMacros

    v1 v1  
     1=  Wiki Macros =
     2Trac 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.
     3
     4Another kind of macros are WikiProcessors. They typically deal with alternate markup formats and representation of larger blocks of information (like source code highlighting). See also: WikiProcessors.
     5
     6== Using Macros ==
     7Macro calls are enclosed in two ''square brackets''. Like python functions, macros can also have arguments, a comma separated list within parenthesis.
     8
     9=== Examples ===
     10
     11{{{
     12 [[Timestamp]]
     13}}}
     14Display:
     15 [[Timestamp]]
     16
     17{{{
     18 [[HelloWorld(Testing)]]
     19}}}
     20Display:
     21 [[HelloWorld(Testing)]]
     22
     23
     24== Available Macros ==
     25Macros are still a new feature, and the list of available (and distributed) macros is
     26admittedly not very impressive. In future Trac releases, we hope to build a library of useful macros, and will of course happily include contributed macros (see below).
     27
     28 * '''!HelloWorld''' -- An example macro, useful for learning how to write macros.
     29 * '''Timestamp''' -- Insert the current date and time.
     30
     31
     32----
     33
     34
     35== Macros from around the world ==
     36The [http://projects.edgewall.com/trac/ Trac Project] has a section dedicated to user-contributed macros, [http://projects.edgewall.com/trac/wiki/MacroBazaar MacroBazaar]. If you're looking for new macros, or have written new ones to share with the world, don't hesitate adding it to the [http://projects.edgewall.com/trac/wiki/MacroBazaar MacroBazaar] wiki page.
     37
     38  http://projects.edgewall.com/trac/wiki/MacroBazaar
     39
     40
     41----
     42
     43
     44== Developing New Macros ==
     45Macros, like Trac itself, are written in the [http://www.python.org/ Python programming language]. They are very simple modules, identified by the filename and should contain a single ''entry point'' function. Trac will display the returned data inserted into the HTML where the macro was called.
     46
     47It's easiest to learn from an example:
     48{{{
     49# MyMacro.py -- The world's simplest macro
     50
     51def execute(hdf, args, env):
     52    return "Hello World called with args: %s" % args
     53}}}
     54
     55=== Advanced Topics: Template-enabled Macros ===
     56For advanced uses, macros can also render structured output in HDF, to be rendered to HTML using clearsilver templates - like most Trac output. In short, this allows more generic and well-designed advanced macros.
     57
     58Macros gain direct access to the main HDF tree, and are free to manipulate it.
     59
     60Example:
     61{{{
     62def execute(hdf, args, env):
     63    # Currently hdf is set only when the macro is called
     64    # From a wiki page
     65    if hdf:
     66        hdf.setValue('wiki.macro.greeting', 'Hello World')
     67       
     68    # args will be null if the macro is called without parentesis.
     69    args = args or 'No arguments'
     70    return 'Hello World, args = ' + args
     71}}}
     72
     73You can also use the environment (env) object to access configuration data.
     74
     75Example.
     76{{{
     77def execute(hdf, txt, env):
     78    return env.get_config('trac', 'repository_dir')
     79}}}
     80----
     81See also:  WikiProcessors, WikiFormatting, TracGuide