Trac Macros

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.

The macro syntax is [[macro-name(optional-arguments)]].

WikiProcessors are another kind of macro, commonly used for source code highlighting using a processor like !#python or !#apache:

{{{#!wiki-processor-name
... 
}}}

Using Macros

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':

Wiki Markup	Display
[[RecentChanges(Trac,3)]]	2024-03-05 TracWorkflow (diff) TracWiki (diff) TracUpgrade (diff)

Getting Detailed Help

The list of available macros and the full help can be obtained using the MacroList macro, see 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?]].

Available Macros

[[Image]]

Inserisci una immagine nel testo formattato.

Il primo parametro è la specifica del file, che può referenziare un allegato in tre modi:

• modulo:id:file, dove modulo può essere o wiki oppure ticket, per riferirsi all'allegato con nome file della pagina wiki o della segnalazione indicata.
• id:file: come sopra, ma id può essere il riferimento a una segnalazione oppure il nome di una pagina Wiki.
• file per riferirsi all'allegato con nome file della medesima pagina o segnalazione.

La specifica può anche referenziare:

• un file contenuto nel repository, usando la sintassi source:file (o più specificamente source:file@rev).
• un file, specificando direttamente un URL: con /file si indica una posizione relativa al progetto, con //file una relativa al server, oppure con http://server/file per una posizione assoluta. Può anche essere usato un prefisso InterWiki.
• un contenuto embedded, usando lo schema ​data: in tal caso l'URL deve essere delimitato da virgolette.

I parametri rimanenti sono opzionali e consentono di configurare gli attributi e lo stile usato per rendere l'elemento <img>:

• numeri e unità vengono interpretati come dimensione dell'immagine (ad esempio 120px, 25%)
• right, left, center, top, bottom e middle sono interpretati come l'allineamento dell'immagine (in alternativa, i primi tre possono essere espressi con align=... e gli ultimi tre con valign=...)
• link=qualche TracLink... sostituisce il link alla sorgente dell'immagine con il TracLink specificato. Se non viene specificato nessun valore, il link viene semplicemente rimosso.
• inline indica che il contenuto sarà reso come un elemento XHTML inline. Di default i contenuti inline non vengono generati, quindi le immagini non vengono rese nelle intestazioni di sezione e in altri contenuti a singola riga.
• nolink per omettere il link al sorgente dell'immagine (deprecato, usare link=)
• chiave=valore viene interpretato come un attributo HTML o come indicazione di uno stile CSS per l'immagine. Le chiavi valide sono:
  • align, valign, border, width, height, alt, title, longdesc, class, margin, margin-(left,right,top,bottom), id e usemap
  • border, margin e margin-* accettano solamente un singolo numero (l'unità di misura è il pixel)
  • margin è stato sostituito da center che utilizza i margini automatici

Esempi:

[[Image(foto.jpg)]]                           # il più semplice
[[Image(foto.jpg, 120px)]]                    # con dimensione immagine
[[Image(foto.jpg, right)]]                    # allineata con chiave
[[Image(foto.jpg, nolink)]]                   # senza link alla sorgente
[[Image(foto.jpg, align=right)]]              # allineata con attributo

Puoi usare una immagine allegata a una pagina wiki, a una segnalazione o a un altro modulo.

[[Image(OtherPage:foo.bmp)]]    # da una pagina wiki
[[Image(base/sub:bar.bmp)]]     # da una pagina wiki gerarchica
[[Image(#3:baz.bmp)]]           # da una particolare segnalazione
[[Image(ticket:36:boo.jpg)]]    # sintassi alternativa per referenziare una segnalazione
[[Image(source:/img/bee.jpg)]]  # dal repository
[[Image(htdocs:foo/bar.png)]]   # dalla directory htdocs del progetto
[[Image(shared:foo/bar.png)]]   # dalla directory htdocs condivisa (dalla versione 1.0.2)

Adattata dalla macro Image.py creata da Shun-ichi Goto <gotoh@…>

[[InterTrac]]

Fornisce la lista dei prefissi InterTrac noti.

[[InterWiki]]

Fornisce una lista descrittiva dei prefissi InterWiki noti.

[[KnownMimeTypes]]

Elenca tutti i mime-type conosciuti che possono essere usati come WikiProcessor.

Come argomento opzionale si può specificare un filtro sui mime-type.

[[MacroList]]

Mostra la lista di tutte le macro Wiki installate, compresa la relativa documentazione, se disponibile.

Come argomento opzionale si può specificare il nome di una macro specifica. In questo caso, verrà mostrata solo la documentazione della macro specificata.

Nota che questa macro non sarà in grado di mostrare la documentazione delle macro se in mod_python è stata specificata l'opzione PythonOptimize!

[[PageOutline]]

Mostra il sommario della pagina wiki corrente, e ogni elemento del sommario è un link al titolo corrispondente.

Questa macro accetta quattro parametri opzionali:

• Il primo è una numero o intervallo che permette di specificare il livello minimo e massimo di titolo da includere nel sommario. Ad esempio, specificando "1" si otterranno nel sommario solo i titoli principali. Specificando "2-3", il sommario comprenderà tutti i titoli di livello 2 e 3, come lista innestata. Il default è di includere tutti i livelli.
• Il secondo parametro serve a specificare un titolo per il sommario (il default è nessun titolo).
• Il terzo parametro seleziona lo stile per il sommario. I valori ammessi sono inline e pullout (il secondo è il default). Lo stile inline mostra il sommario come parte integrante della pagina, mentre pullout lo mostra in un rettangolo, di default posizionato in alto a destra della pagina.
• Il quarto parametro specifica se il sommario debba essere o meno numerato. I valori ammessi sono numbered o unnumbered (il primo è il default). Questo parametro ha effetto solo nel formato inline.

[[RecentChanges]]

Elenca tutte le pagine modificate di recente, ordinate per orario di ultima modifica.

Questa macro accetta due argomenti ordinali e un argomento con nome. L'argomento con nome può essere posizionato ovunque nella lista di argomenti.

Il primo argomento è una stringa di prefisso: se specificata, la lista comprenderà solo le pagine i cui nomi iniziano con tale prefisso. Altrimenti, la lista comprenderà tutte le pagine.

Il secondo parametro è il massimo numero di pagine da includere nella lista.

Il parametro group determina come viene presentata la lista:

group=date

Le pagine sono presentate in liste puntate, raggruppate per data (default).

group=none

Le pagine sono presentate in un'unica lista puntata.

Suggerimento: se vuoi specificare solo il numero massimo di elementi da visualizzare e non vuoi specificare un prefisso, basta lasciare vuoto il primo parametro. Es.: [[RecentChanges(,10,group=none)]].

[[RepositoryIndex]]

Display the list of available repositories.

Can be given the following named arguments:

format

Select the rendering format:

• compact produces a comma-separated list of repository prefix names (default)
• list produces a description list of repository prefix names
• table produces a table view, similar to the one visible in the Browse View page

glob

Do a glob-style filtering on the repository names (defaults to '*')

order

Order repositories by the given column (one of "name", "date" or "author")

desc

When set to 1, order by descending order

[[SubscriberList]]

Mostra la lista di tutti i notification subscriber installati, compresa la relativa documentazione, se disponibile.

Come argomento opzionale si può specificare il nome di un particolare subscriber. In questo caso, verrà mostrata solo la documentazione di quello specifico subscriber.

Nota che questa macro non sarà in grado di mostrare la documentazione dei subscriber se in mod_python è stata specificata l'opzione PythonOptimize!

[[TicketQuery]]

Elenca le segnalazioni che corrispondono a certi criteri.

Questa macro accetta una lista di parametri nella forma "chiave=valore" separati da virgole.

Quando la chiave è il nome di un campo, la sintassi del valore deve corrispondere a quella dei filtri, definita in TracQuery#QueryLanguage. Nota che non si tratta della medesima sintassi semplificata usata nei URL di collegamento query: che cominciano con il carattere ?. È possibile includere delle virgole (,) nei valori precedendole con un backslash (\\).

Per utilizzare una serie di alternative separare i singoli criteri con l'operatore or.

Oltre ai criteri di filtro, è possibile usare diversi altri parametri, tutti opzionali, per controllare la presentazione dei risultati.

Il parametro format determina come verrà presentata la lista delle segnalazioni:

• list -- la presentazione di default è un elenco di segnalazioni, una per riga, con l'ID seguito dal suo sommario.
• compact -- le segnalazioni verranno presentate come una lista di ID separati da virgole.
• count -- verrà mostrato solo il numero di segnalazioni corrispondenti.
• rawcount -- verrà mostrato solo il numero di segnalazioni corrispondenti, senza neanche il collegamento alla ricerca effettuata (dalla 1.1.1).
• table -- una vista simile a quella delle ricerche personalizzate (ma senza i controlli).
• progress -- una vista simile ai grafici mostrati negli obiettivi.

Il parametro max può essere usato per limitare il numero di segnalazioni mostrate (di default 0, cioè illimitato).

Il parametro order imposta il campo utilizzato per ordinare le segnalazioni (di default il campo id).

Il parametro desc indica se l'ordinamento delle segnalazioni debba essere invertito (di default false).

Il parametro group imposta il campo utilizzato per raggruppare le segnalazioni (di default non viene effettuato alcun raggruppamento).

Il parametro groupdesc indica se l'ordine di visualizzazione dei gruppi debba essere invertito (di default false).

Il parametro verbose può essere impostato a un valore true per ottenere la descrizione delle segnalazioni elencate. Solo per il formato table. deprecato, sostituito dal parametro rows.

Il parametro rows può essere usato per specificare il campo, o i campi, da visualizzare, ad esempio rows=description|summary.

Il parametro col può essere usato per specificare quali campi debbano essere visualizzati come colonne. Solo per il formato table.

Per compatibilità con Trac 0.10, l'eventuale ultimo parametro posizionale verrà usato per specificare il format. Inoltre, è ancora consentito l'utilizzo di "&" come separatore dei campi (tranne che nel caso di order), ma è deprecato.

[[TitleIndex]]

Insert an alphabetic list of all wiki pages into the output.

Accepts a prefix string as parameter: 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 listed. If the prefix is specified, a second argument of value hideprefix can be given as well, in order to remove that prefix from the output.

The prefix string supports the standard relative-path notation when using the macro in a wiki page. A prefix string starting with ./ will be relative to the current page, and parent pages can be specified using ../.

Several named parameters can be specified:

• format=compact: The pages are displayed as comma-separated links.
• format=group: The list of pages will be structured in groups according to common prefix. This format also supports a min=n argument, where n is the minimal number of pages for a group.
• format=hierarchy: The list of pages will be structured according to the page name path hierarchy. This format also supports a min=n argument, where higher n flatten the display hierarchy
• depth=n: limit the depth of the pages to list. If set to 0, only toplevel pages will be shown, if set to 1, only immediate children pages will be shown, etc. If not set, or set to -1, all pages in the hierarchy will be shown.
• include=page1:page*2: include only pages that match an item in the colon-separated list of pages. If the list is empty, or if no include argument is given, include all pages.
• exclude=page1:page*2: exclude pages that match an item in the colon- separated list of pages.

The include and exclude lists accept shell-style patterns.

[[TracAdminHelp]]

Mostra l'aiuto relativo ai comandi di trac-admin.

Esempi:

[[TracAdminHelp]]               # tutti i comandi
[[TracAdminHelp(wiki)]]         # tutti i comandi del wiki
[[TracAdminHelp(wiki export)]]  # il comando "wiki export"
[[TracAdminHelp(upgrade)]]      # il comando di aggiornamento

[[TracGuideToc]]

Mostra una tabella dei contenuti della guida di Trac.

Questa macro mostra come creare una rudimentale tabella dei contenuti della Aiuto/Guida. La tabella conterrà le pagine Trac* e WikiFormatting e non può essere personalizzata. La ​TocMacro è più versatile.

[[TracIni]]

Produce documentation for the Trac configuration file.

Typically, this will be used in the TracIni page. The macro accepts two ordered arguments and two named arguments.

The ordered arguments are a configuration section filter, and a configuration option name filter: only the configuration options whose section and name start with the filters are output.

The named arguments can be specified:

section

a glob-style filtering on the section names

option

a glob-style filtering on the option names

[[Workflow]]

Render a workflow graph.

This macro accepts a TracWorkflow configuration and renders the states and transitions as a directed graph. If no parameters are given, the current ticket workflow is rendered.

In WikiProcessor mode the width and height arguments can be specified (Defaults: width = 800 and height = 600).

The repository-scoped path of a workflow file can be specified as either a macro or WikiProcessor file argument. The file revision can be specified by appending @<rev> to the path. The file argument value must be enclosed in single or double quotes. (Since 1.3.2).

Examples:

[[Workflow()]]

[[Workflow(go = here -> there; return = there -> here)]]

[[Workflow(file=/contrib/workflow/enterprise-workflow.ini@1)]]

{{{#!Workflow file="/contrib/workflow/enterprise-workflow.ini"
}}}

{{{#!Workflow width=700 height=700
leave = * -> *
leave.operations = leave_status
leave.default = 1

create = <none> -> new
create.default = 1

create_and_assign = <none> -> assigned
create_and_assign.label = assign
create_and_assign.permissions = TICKET_MODIFY
create_and_assign.operations = may_set_owner

accept = new,assigned,accepted,reopened -> accepted
accept.permissions = TICKET_MODIFY
accept.operations = set_owner_to_self

resolve = new,assigned,accepted,reopened -> closed
resolve.permissions = TICKET_MODIFY
resolve.operations = set_resolution

reassign = new,assigned,accepted,reopened -> assigned
reassign.permissions = TICKET_MODIFY
reassign.operations = set_owner

reopen = closed -> reopened
reopen.permissions = TICKET_CREATE
reopen.operations = del_resolution
}}}

Contributed macros

The ​Trac Hacks site provides a large collection of macros and other Trac 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 ​Python programming language and are a type of plugin.

Here are 2 simple examples showing how to create a Macro. For more information about developing macros, see the ​development resources and ​sample-plugins.

Macro without arguments

To test the following code, copy it to timestamp_sample.py in the TracEnvironment's plugins/ directory.

from trac.util.datefmt import datetime_now, format_datetime, utc
from trac.util.html import tag
from trac.wiki.macros import WikiMacroBase

class TimestampMacro(WikiMacroBase):
    _description = "Inserts the current time (in seconds) into the wiki page."

    def expand_macro(self, formatter, name, content, args=None):
        t = datetime_now(utc)
        return tag.strong(format_datetime(t, '%c'))

Macro with arguments

To test the following code, copy it to helloworld_sample.py in the TracEnvironment's plugins/ directory.

from trac.util.translation import cleandoc_
from trac.wiki.macros import WikiMacroBase

class HelloWorldMacro(WikiMacroBase):
    _description = cleandoc_(
    """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).
    """)

    def expand_macro(self, formatter, name, content, args=None):
        """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'`),
        `content` 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 `content` is `None`.
        `args` will contain a dictionary of arguments when called using the
          Wiki processor syntax and will be `None` if called using the
          macro syntax.
        """
        return 'Hello World, content = ' + unicode(content)

Note that expand_macro optionally takes a 4^th parameter args. When the macro is called as a WikiProcessor, it is also possible to pass key=value 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.

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) (from trac.util.html import Markup).

You can also recursively use a wiki formatter to process the content as wiki markup:

from trac.wiki.formatter import format_to_html
from trac.wiki.macros import WikiMacroBase

class HelloWorldMacro(WikiMacroBase):
    def expand_macro(self, formatter, name, content, args):
        content = "any '''wiki''' markup you want, even containing other macros"
        # Convert Wiki markup to HTML
        return format_to_html(self.env, formatter.context, content)