close
Warning:
Can't synchronize with repository "(default)" (The repository directory has changed, you should resynchronize the repository with: trac-admin $ENV repository resync '(default)'). Look in the Trac log for more information.
- Timestamp:
-
2020-07-23T14:06:24-07:00 (4 years ago)
- Author:
-
trac
- Comment:
-
--
Legend:
- Unmodified
- Added
- Removed
- Modified
-
v4
|
v5
|
|
3 | 3 | [[PageOutline(2-5,Contents,pullout)]] |
4 | 4 | |
5 | | '''Trac macros''' extend the Trac engine with custom functionality. Macros are a special type of plugin and are written in Python. A macro inserts dynamic HTML data in any context supporting WikiFormatting. |
| 5 | '''Trac macros''' extend Trac with custom functionality. Macros are a special type of plugin and are written in Python. A macro generates HTML in any context supporting WikiFormatting. |
6 | 6 | |
7 | 7 | The macro syntax is `[[macro-name(optional-arguments)]]`. |
8 | 8 | |
9 | | '''WikiProcessors''' are another kind of macros. They are typically used for source code highlighting, such as `!#python` or `!#apache` and when the source code spans multiple lines, such as: |
| 9 | '''WikiProcessors''' are another kind of macro, commonly used for source code highlighting using a processor like `!#python` or `!#apache`: |
10 | 10 | |
11 | 11 | {{{ |
… |
… |
|
17 | 17 | == Using Macros |
18 | 18 | |
19 | | Macro calls are enclosed in double-square brackets `[[..]]`. Like Python functions, macros can have arguments, which is then a comma separated list within parentheses `[[..(,)]]`. |
20 | | |
21 | | === Getting Detailed Help |
22 | | |
23 | | The list of available macros and the full help can be obtained using the !MacroList macro, as seen [#AvailableMacros below]. |
24 | | |
25 | | A brief list can be obtained via `[[MacroList(*)]]` or `[[?]]`. |
26 | | |
27 | | 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?]]`. |
28 | | |
29 | | === Example |
30 | | |
31 | | A list of the 3 most recently changed wiki pages starting with 'Trac': |
| 19 | Macro calls are enclosed in double-square brackets `[[..]]`. Like Python functions macros can have arguments, which take the form of a comma separated list within parentheses `[[..(,)]]`. A common macro used is a list of the 3 most recent changes to a wiki page, or here, for example, all wiki pages starting with 'Trac': |
32 | 20 | |
33 | 21 | ||= Wiki Markup =||= Display =|| |
… |
… |
|
40 | 28 | [[RecentChanges(Trac,3)]] |
41 | 29 | }}} |
42 | | |----------------------------------- |
43 | | {{{#!td |
44 | | {{{ |
45 | | [[RecentChanges?(Trac,3)]] |
46 | | }}} |
47 | | }}} |
48 | | {{{#!td style="padding-left: 2em;" |
49 | | [[RecentChanges?(Trac,3)]] |
50 | | }}} |
51 | | |----------------------------------- |
52 | | {{{#!td |
53 | | {{{ |
54 | | [[?]] |
55 | | }}} |
56 | | }}} |
57 | | {{{#!td style="padding-left: 2em" |
58 | | {{{#!html |
59 | | <div class="trac-macrolist"> |
60 | | <h3><code>[[Image]]</code></h3>Embed an image in wiki-formatted text. |
61 | 30 | |
62 | | The first argument is the file, as in <code>[[Image(filename.png)]]</code> |
63 | | <h3><code>[[InterTrac]]</code></h3>Provide a list of known <a class="wiki" href="/wiki/InterTrac">InterTrac</a> prefixes. |
64 | | <h3><code>[[InterWiki]]</code></h3>Provide a description list for the known <a class="wiki" href="/wiki/InterWiki">InterWiki</a> prefixes. |
65 | | <h3><code>[[KnownMimeTypes]]</code></h3>List all known mime-types which can be used as <a class="wiki" href="/wiki/WikiProcessors">WikiProcessors</a>. |
66 | | </div> |
67 | | }}} |
68 | | etc. |
69 | | }}} |
| 31 | === Getting Detailed Help |
| 32 | |
| 33 | The list of available macros and the full help can be obtained using the !MacroList macro, see [#AvailableMacros below]. |
| 34 | |
| 35 | A brief list can be obtained via `[[MacroList(*)]]` or `[[?]]`. |
| 36 | |
| 37 | 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?]]`. |
70 | 38 | |
71 | 39 | == Available Macros |
72 | 40 | |
73 | | ''Note that the following list will only contain the macro documentation if you've not enabled `-OO` optimizations, or not set the `PythonOptimize` option for [wiki:TracModPython mod_python].'' |
74 | | |
75 | 41 | [[MacroList]] |
76 | 42 | |
77 | | == Macros from around the world |
| 43 | == Contributed macros |
78 | 44 | |
79 | | The [http://trac-hacks.org/ Trac Hacks] site provides a wide collection of macros and other Trac [TracPlugins plugins] contributed by the Trac community. If you are looking for new macros, or have written one that you would like to share, please visit that site. |
| 45 | The [https://trac-hacks.org/ Trac Hacks] site provides a large collection of macros and other Trac [TracPlugins plugins] contributed by the Trac community. If you are looking for new macros, or have written one that you would like to share, please visit that site. |
80 | 46 | |
81 | 47 | == Developing Custom Macros |
82 | 48 | |
83 | | Macros, like Trac itself, are written in the [http://python.org/ Python programming language] and are developed as part of TracPlugins. |
| 49 | Macros, like Trac itself, are written in the [https://python.org/ Python programming language] and are a type of [TracPlugins plugin]. |
84 | 50 | |
85 | | For more information about developing macros, see the [trac:TracDev development resources] on the main project site. |
86 | | |
87 | | Here are 2 simple examples showing how to create a Macro. Also, have a look at [trac:source:tags/trac-1.0.2/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 more insight about the transition. |
| 51 | Here are 2 simple examples showing how to create a Macro. For more information about developing macros, see the [trac:TracDev development resources] and [trac:browser:branches/1.4-stable/sample-plugins sample-plugins]. |
88 | 52 | |
89 | 53 | === Macro without arguments |
90 | 54 | |
91 | | To test the following code, save it in a `timestamp_sample.py` file located in the TracEnvironment's `plugins/` directory. |
| 55 | To test the following code, copy it to `timestamp_sample.py` in the TracEnvironment's `plugins/` directory. |
92 | 56 | |
93 | 57 | {{{#!python |
94 | | from datetime import datetime |
95 | | # Note: since Trac 0.11, datetime objects are used internally |
96 | | |
97 | | from trac.util.datefmt import format_datetime, utc |
| 58 | from trac.util.datefmt import datetime_now, format_datetime, utc |
98 | 59 | from trac.util.html import tag |
99 | 60 | from trac.wiki.macros import WikiMacroBase |
100 | 61 | |
101 | | class TimeStampMacro(WikiMacroBase): |
102 | | """Inserts the current time (in seconds) into the wiki page.""" |
| 62 | class TimestampMacro(WikiMacroBase): |
| 63 | _description = "Inserts the current time (in seconds) into the wiki page." |
103 | 64 | |
104 | | revision = "$Rev$" |
105 | | url = "$URL$" |
106 | | |
107 | | def expand_macro(self, formatter, name, text): |
108 | | t = datetime.now(utc) |
| 65 | def expand_macro(self, formatter, name, content, args=None): |
| 66 | t = datetime_now(utc) |
109 | 67 | return tag.strong(format_datetime(t, '%c')) |
110 | 68 | }}} |
… |
… |
|
112 | 70 | === Macro with arguments |
113 | 71 | |
114 | | To test the following code, save it in a `helloworld_sample.py` file located in the TracEnvironment's `plugins/` directory. |
| 72 | To test the following code, copy it to `helloworld_sample.py` in the TracEnvironment's `plugins/` directory. |
115 | 73 | |
116 | 74 | {{{#!python |
117 | | from trac.util.html import Markup |
| 75 | from trac.util.translation import cleandoc_ |
118 | 76 | from trac.wiki.macros import WikiMacroBase |
119 | 77 | |
120 | 78 | class HelloWorldMacro(WikiMacroBase): |
| 79 | _description = cleandoc_( |
121 | 80 | """Simple HelloWorld macro. |
122 | 81 | |
… |
… |
|
128 | 87 | will become the documentation of the macro, as shown by |
129 | 88 | the !MacroList macro (usually used in the WikiMacros page). |
130 | | """ |
| 89 | """) |
131 | 90 | |
132 | | revision = "$Rev$" |
133 | | url = "$URL$" |
134 | | |
135 | | def expand_macro(self, formatter, name, text, args): |
| 91 | def expand_macro(self, formatter, name, content, args=None): |
136 | 92 | """Return some output that will be displayed in the Wiki content. |
137 | 93 | |
138 | 94 | `name` is the actual name of the macro (no surprise, here it'll be |
139 | 95 | `'HelloWorld'`), |
140 | | `text` is the text enclosed in parenthesis at the call of the macro. |
141 | | Note that if there are ''no'' parenthesis (like in, e.g. |
142 | | [[HelloWorld]]), then `text` is `None`. |
143 | | `args` are the arguments passed when HelloWorld is called using a |
144 | | `#!HelloWorld` code block. |
| 96 | `content` is the text enclosed in parenthesis at the call of the |
| 97 | macro. Note that if there are ''no'' parenthesis (like in, e.g. |
| 98 | [[HelloWorld]]), then `content` is `None`. |
| 99 | `args` will contain a dictionary of arguments when called using the |
| 100 | Wiki processor syntax and will be `None` if called using the |
| 101 | macro syntax. |
145 | 102 | """ |
146 | | return 'Hello World, text = %s, args = %s' % \ |
147 | | (Markup.escape(text), Markup.escape(repr(args))) |
148 | | |
| 103 | return 'Hello World, content = ' + unicode(content) |
149 | 104 | }}} |
150 | 105 | |
151 | | Note that `expand_macro` optionally takes a 4^th^ parameter ''`args`''. When the macro is called as a [WikiProcessors WikiProcessor], it is 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. In the other case, when called as a macro, `args` is `None`. (''since 0.12''). |
| 106 | Note that `expand_macro` optionally takes a 4^th^ parameter ''`args`''. When the macro is called as a [WikiProcessors WikiProcessor], it is 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. When called as a macro, `args` is `None`. |
152 | 107 | |
153 | 108 | For example, when writing: |
… |
… |
|
171 | 126 | }}} |
172 | 127 | |
173 | | Note that the return value of `expand_macro` is '''not''' HTML escaped. Depending on the expected result, you should escape it yourself (using `return Markup.escape(result)`) or, if this is indeed HTML, wrap it in a Markup object: `return Markup(result)` (`from trac.util.html import Markup`). |
| 128 | Note that the return value of `expand_macro` is '''not''' HTML escaped. Depending on the expected result, you should escape it yourself (using `return Markup.escape(result)`), or if this is indeed HTML, wrap it in a Markup object: `return Markup(result)` (`from trac.util.html import Markup`). |
174 | 129 | |
175 | | You can also recursively use a wiki Formatter (`from trac.wiki import Formatter`) to process the `text` as wiki markup: |
| 130 | You can also recursively use a wiki formatter to process the `content` as wiki markup: |
176 | 131 | |
177 | 132 | {{{#!python |
178 | | from trac.util.html import Markup |
| 133 | from trac.wiki.formatter import format_to_html |
179 | 134 | from trac.wiki.macros import WikiMacroBase |
180 | | from trac.wiki import Formatter |
181 | | import StringIO |
182 | 135 | |
183 | 136 | class HelloWorldMacro(WikiMacroBase): |
184 | | def expand_macro(self, formatter, name, text, args): |
185 | | text = "whatever '''wiki''' markup you want, even containing other macros" |
186 | | # Convert Wiki markup to HTML, new style |
187 | | out = StringIO.StringIO() |
188 | | Formatter(self.env, formatter.context).format(text, out) |
189 | | return Markup(out.getvalue()) |
| 137 | def expand_macro(self, formatter, name, content, args): |
| 138 | content = "any '''wiki''' markup you want, even containing other macros" |
| 139 | # Convert Wiki markup to HTML |
| 140 | return format_to_html(self.env, formatter.context, content) |
190 | 141 | }}} |