Home

Documentation

Project Support

Changes in Version 1 of WikiMacros

Author:
trac
Timestamp:
Wed Aug 23 17:34:43 2006

Legend:

Unmodified
Added
Removed
Modified

  • WikiMacros

    v0 v1
      1  =  Wiki Macros = 
      2  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. 
      3   
      4  Another 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 == 
      7  Macro 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  }}} 
      14  Display: 
      15   [[Timestamp]] 
      16   
      17  {{{ 
      18   [[HelloWorld(Testing)]] 
      19  }}} 
      20  Display: 
      21   [[HelloWorld(Testing)]] 
      22   
      23   
      24  == Available Macros == 
      25  Macros are still a new feature, and the list of available (and distributed) macros is  
      26  admittedly 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 == 
      36  The [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 == 
      45  Macros, 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   
      47  It's easiest to learn from an example: 
      48  {{{ 
      49  # MyMacro.py -- The world's simplest macro 
      50   
      51  def execute(hdf, args, env): 
      52      return "Hello World called with args: %s" % args 
      53  }}} 
      54   
      55  === Advanced Topics: Template-enabled Macros === 
      56  For 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   
      58  Macros gain direct access to the main HDF tree, and are free to manipulate it.  
      59   
      60  Example: 
      61  {{{ 
      62  def 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   
      73  You can also use the environment (env) object to access configuration data. 
      74   
      75  Example. 
      76  {{{ 
      77  def execute(hdf, txt, env): 
      78      return env.get_config('trac', 'repository_dir') 
      79  }}} 
      80  ---- 
      81  See also:  WikiProcessors, WikiFormatting, TracGuide