diff options
Diffstat (limited to 'raw-wiki-dump/WikiMacros.trac')
| -rw-r--r-- | raw-wiki-dump/WikiMacros.trac | 192 |
1 files changed, 0 insertions, 192 deletions
diff --git a/raw-wiki-dump/WikiMacros.trac b/raw-wiki-dump/WikiMacros.trac deleted file mode 100644 index d619054..0000000 --- a/raw-wiki-dump/WikiMacros.trac +++ /dev/null @@ -1,192 +0,0 @@ -= Trac Macros - -[[PageOutline(2-5,Contents,pullout)]] - -'''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. - -The macro syntax is `[[macro-name(optional-arguments)]]`. - -'''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: - -{{{ -{{{#!wiki-processor-name -... -}}} -}}} - -== Using Macros - -Macro calls are enclosed in double-square brackets `[[..]]`. Like Python functions, macros can have arguments, which is then a comma separated list within parentheses `[[..(,)]]`. - -=== Getting Detailed Help - -The list of available macros and the full help can be obtained using the !MacroList macro, as seen [#AvailableMacros below]. - -A brief list can be obtained via `[[MacroList(*)]]` or `[[?]]`. - -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?]]`. - -=== Example - -A list of the 3 most recently changed wiki pages starting with 'Trac': - -||= Wiki Markup =||= Display =|| -{{{#!td - {{{ - [[RecentChanges(Trac,3)]] - }}} -}}} -{{{#!td style="padding-left: 2em;" -[[RecentChanges(Trac,3)]] -}}} -|----------------------------------- -{{{#!td - {{{ - [[RecentChanges?(Trac,3)]] - }}} -}}} -{{{#!td style="padding-left: 2em;" -[[RecentChanges?(Trac,3)]] -}}} -|----------------------------------- -{{{#!td - {{{ - [[?]] - }}} -}}} -{{{#!td style="padding-left: 2em" -{{{#!html -<div class="trac-macrolist"> -<h3><code>[[Image]]</code></h3>Embed an image in wiki-formatted text. - -The first argument is the file, as in <code>[[Image(filename.png)]]</code> -<h3><code>[[InterTrac]]</code></h3>Provide a list of known <a class="wiki" href="/wiki/InterTrac">InterTrac</a> prefixes. -<h3><code>[[InterWiki]]</code></h3>Provide a description list for the known <a class="wiki" href="/wiki/InterWiki">InterWiki</a> prefixes. -<h3><code>[[KnownMimeTypes]]</code></h3>List all known mime-types which can be used as <a class="wiki" href="/wiki/WikiProcessors">WikiProcessors</a>. -</div> -}}} -etc. -}}} - -== Available Macros - -''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].'' - -[[MacroList]] - -== Macros from around the world - -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. - -== Developing Custom Macros - -Macros, like Trac itself, are written in the [http://python.org/ Python programming language] and are developed as part of TracPlugins. - -For more information about developing macros, see the [trac:TracDev development resources] on the main project site. - -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. - -=== Macro without arguments - -To test the following code, save it in a `timestamp_sample.py` file located in the TracEnvironment's `plugins/` directory. - -{{{#!python -from datetime import datetime -# Note: since Trac 0.11, datetime objects are used internally - -from genshi.builder import tag - -from trac.util.datefmt import format_datetime, utc -from trac.wiki.macros import WikiMacroBase - -class TimeStampMacro(WikiMacroBase): - """Inserts the current time (in seconds) into the wiki page.""" - - revision = "$Rev$" - url = "$URL$" - - def expand_macro(self, formatter, name, text): - t = datetime.now(utc) - return tag.strong(format_datetime(t, '%c')) -}}} - -=== Macro with arguments - -To test the following code, save it in a `helloworld_sample.py` file located in the TracEnvironment's `plugins/` directory. - -{{{#!python -from genshi.core import Markup - -from trac.wiki.macros import WikiMacroBase - -class HelloWorldMacro(WikiMacroBase): - """Simple HelloWorld macro. - - Note that the name of the class is meaningful: - - it must end with "Macro" - - what comes before "Macro" ends up being the macro name - - The documentation of the class (i.e. what you're reading) - will become the documentation of the macro, as shown by - the !MacroList macro (usually used in the WikiMacros page). - """ - - revision = "$Rev$" - url = "$URL$" - - def expand_macro(self, formatter, name, text, args): - """Return some output that will be displayed in the Wiki content. - - `name` is the actual name of the macro (no surprise, here it'll be - `'HelloWorld'`), - `text` is the text enclosed in parenthesis at the call of the macro. - Note that if there are ''no'' parenthesis (like in, e.g. - [[HelloWorld]]), then `text` is `None`. - `args` are the arguments passed when HelloWorld is called using a - `#!HelloWorld` code block. - """ - return 'Hello World, text = %s, args = %s' % \ - (Markup.escape(text), Markup.escape(repr(args))) - -}}} - -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''). - -For example, when writing: -{{{ -{{{#!HelloWorld style="polite" -silent verbose -<Hello World!> -}}} - -{{{#!HelloWorld -<Hello World!> -}}} - -[[HelloWorld(<Hello World!>)]] -}}} - -One should get: -{{{ -Hello World, text = <Hello World!>, args = {'style': u'polite', 'silent': False, 'verbose': True} -Hello World, text = <Hello World!>, args = {} -Hello World, text = <Hello World!>, args = None -}}} - -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`). - -You can also recursively use a wiki Formatter (`from trac.wiki import Formatter`) to process the `text` as wiki markup: - -{{{#!python -from genshi.core import Markup -from trac.wiki.macros import WikiMacroBase -from trac.wiki import Formatter -import StringIO - -class HelloWorldMacro(WikiMacroBase): - def expand_macro(self, formatter, name, text, args): - text = "whatever '''wiki''' markup you want, even containing other macros" - # Convert Wiki markup to HTML, new style - out = StringIO.StringIO() - Formatter(self.env, formatter.context).format(text, out) - return Markup(out.getvalue()) -}}}
\ No newline at end of file |