Note: This website is archived. For up-to-date information about D projects and development, please visit wiki.dlang.org.

Changes from Version 1 of WikiMacros

Show
Ignore:
Author:
trac (IP: 127.0.0.1)
Timestamp:
11/23/05 04:00:36 (13 years ago)
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiMacros

    v0 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 parentheses.  
     8 
     9=== Examples === 
     10 
     11{{{ 
     12 [[Timestamp]] 
     13}}} 
     14Display: 
     15 [[Timestamp]] 
     16 
     17{{{ 
     18 [[HelloWorld(Testing)]] 
     19}}} 
     20Display: 
     21 [[HelloWorld(Testing)]] 
     22 
     23== Available Macros == 
     24 
     25Macros are still a relatively 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[[MacroList]] 
     29 
     30== Macros from around the world == 
     31The [http://projects.edgewall.com/trac/ Trac Project] has a section dedicated to user-contributed macros, [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 [wiki:MacroBazaar MacroBazaar] wiki page. 
     32 
     33  http://projects.edgewall.com/trac/wiki/MacroBazaar 
     34 
     35 
     36---- 
     37 
     38 
     39== Developing New Macros == 
     40Macros, 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. 
     41 
     42It's easiest to learn from an example: 
     43{{{ 
     44#!python 
     45# MyMacro.py -- The world's simplest macro 
     46 
     47def execute(hdf, args, env): 
     48    return "Hello World called with args: %s" % args 
     49}}} 
     50 
     51=== Advanced Topics: Template-enabled Macros === 
     52For 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. 
     53 
     54Macros gain direct access to the main HDF tree, and are free to manipulate it.  
     55 
     56Example: 
     57{{{ 
     58#!python 
     59def execute(hdf, args, env): 
     60    # Currently hdf is set only when the macro is called 
     61    # from a wiki page. 
     62    if hdf: 
     63        hdf.setValue('wiki.macro.greeting', 'Hello World') 
     64         
     65    # args will be null if the macro is called without parentheses. 
     66    args = args or 'No arguments' 
     67    return 'Hello World, args = ' + args 
     68}}} 
     69 
     70You can also use the environment (env) object to access configuration data. 
     71 
     72Example. 
     73{{{ 
     74#!python 
     75def execute(hdf, txt, env): 
     76    return env.get_config('trac', 'repository_dir') 
     77}}} 
     78 
     79Here is information on the different WikiMacroObjects. 
     80 
     81---- 
     82See also:  WikiProcessors, WikiFormatting, TracGuide, WikiMacroObjects