From 3aa8b1dd6e0f504ef83da99f8c9cdb2532f948f5 Mon Sep 17 00:00:00 2001 From: Rob Austein Date: Sun, 13 Sep 2020 23:10:21 +0000 Subject: Initial conversion pass --- raw-wiki-dump/WikiMacros.md | 194 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 raw-wiki-dump/WikiMacros.md (limited to 'raw-wiki-dump/WikiMacros.md') diff --git a/raw-wiki-dump/WikiMacros.md b/raw-wiki-dump/WikiMacros.md new file mode 100644 index 0000000..5a5d158 --- /dev/null +++ b/raw-wiki-dump/WikiMacros.md @@ -0,0 +1,194 @@ +# 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 +
+

[[Image]]

Embed an image in wiki-formatted text. + +The first argument is the file, as in [[Image(filename.png)]] +

[[InterTrac]]

Provide a list of known InterTrac prefixes. +

[[InterWiki]]

Provide a description list for the known InterWiki prefixes. +

[[KnownMimeTypes]]

List all known mime-types which can be used as WikiProcessors. +
+``` +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 [Trac Hacks] site provides a wide collection of macros and other Trac [TracPlugins plugins](http://trac-hacks.org/) 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 [Python programming language](http://python.org/) 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 + +``` + +```#!HelloWorld + +``` + +[[HelloWorld()]] +``` + +One should get: +``` +Hello World, text = , args = {'style': u'polite', 'silent': False, 'verbose': True} +Hello World, text = , args = {} +Hello World, text = , 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()) +``` -- cgit v1.2.3