Edgewall Software
Last modified 5 years ago Last modified on Dec 14, 2006 6:29:23 PM

Note: This page applies to 0.8, not 0.9, as I have discovered..

Caveat: This documents old style macros, which are now deprecated. Support for this style of macros has been removed completely in 0.11.

Trac Macro Documentation

Trac macros have the following interface: 

def execute(hdf, txt, env):

Which begs the question - what are hdf, txt and env?

env

The following source reveals the env methods:

trac.Environment​

env has the following methods:

  • verify() - Verifies that self.path is a compatible trac environment
  • get_db_cnx() - Returns a database connection
  • create() - Create a new trac project
  • get_version() - Return current database version (7)
  • load_config() - Load the trac.ini file
  • get_config(section, name, default=)
  • set_config(section, name, value) - Changes a config value, these changes are _not_ persistent unless saved with save_config()
  • get_config_items(section) - Return a list of (name, value) pairs for all the entries in "section". See TracIni for the valid values of section.
  • save_config() - Save configuration changes to trac.ini file
  • get_templates_dir() - Return the path to the Trac templates directory
  • get_log_dir() - Return the path to the Tac log directory
  • setup_log() - Enable logging
  • setup_mimeviewer() - ?
  • get_attachments_dir() - Return the path to the Trac attachments directory
  • get_attachments(cnx, type, id) -
  • get_attachments_hdf(self, cnx, type, id, hdf, prefix) - ?
  • create_attachment(cnx, type, id, attachment, description, author, ipnr) - ?
  • delete_attachment(cnx, type, id, filename) -
  • backup(dest=None) - Backup the Trac database.
  • upgrade(backup=None,backup_dest=None) - Upgrade database. Each db version should have its own upgrade module, names upgrades/dbN.py, where 'N' is the version number (int).

txt

This is any arguments passed to the macro as a string. So a macro called like: 

[[myMacro(flim, flam)]]

has a txt value of 'flim, flam'

hdf

The following links explain and document the HDF (Hierarchical Data Format) and the interface:

The following methods are available (see above for details):

  • getIntValue(hdf_var_name, default_value)
  • getValue(hdf_var_name, default_value)
  • setValue(hdf_var_name, value)
  • readFile(filename)
  • readString(hdf_string_data)
  • writeFile(filename)
  • writeString()
  • dump()
  • getObj(hdf_name)
  • top()
  • copy(name, src_dataset)
  • removeTree(hdf_path)
  • setSymLink(hdf_name_src, hdf_name_dest)
  • getAttrs(hdf_var_name)
  • setAttr(hdf_node_name, attr_name, attr_value)
  • child()
  • next()
  • name()
  • value()

To discover the actual HDF for a given Wiki page, create and run a macro something like: 

def execute(hdf, txt, env):
   return hdf.writeString()

The results for a sample look like this (after some clean up): WikiMacroObjects/HdfExample