wiki:MacroMigrationTutorial

Migrating Trac macros from 0.8.x to 0.9.x

Changes

Global macros are now stored in ${prefix}/share/trac/wiki-macros instead of ${prefix}/pythonX.Y/site-packages/trac/wiki-macros.

Global macros are not implicitly loaded. After installing a macro into the global macro directory a trac-admin <env> upgrade must be performed, which will copy the macro into the environments <env>/wiki-macros directory. Unfortunately, trac does not appear to detect outdated macros and will not upgrade existing macros to newer versions. You will need to manually delete the copies of the global macros in each environment, then perform an environment upgrade. With mod_python, as always, this will require an apache restart.

Note : previous behaviour has been reverted in the trunk, just after 0.9b2. In release 0.9, there should be no need to rerun trac-admin upgrade after each macro update.

Hints

If your macro needs to preserve state across an entire page render, place the state variables into the hdf object.

Issues

Due to trac-ticket:1562, there is seemingly no way to pass dynamic variables to reports apart from using a fully qualified link. For example, in a perfect world this would work. This feature did work in 0.8.

API Changes

Several classes and functions used frequently in macros have changed. This table outlines some of those that I came across while migrating my macros to the 0.9.x object hierarchy:

0.8.xEquivalent in 0.9.x
trac.WikiFormatter.wiki_to_oneliner(wikitext, hdf, env, db,absurls=0)trac.wiki.wiki_to_oneliner(wikitext, env, db=None, absurls=0)
trac.WikiFormatter.wiki_to_html(wikitext, hdf, env, db, absurls=0)trac.wiki.wiki_to_html(wikitext, env, req, db=None, absurls=0, escape_newlines=False) 1


  1. 1. If you wish to use wiki_to_html with content that itself contains macro's, you will need to create a full plugin. This seems to be because the hdf macro argument is extracted from the req object in the sub-macro.

TagIt(tutorial,athomas,0.8,0.9)?

Last modified 9 years ago Last modified on Dec 1, 2005 2:44:03 PM