Skip to content

TracWikiMacros

Jump to bottom
JBBgameich edited this page May 1, 2018 · 3 revisions

Trac Macros

Trac macros are plugins to extend the Trac engine with custom 'functions' written in Python. A macro inserts dynamic HTML data in any context supporting WikiFormatting.

Another kind of macros are WikiProcessors. They typically deal with alternate markup formats and representation of larger blocks of information (like source code highlighting).

Using Macros

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

Trac macros can also be written as TracPlugins. This gives them some capabilities that macros do not have, such as being able to directly access the HTTP request.

Example

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

 [[RecentChanges(Trac,3)]]

Display:

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 mod_python.

[[AboutWikiBoxes]]

Display a wiki page on how to use boxes.

[[AboutWikiIcons]]

Display a wiki page on how to use icons.

[[AboutWikiPhrases]]

Display a wiki page on how to use attentional phrases.

[[Color]]

Decorate text with colors.

Syntax:

[[Color(text, fg/bg/size)]]

where

  • text is the text to decorate. Enter a leading and/or trailing space character to surround the text with a decorated space.
  • fg/bg/size defines the foreground and background colors, and a font size. All parameters are optional and separated by slash character (/).

Colors may be specified as an RGB triplet in hexadecimal format (a hex triplet; e.g. #000 or #000000 for black); they may also be specified according to their common English names (e.g. red, green, blue etc.). See ​here for details.

Examples:

[[Color(Large red on yellow, red/yellow/150%)]]
[[Color(Red on yellow, red/yellow)]]
[[Color(Yellow background, /yellow)]]
[[Color(Large red, #f00/2em)]]
[[Color(Large on yellow, /yellow/20px)]]
[[Color(Text, can, have, commas, /yellow)]]
[[Color( Surrounding space is also decorated , white/red)]]

To set the foreground color for a larger block, the processor variant can be used (background color and font size may not display as expected due to the mechanisms of cascading style sheets, be advised and use the color parameter only):

{{{#!Color color=green
...
}}}

[[CommitTicketReference]]

Insert a changeset message into the output.

This macro must be called using wiki processor syntax as follows:

{{{
#!CommitTicketReference repository="reponame" revision="rev"
}}}

where the arguments are the following:

  • repository: the repository containing the changeset
  • revision: the revision of the desired changeset

[[DownloadsCount]]

Display count of downloads.

[[Icon]]

Shows a named icon that can be in line with text.

Syntax:

[[Icon(name, size)]]

where

  • name is the name of the icon. When name contains a pattern character (* or ?), a 2-column preview of matching icons is presented, which should mainly be used for finding and selecting an icon during wiki page editing in side-by-side mode (however, no more than 32 icons are presented to prevent exhaustive network traffic.)
  • size is optionally one of small, medium or large or an abbreviation thereof (defaults small).

Example:

[[Icon(smiley)]]

Use ShowIcons for static presentation of available icons. Smileys like :-) are automatically rendered as icons. Use ShowSmileys to se all available smileys.

Following wiki markup is equivalent to using this macro:

(|name, size|)

[[Image]]

Embed an image in wiki-formatted text.

The first argument is the file specification. The file specification may reference attachments in three ways:

  • module:id:file, where module can be either wiki or ticket, to refer to the attachment named file of the specified wiki page or ticket.
  • id:file: same as above, but id is either a ticket shorthand or a Wiki page name.
  • file to refer to a local attachment named 'file'. This only works from within that wiki page or a ticket.

Also, the file specification may refer to repository files, using the source:file syntax (source:file@rev works also).

Files can also be accessed with a direct URLs; /file for a project-relative, //file for a server-relative, or http://server/file for absolute location of the file.

The remaining arguments are optional and allow configuring the attributes and style of the rendered <img> element:

  • digits and unit are interpreted as the size (ex. 120, 25%) for the image
  • right, left, center, top, bottom and middle are interpreted as the alignment for the image (alternatively, the first three can be specified using align=... and the last three using valign=...)
  • link=some TracLinks... replaces the link to the image source by the one specified using a TracLinks. If no value is specified, the link is simply removed.
  • nolink means without link to image source (deprecated, use link=)
  • key=value style are interpreted as HTML attributes or CSS style indications for the image. Valid keys are:
    • align, valign, border, width, height, alt, title, longdesc, class, margin, margin-(left,right,top,bottom), id and usemap
    • border, margin, and margin-* can only be a single number
    • margin is superseded by center which uses auto margins

Examples:

    [[Image(photo.jpg)]]                           # simplest
    [[Image(photo.jpg, 120px)]]                    # with image width size
    [[Image(photo.jpg, right)]]                    # aligned by keyword
    [[Image(photo.jpg, nolink)]]                   # without link to source
    [[Image(photo.jpg, align=right)]]              # aligned by attribute

You can use image from other page, other ticket or other module.

    [[Image(OtherPage:foo.bmp)]]    # if current module is wiki
    [[Image(base/sub:bar.bmp)]]     # from hierarchical wiki page
    [[Image(#3:baz.bmp)]]           # if in a ticket, point to #3
    [[Image(ticket:36:boo.jpg)]]
    [[Image(source:/images/bee.jpg)]] # straight from the repository!
    [[Image(htdocs:foo/bar.png)]]   # image file in project htdocs dir.

Adapted from the Image.py macro created by Shun-ichi Goto <gotoh@…>

[[InterTrac]]

Geben Sie eine Liste der bekannten InterTrac-Präfixe an.

[[InterWiki]]

Provide a description list for the known InterWiki prefixes.

[[KnownMimeTypes]]

List all known mime-types which can be used as WikiProcessors.

Can be given an optional argument which is interpreted as mime-type filter.

[[ListDownloads]]

Display list of download files.

[[ListTagged]]

Zeite eine Liste von Dokumenten mit Tags.

Aufruf:

[[ListTagged(query)]]

Die Abfrage-Syntax finden Sie in der Beschreibung zu Tags.

[[MacroList]]

Display a list of all installed Wiki macros, including documentation if available.

Optionally, the name of a specific macro can be provided as an argument. In that case, only the documentation for that macro will be rendered.

Note that this macro will not be able to display the documentation of macros if the PythonOptimize option is enabled for mod_python!

[[MultiLangTitleIndex]]

Inserts an alphabetic list of all wiki pages cosidering suffixes.

This macro is similar to TitleIndex macro but differ in two points.

  • All the variants are displayed in one line.
  • Displayed in two columns. One is for the pages made for the project. One is for the pages provided by Trac. WikiStart and SandBox are grouped in project pages as default. This is configurable via _explicit_user_pages option.

One entry displayed by this macro has a format like this:

WikiStart (en, fr, ja, default)

Left most page name is for usual access with negotiation. Items in paren are existing language variants for the page.

System pages are decided by listing files in wiki-default directory. As described before, you can exclude some pages as user page by spcifying _explicit_user_pages. Likewise, you can specify the system pages via _explicit_system_pages option.

These two options are list of page names separated by comma. If the page name ends with '*' character, it works as prefix for matching. For exmaple, 'Trac*' means "page names staring with 'Trac'".

[[NTOC]]

Language-aware version of TOC Macro.

Dependency

  • trac 0.11 or later
  • tractoc macro for trac 0.11

Description

This macro is an alternative of TOC macro (written by coderanger) extending to use content of localized page if exist. You can write TOC macro entry by normal page name wihtout lang suffix.

For example, if you specify the page 'SubPage' in argument on the Japanese localized page 'BasePage.ja', find 'SubPage.ja' first and return it's content if exist. Or find localized page regarding preferred languages from browser's Accept-Language: header. Or, finally, exact given page name is used.

If you specify the page with lang suffix, that page is used.

LIMITATION

TOC macro accepts wildcard like Trac* to list multiple pages but NTOC macro cannot hook it. In such case, all the variants will match and be used. It'd be better not to use wildcard with NTOC macro.

[[PageOutline]]

Display a structural outline of the current wiki page, each item in the outline being a link to the corresponding heading.

This macro accepts four optional parameters:

  • The first is a number or range that allows configuring the minimum and maximum level of headings that should be included in the outline. For example, specifying "1" here will result in only the top-level headings being included in the outline. Specifying "2-3" will make the outline include all headings of level 2 and 3, as a nested list. The default is to include all heading levels.
  • The second parameter can be used to specify a custom title (the default is no title).
  • The third parameter selects the style of the outline. This can be either inline or pullout (the latter being the default). The inline style renders the outline as normal part of the content, while pullout causes the outline to be rendered in a box that is by default floated to the right side of the other content.
  • The fourth parameter specifies whether the outline is numbered or not. It can be either numbered or unnumbered (the former being the default). This parameter only has an effect in inline style.

[[ProjectStats]]

Wiki macro listing some generic Trac statistics.

This macro accepts a comma-separated list of keyed parameters, in the form "key=value". Valid keys:

  • wiki — statistics for TracWiki, values:
    • count — show wiki page count
  • prefix — use with wiki key: only names that start with that prefix are included

'count' is also recognized without prepended key name.

[[RecentChanges]]

List all pages that have recently been modified, ordered by the time they were last modified.

This macro accepts two ordered arguments and a named argument. The named argument can be placed in any position within the argument list.

The first parameter is a prefix string: if provided, only pages with names that start with the prefix are included in the resulting list. If this parameter is omitted, all pages are included in the list.

The second parameter is the maximum number of pages to include in the list.

The group parameter determines how the list is presented:

group=date : The pages are presented in bulleted lists that are grouped by date (default).

group=none : The pages are presented in a single bulleted list.

Clone this wiki locally