close
Warning:
Can't synchronize with repository "(default)" (/common/SVN/crkit does not appear to be a Subversion repository.). Look in the Trac log for more information.
- Timestamp:
-
Jan 30, 2019, 11:46:21 PM (5 years ago)
- Author:
-
trac
- Comment:
-
--
Legend:
- Unmodified
- Added
- Removed
- Modified
-
v3
|
v4
|
|
3 | 3 | [[PageOutline(2-5,Contents,pullout)]] |
4 | 4 | |
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. |
| 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. |
6 | 6 | |
7 | 7 | The macro syntax is `[[macro-name(optional-arguments)]]`. |
8 | 8 | |
9 | | '''WikiProcessors''' are another kind of macro, commonly used for source code highlighting using a processor like `!#python` or `!#apache`: |
| 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: |
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 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': |
| 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': |
20 | 32 | |
21 | 33 | ||= Wiki Markup =||= Display =|| |
… |
… |
|
28 | 40 | [[RecentChanges(Trac,3)]] |
29 | 41 | }}} |
| 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. |
30 | 61 | |
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?]]`. |
| 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 | }}} |
38 | 70 | |
39 | 71 | == Available Macros |
40 | 72 | |
| 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 | |
41 | 75 | [[MacroList]] |
42 | 76 | |
43 | | == Contributed macros |
| 77 | == Macros from around the world |
44 | 78 | |
45 | | The [http://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. |
| 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. |
46 | 80 | |
47 | 81 | == Developing Custom Macros |
48 | 82 | |
49 | | Macros, like Trac itself, are written in the [http://python.org/ Python programming language] and are a type of [TracPlugins plugin]. |
| 83 | Macros, like Trac itself, are written in the [http://python.org/ Python programming language] and are developed as part of TracPlugins. |
50 | 84 | |
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.2-stable/sample-plugins sample-plugins]. |
| 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. |
52 | 88 | |
53 | 89 | === Macro without arguments |
54 | 90 | |
55 | | To test the following code, copy it to `timestamp_sample.py` in the TracEnvironment's `plugins/` directory. |
| 91 | To test the following code, save it in a `timestamp_sample.py` file located in the TracEnvironment's `plugins/` directory. |
56 | 92 | |
57 | 93 | {{{#!python |
58 | | from trac.util.datefmt import datetime_now, format_datetime, utc |
59 | | from trac.util.html import tag |
| 94 | from datetime import datetime |
| 95 | # Note: since Trac 0.11, datetime objects are used internally |
| 96 | |
| 97 | from genshi.builder import tag |
| 98 | |
| 99 | from trac.util.datefmt import format_datetime, utc |
60 | 100 | from trac.wiki.macros import WikiMacroBase |
61 | 101 | |
62 | | class TimestampMacro(WikiMacroBase): |
63 | | _description = "Inserts the current time (in seconds) into the wiki page." |
| 102 | class TimeStampMacro(WikiMacroBase): |
| 103 | """Inserts the current time (in seconds) into the wiki page.""" |
64 | 104 | |
65 | | def expand_macro(self, formatter, name, content, args=None): |
66 | | t = datetime_now(utc) |
| 105 | revision = "$Rev$" |
| 106 | url = "$URL$" |
| 107 | |
| 108 | def expand_macro(self, formatter, name, text): |
| 109 | t = datetime.now(utc) |
67 | 110 | return tag.strong(format_datetime(t, '%c')) |
68 | 111 | }}} |
… |
… |
|
70 | 113 | === Macro with arguments |
71 | 114 | |
72 | | To test the following code, copy it to `helloworld_sample.py` in the TracEnvironment's `plugins/` directory. |
| 115 | To test the following code, save it in a `helloworld_sample.py` file located in the TracEnvironment's `plugins/` directory. |
73 | 116 | |
74 | 117 | {{{#!python |
75 | | from trac.util.translation import cleandoc_ |
| 118 | from genshi.core import Markup |
| 119 | |
76 | 120 | from trac.wiki.macros import WikiMacroBase |
77 | 121 | |
78 | 122 | class HelloWorldMacro(WikiMacroBase): |
79 | | _description = cleandoc_( |
80 | 123 | """Simple HelloWorld macro. |
81 | 124 | |
… |
… |
|
87 | 130 | will become the documentation of the macro, as shown by |
88 | 131 | the !MacroList macro (usually used in the WikiMacros page). |
89 | | """) |
| 132 | """ |
90 | 133 | |
91 | | def expand_macro(self, formatter, name, content, args=None): |
| 134 | revision = "$Rev$" |
| 135 | url = "$URL$" |
| 136 | |
| 137 | def expand_macro(self, formatter, name, text, args): |
92 | 138 | """Return some output that will be displayed in the Wiki content. |
93 | 139 | |
94 | 140 | `name` is the actual name of the macro (no surprise, here it'll be |
95 | 141 | `'HelloWorld'`), |
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. |
| 142 | `text` is the text enclosed in parenthesis at the call of the macro. |
| 143 | Note that if there are ''no'' parenthesis (like in, e.g. |
| 144 | [[HelloWorld]]), then `text` is `None`. |
| 145 | `args` are the arguments passed when HelloWorld is called using a |
| 146 | `#!HelloWorld` code block. |
102 | 147 | """ |
103 | | return 'Hello World, content = ' + unicode(content) |
| 148 | return 'Hello World, text = %s, args = %s' % \ |
| 149 | (Markup.escape(text), Markup.escape(repr(args))) |
| 150 | |
104 | 151 | }}} |
105 | 152 | |
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`. |
| 153 | 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''). |
107 | 154 | |
108 | 155 | For example, when writing: |
… |
… |
|
126 | 173 | }}} |
127 | 174 | |
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`). |
| 175 | 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)`) with `Markup` coming from Genshi (`from genshi.core import Markup`). |
129 | 176 | |
130 | | You can also recursively use a wiki formatter to process the `content` as wiki markup: |
| 177 | You can also recursively use a wiki Formatter (`from trac.wiki import Formatter`) to process the `text` as wiki markup: |
131 | 178 | |
132 | 179 | {{{#!python |
133 | | from trac.wiki.formatter import format_to_html |
| 180 | from genshi.core import Markup |
134 | 181 | from trac.wiki.macros import WikiMacroBase |
| 182 | from trac.wiki import Formatter |
| 183 | import StringIO |
135 | 184 | |
136 | 185 | class HelloWorldMacro(WikiMacroBase): |
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) |
| 186 | def expand_macro(self, formatter, name, text, args): |
| 187 | text = "whatever '''wiki''' markup you want, even containing other macros" |
| 188 | # Convert Wiki markup to HTML, new style |
| 189 | out = StringIO.StringIO() |
| 190 | Formatter(self.env, formatter.context).format(text, out) |
| 191 | return Markup(out.getvalue()) |
141 | 192 | }}} |