Macro calls are enclosed in two ''square brackets''. Like Python functions, macros can also have arguments, a comma separated list within parentheses.

8

10

9

=== Examples ===

11

Macro calls are enclosed in two ''square brackets''. Like Python functions, macros can also have arguments, a comma separated list within parentheses.

10

12

11

{{{

12

[[Timestamp]]

13

=== Getting Detailed Help ===

14

The list of available macros and the full help can be obtained using the !MacroList macro, as seen [#AvailableMacros below].

15

16

A brief list can be obtained via ![[MacroList(*)]] or ![[?]].

17

18

Detailed help on a specific macro can be obtained by passing it as an argument to !MacroList, e.g. ![[MacroList(MacroList)]], or, more conveniently, by appending a question mark (?) to the macro's name, like in ![[MacroList?]].

19

20

21

22

=== Example ===

23

24

A list of 3 most recently changed wiki pages starting with 'Trac':

25

26

||= Wiki Markup =||= Display =||

27

{{{#!td

28

{{{

29

[[RecentChanges(Trac,3)]]

30

}}}

13

31

}}}

14

Display:

15

[[Timestamp]]

32

{{{#!td style="padding-left: 2em;"

33

[[RecentChanges(Trac,3)]]

34

}}}

35

|-----------------------------------

36

{{{#!td

37

{{{

38

[[RecentChanges?(Trac,3)]]

39

}}}

40

}}}

41

{{{#!td style="padding-left: 2em;"

42

[[RecentChanges?(Trac,3)]]

43

}}}

44

|-----------------------------------

45

{{{#!td

46

{{{

47

[[?]]

48

}}}

49

}}}

50

{{{#!td style="padding-left: 2em"

51

{{{#!html

52

<div style="font-size: 80%" class="trac-macrolist">

53

<h3><code>[[Image]]</code></h3>Embed an image in wiki-formatted text.

16

54

17

{{{

18

[[HelloWorld(Testing)]]

55

The first argument is the file …

56

<h3><code>[[InterTrac]]</code></h3>Provide a list of known <a class="wiki" href="/wiki/InterTrac">InterTrac</a> prefixes.

57

<h3><code>[[InterWiki]]</code></h3>Provide a description list for the known <a class="wiki" href="/wiki/InterWiki">InterWiki</a> prefixes.

58

<h3><code>[[KnownMimeTypes]]</code></h3>List all known mime-types which can be used as <a class="wiki" href="/wiki/WikiProcessors">WikiProcessors</a>.

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 `execute()` function. Trac will display the returned data inserted into the HTML representation of the Wiki page where the macro is called.

75

Macros, like Trac itself, are written in the [http://python.org/ Python programming language] and are developed as part of TracPlugins.

35

76

36

It's easiest to learn from an example:

77

For more information about developing macros, see the [trac:TracDev development resources] on the main project site.

78

79

80

Here are 2 simple examples showing how to create a Macro with Trac 0.11.

81

82

Also, have a look at [trac:source:tags/trac-0.11/sample-plugins/Timestamp.py Timestamp.py] for an example that shows the difference between old style and new style macros and at the [trac:source:tags/trac-0.11/wiki-macros/README macros/README] which provides a little more insight about the transition.

83

84

=== Macro without arguments ===

85

To test the following code, you should saved it in a `timestamp_sample.py` file located in the TracEnvironment's `plugins/` directory.

37

86

{{{

38

87

#!python

39

# MyMacro.py -- The world's simplest macro

88

from datetime import datetime

89

# Note: since Trac 0.11, datetime objects are used internally

40

90

41

def execute(hdf, args, env):

42

return "Hello World called with args: %s" % args

91

from genshi.builder import tag

92

93

from trac.util.datefmt import format_datetime, utc

94

from trac.wiki.macros import WikiMacroBase

95

96

class TimeStampMacro(WikiMacroBase):

97

"""Inserts the current time (in seconds) into the wiki page."""

98

99

revision = "$Rev$"

100

url = "$URL$"

101

102

def expand_macro(self, formatter, name, text):

103

t = datetime.now(utc)

104

return tag.b(format_datetime(t, '%c'))

43

105

}}}

44

106

45

You can also use the environment (`env`) object, for example to access configuration data and the database, for example:

107

=== Macro with arguments ===

108

To test the following code, you should saved it in a `helloworld_sample.py` file located in the TracEnvironment's `plugins/` directory.

46

109

{{{

47

110

#!python

48

def execute(hdf, txt, env):

49

return env.config.get('trac', 'repository_dir')

111

from genshi.core import Markup

112

113

from trac.wiki.macros import WikiMacroBase

114

115

class HelloWorldMacro(WikiMacroBase):

116

"""Simple HelloWorld macro.

117

118

Note that the name of the class is meaningful:

119

- it must end with "Macro"

120

- what comes before "Macro" ends up being the macro name

121

122

The documentation of the class (i.e. what you're reading)

123

will become the documentation of the macro, as shown by

124

the !MacroList macro (usually used in the WikiMacros page).

125

"""

126

127

revision = "$Rev$"

128

url = "$URL$"

129

130

def expand_macro(self, formatter, name, text, args):

131

"""Return some output that will be displayed in the Wiki content.

132

133

`name` is the actual name of the macro (no surprise, here it'll be

134

`'HelloWorld'`),

135

`text` is the text enclosed in parenthesis at the call of the macro.

136

Note that if there are ''no'' parenthesis (like in, e.g.

137

[[HelloWorld]]), then `text` is `None`.

138

`args` are the arguments passed when HelloWorld is called using a

139

`#!HelloWorld` code block.

140

"""

141

return 'Hello World, text = %s, args = %s' % \

142

(Markup.escape(text), Markup.escape(repr(args)))

143

50

144

}}}

51

145

52

Note that since version 0.9, wiki macros can also be written as TracPlugins. This gives them some capabilities that “classic” macros do not have, such as being able to directly access the HTTP request.

146

Note that `expand_macro` optionally takes a 4^th^ parameter ''`args`''. When the macro is called as a [WikiProcessors WikiProcessor], it's also possible to pass `key=value` [WikiProcessors#UsingProcessors processor parameters]. If given, those are stored in a dictionary and passed in this extra `args` parameter. On the contrary, when called as a macro, `args` is `None`. (''since 0.12'').

53

147

54

For more information about developing macros, see the [http://projects.edgewall.com/trac/wiki/TracDev development resources] on the main project site.

148

For example, when writing:

149

{{{

150

{{{#!HelloWorld style="polite"

151

<Hello World!>

152

}}}

55

153

56

----

57

See also: WikiProcessors, WikiFormatting, TracGuide

154

{{{#!HelloWorld

155

<Hello World!>

156

}}}

157

158

[[HelloWorld(<Hello World!>)]]

159

}}}

160

One should get:

161

{{{

162

Hello World, text = <Hello World!> , args = {'style': u'polite'}

163

Hello World, text = <Hello World!> , args = {}

164

Hello World, text = <Hello World!> , args = None

165

}}}

166

167

Note that the return value of `expand_macro` is '''not''' HTML escaped. Depending on the expected result, you should escape it by yourself (using `return Markup.escape(result)`) or, if this is indeed HTML, wrap it in a Markup object (`return Markup(result)`) with `Markup` coming from Genshi, (`from genshi.core import Markup`).

168

169

You can also recursively use a wiki Formatter (`from trac.wiki import Formatter`) to process the `text` as wiki markup, for example by doing: