[[PageOutline(2-5,Contents,pullout)]]

= Some useful Trac macros

== Description

This collection of macros extends Trac's capabilities. It works by embedding these snippets in Trac wiki pages: 

=== !ConfigOptionMacro

Insert configuration options in Wiki pages.

==== !WikiHistoryMacro

Embed information about wiki changelog in wiki pages. If invoked without keyword arguments then the full changelog is shown inside a table with columns `Date`, `Version`, `Description`, `Author`. Please read below for further details.

== Bugs/Feature Requests

Existing bugs and feature requests for TracBasicMacro are 
[report:9?COMPONENT=TracBasicMacro here].

If you have any issues, create a 
[/newticket?component=TracBasicMacro new ticket].

If you want to submit patches, please read the 
[wiki:olemis#Guidelinestocollaborate patch submission guidelines].

[[TicketQuery(component=TracBasicMacro&group=type,format=progress)]]

== Download

Download the zipped source from [pypi:TracBasicMacros PyPI].

== Source

You can check out TracBasicMacro from [http://bitbucket.org/olemis/trac-basic-macros its Bitbucket repository] using '''Mercurial'''. Currently it is not possible to [source:tracbasicmacro browse the source] with Trac.

== Example

Install the plugin and enable [TracBasicMacro TracBasicMacros] plugin by inserting the following lines in [TracIni trac.ini].

{{{#!ini
[components]
tracbmacros.* = enabled
}}}

All the macros will be ready to use in your Trac environment:
 - `[[ConfigOption(project, name)]]` displays project name.
 - `[[ConfigOption(trac, auto_reload, type=bool)]]` displays a check-box indicating whether the option is set or not.
 - `[[ConfigOption(trac, auto_reload)]]` idem. the macro is able to lookup metadata describing the option (if it's registered in the global `Option`'s registry).
 - `[[ConfigOption(olemis, simelo, type=text)]]` displays the specified text.
 - `[[ConfigOption(timeline, default_daysback, type=int)]]` displays default number of days displayed in the `Timeline`, in days. Integers are displayed like this `30`.
 - `[[ConfigOption(trac, metanav, type=list)]]` Display a list of ''metanav'' options. Output looks like this:
   - login
   - search
   - help
 - `[[ConfigOption(trac, permission_store, type=extension)]]` display the component responsible of storing user permissions.
 - `[[ConfigOption(trac, permission_policies, type=extension_list)]]` display active permission policies.
 - `[[ConfigOption(trac, permission_policies, type=extension_list, include_missing=true)]]` display all permission policies, active first.

For up-to-date documentation consult `TracMacros` page in your local environment.

'''Important:''' Administrator must specify permissions (i.e. permission names) needed to view a particular configuration option by adding entries under `config-perm` section in [TracIni trac.ini]. Option names will be of the form `section.option`, `section.*` or `*` to make reference respectively to a particular option, all options in a section, or any option. For instance, the following configuration:

{{{#!ini
[config-perm]
* = TRAC_ADMIN
project.* = WIKI_VIEW
project.name = *
}}}

will allow users with `TRAC_ADMIN` privilege to see any option, whereas all those able to read wiki pages may see any option under `project` section. Finally, any user will be able to see the project name.

 - `[[WikiHistory]]` lists versions of current wiki page (or `WikiStart` if wiki text inserted elsewhere e.g. in a ticket's comment).
 - `[[WikiHistory(,4)]]` lists versions of current wiki page (or `WikiStart` if wiki text inserted elsewhere e.g. in a ticket's comment) up to version 4.
 - `[[WikiHistory(TracGuide,cols=time:version:author)]]` lists versions of `TracGuide` wiki page but hides user comments.
 - `[[WikiHistory(,cols=time:comment)]]` lists versions of current wiki page (or `WikiStart` if wiki text inserted elsewhere e.g. in a ticket's comment). Only shows modification time and user comment.
 - `[[WikiHistory(TracGuide,19,cols=time:comment)]]` lists versions of `TracGuide` wiki page up to version 19. Only shows modification time and user comment.
  - `[[WikiHistory(,attr=time)]]` displays last modification time of current wiki page (or `WikiStart` if wiki text inserted elsewhere e.g. in a ticket's comment)
  - `[[WikiHistory(TracPermissions,2,attr=time)]]` displays modification time of version 2 of `TracPermissions` wiki page.

== Author/Contributors

'''Author:''' [wiki:olemis Olemis Lang] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''