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

= Ticket list in a box on the wiki page

== News
This macro is unified for several Trac versions (0.9, 0.10, 0.11, 0.12dev) since 2008-07-31 (r4088).
Note that the repository structure has changed and the version directory does no longer exist.
Get the latest source from [http://trac-hacks.org/svn/ticketboxmacro/TicketBox.py here].

== Description

This macro displays the list of ticket numbers in a box on the right side of the page compactly.
You can specify the tickets explicitly or use the result of reporting.
The tickets will be displayed as sorted and uniq'ed.
An example image is shown on the right of this page.

'''Note''': 'query' format is not yet supported.

{{{
#!html
<img src="http://trac-hacks.org/svn/ticketboxmacro/TicketBox-image.png"
 title="sample image" style="float:right"/>
}}}

== Bugs/Feature Requests

Existing bugs and feature requests for TicketBoxMacro are [query:status!=closed&component=TicketBoxMacro&order=priority here].

If you have any issues, create a 
[/newticket?component=TicketBoxMacro&owner=gotoh new ticket].

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

== Download and Source

 * [source:ticketboxmacro Browse with Trac].
 * checkout with subversion from [/svn/ticketboxmacro repository] for any Trac version.

Notes:
 * 2008/07/31 : Files for each trac versions are unified.
 * 2008/03/28 : [source:ticketboxmacro/0.8/#2848 TicketBoxMacro for 0.8] is obsoleted.

== Installation

For Trac 0.10 or before, copy `TicketBox.py` to `wiki-macros` directory of your Trac environment or system wide `wiki-macros` directory.

For Trac 0.11 or later, copy `TicketBox.py` to `plugins` directory of your Trac environment and there is no need enable this plugin explicitly.
Or copy it to system wide `plugins` directory then enable the `TicketBox` plugin via the admin page.

== Usage

These example shows the simple list of tickets by specifiying ticket numbers.
'#' character can be omitted:
{{{
[[TicketBox(#1,#7,#31)]]
[[TicketBox(1,7,31)]]
}}}

These examples list the tickets from the report result.
The third example uses the dynamic variable 'COMPONENT'.
The special variable 'USER' is always available and it is your login name, or 'anonymous' if not logged in.
You can override the variable 'USER' like in the fourth example.
{{{
[[TicketBox({1})]]
[[TicketBox([report:1])]]
[[TicketBox([report:9?COMPONENT=TicketBox])]]
[[TicketBox([report:9?USER=foo])]]
}}}

If field name of ticket id is not 'ticket' in report report definition, you can specify by `ticket=xxx`:
{{{
[[Ticketbox({20},ticket=id)]]
}}}

TracQuery style of query string can be used.
And it can also be used in report defintion, starting with `query:`:
{{{
[[TicketBox([query:status=new])]]
}}}

The combination of above is allowed.
The tickets are listed as sorted and uniq'ed:
{{{
[[TicketBox({1},#50,{2},[query:keywords~=important],100)]]
}}}

If `nosort` option is specified, tickets are listed without sorting:
{{{
[[TicketBox(3,2,1,{1},nosort)]]
}}}

== Display Options

You can specify the size of the box:
{{{
[[TicketBox(500pt,{1})]]
[[TicketBox(200px,{1})]]
[[TicketBox(25%,{1})]]
}}}

You can specify the title.
The value should be surrounded by a single quote or a double quote.
You can also embed the number of tickets by '%d' in title string like in the third example:
{{{
[[TicketBox('Related Tickets',#1,#2)]]
[[TicketBox("Related Tickets",#1,#2)]]
[[TicketBox("There are %d tickets",{1})]]
}}}

If you do not want the box to be floating, use the `inline` keyword.
The box is placed inline with the wiki text.
If you want the ticket's summary to be displayed, use the `summary` keyword:
{{{
[[TicketBox({1},inline)]]
[[TicketBox({1},summary,inline)]]
}}}

`nowrap` forces no wrap of line. It is useful with summary option.
If this option is specified, line length may exceeds specified `width`:
{{{
[[TicketBox({1},summary,nowrap)]]
}}}

Text color, background color, border line color and float position can be specified:
{{{
[[TicketBox({1},float=left,color=green,background=transparent,border-color=red)]]
}}}

== Recent Changes

[[ChangeLog(ticketboxmacro,3)]]

== Author/Contributors

'''Author:''' [wiki:gotoh gotoh] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''