[[PageOutline(2-5,Contents,pullout)]]
= Calendar view of Milestones and Tickets =
== Description ==

Macro for the Trac Wiki to display Milestones and Tickets from the Ticketing system in a calendar view. See screenshot (!WikiTicketCalendarMacro 1.2.0 & Trac 0.12) with different localizations (wikipage links and CSS style ticket tooltip) below:

[[Image(wikiticketcalendar_screenshot.gif)]]

Development of the single-file macros is discontinued.
Code has been merged with WikiCalendarMacro for joined upstream development.
Make sure to change over to the packaged plugin code hosted within the
[source:/wikicalendarmacro /wikicalendarmacro] domain to receive latest improvements and bug fixes.

== Usage ==

The invocation for the screenshot above is `[[WikiTicketCalendar(*,*,true,Wochenberatung/%Y-%m-%d,true,Beratung)]]`.

Macro can be invoked in the following two basic ways:
 A. "Simple"
{{{
    [[WikiTicketCalendar([<year>,<month>,[<nav>,[<wiki>,[<cdate>,[<template>,[<query>,[<short>,[<width>]]]]]]]])]]
}}}
 B. "Advanced"
{{{
    [[WikiTicketCalendar([nav=(0|1)],[wiki=<strftime-expression>],
        [cdate=(0|1)],[base=<template>],[query=<TracQuery-expr>],
        [short=<integer-value>],[width=[+]<valid-CSS-size>])]]
}}}
     - equivalent keyword-argument available for all but first two arguments
     - mixed use of keyword-arguments with simple arguments permitted,
       but strict order of simple arguments (see above) still applies while
       keyword-arguments in-between do not count for that positional mapping,
     - query evaluates a valid TracQuery expression based on any ticket field
       including multiple expressions grouped by 'and' and 'or' 

=== Arguments ===

||'''Argument'''||'''Version'''||'''Description'''||'''Default'''||'''Example'''||
|| `year`|| || specifies the year to be shown, '*' current year || * || year=2011 ||
|| `month`|| || specifies the month to be shown, '*'  current month || * || month=12 ||
|| `nav`|| || (1) show previous/next navigation or (0) not || 1 || nav=1 ||
|| `wiki`|| || strftime format for wiki pages to display as link (if exist, otherwise links to a create page) '*' for default. Supports any expression that strftime can handle  || "%Y-%m-%d" || wiki="%Y-%m-%d" ||
|| `cdate`|| || (1) show ticket created / open dates [1,0] || 1 || cdate=1 ||
|| `base`|| ||wiki template tried to create new page  || "" || base="" ||
|| `query`|| ||evaluates a valid TracQuery expression based on any ticket field including multiple expressions grouped by 'and' and 'or' || || query="id!=0" ||
|| `short`|| ||total ticket count per day, that'll have ticket list display condensed to just ticket no., 0 = never condense list. This feature looks like [attachment:wikiticketcalendar_screenshot_1-2-1.png this] [0,1,...] || 0 || short=0 ||
|| `width`|| ||set calendar table 'min-width', and optionally 'width' for surrounding div triggered by prepending '+' to value || 100% || width=100% ||

=== Examples ===
{{{
    [[WikiTicketCalendar(2006,07)]]
    [[WikiTicketCalendar(2006,07,false)]]
    [[WikiTicketCalendar(*,*,true,Meeting-%Y-%m-%d)]]
    [[WikiTicketCalendar(2006,07,false,Meeting-%Y-%m-%d)]]
    [[WikiTicketCalendar(2006,07,true,*,true)]]
    [[WikiTicketCalendar(2006,07,true,Meeting-%Y-%m-%d,true,Meeting)]]
    [[WikiTicketCalendar(wiki=Talk-%Y-%m-%d,base=Talk)]]
     equivalent to [[WikiTicketCalendar(*,*,true,Talk-%Y-%m-%d,true,Talk)]]
    [[WikiTicketCalendar(wiki=Meeting-%Y-%m-%d,query=type=task&owner=wg1)]]
    [[WikiTicketCalendar(wiki=Meeting_%Y/%m/%d,short=6)]]
    [[WikiTicketCalendar(*,*,true,Meeting-%Y%m%d,width=+75%;)]]
}}}
 

'''Notes''':

1. All maintained versions of this macro support keyword arguments and mixed use of both - simple and keyword arguments - as well.
This could make macro invocations more readable and maybe even shorter than before, as long as you largely stick to the defaults and just want to change one or two values. So i.e. the 3rd example from above could be rewritten now as:
{{{
    [[WikiTicketCalendar(wiki=Meeting-%Y-%m-%d)]]
}}}
2. The ''query'' keyword supports any expression supported by TracQuery. This is the single new ticket selection logic that can use custom field values as well for expressions chained by AND (OR since 0.12 only). An always-true expression was chosen on purpose to select and show all tickets by default. Use your own query expression to create per-developer or per-component ticket calendars,
or you could choose to display tickets only with high/highest priority, tickets with some special content in a custom field, etc.


== Install ==

Generic guidelines on installation and troubleshooting can be found at TracPlugins.

Steps to install and configure this plugin are:

 1. '''Install'''
  1. with easy_install:
{{{
#!sh
$ sudo easy_install https://trac-hacks.org/svn/wikiticketcalendarmacro
}}}
 1. '''Enable'''
  * Update TracIni file (`..../trac.ini`) with:
{{{
#!ini
[components]
wikicalendar.* = enabled
}}}
 1. '''Configure'''
  * The macro optionally makes use of an own configuration section, that could be placed into 'trac.ini' as follows:
{{{
#!ini
[wikicalendar]
ticket.due_field = due_close
ticket.due_field.format = %y-%m-%d
}}}
 1. '''Restart''' web server:
{{{
#!sh
$ sudo /etc/init.d/apache2 restart
}}}

The procedure above enables both, this macro as well as the WikiCalendarMacro.
Both macros are bundled in `wikicalendar-2.0.0` and later.
For historic versions the old instructions are preserved [#Historicnotes below].

=== About i18n/l10n support ===

The 0.12 branch of this plugin is prepared for localization (tooltip customization in calendar navigation).

But English message texts are still the (POSIX) default. If this isn't your preferred language, you can
 1. look, if it's already available from the [TracPluginTranslation Trac plugin l10n project] at [http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/wikiticketcalendar Transifex] or
 2. do it yourself (see the [t:wiki:CookBook/PluginL10N#Dotranslatorswork l10n cookbook page for Trac plugins] for more details).

You've done a new translation? Superb! Contributing your translation is highly appreciated.

You could send it to the plugin's maintainer or contribute to [TracPluginTranslation Trac plugin l10n project]
via [http://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex]:

Top translations: Trac_Plugin-L10N » [http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/etcalendar-locale-messages-pot_0/ etcalendar-locale-messages-pot_0][[BR]]
 [[Image(http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/etcalendar-locale-messages-pot_0/chart/image_png, title=Go to Trac_Plugin-L10N project page on Transifex.net, link=http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/etcalendar-locale-messages-pot_0/)]]

Kindly provided by [[Image(http://sw.transifex.net/3/static/charts/images/tx-logo-micro.png, link=http://www.transifex.net/, title=the open translation platform, valign=bottom)]]

Preparing the plugin from source requires '''no additional steps''' for compiling message catalog files. Only to include translations marked as `# fuzzy` by the translator, you'll want to do a manual message catalog compilation with the extra `-f` argument before packaging:
{{{
cd wikiticketcalendarmacro/
python ./setup.py compile_catalog -f
python ./setup.py bdist_egg
}}} 

Complaints about missing `locale` directory are often a side-effect of failure to compile any message catalog for inclusion into Python egg, hence the whole path is missing. Due to a known Trac issue, Babel has to be installed prior to Trac, to get it all working as expected.

Again, for more details see the [t:wiki:CookBook/PluginL10N#Compileanduseit l10n cookbook page for Trac plugins].


== Bug Reports ==

Get it, enjoy and report back, please. Comments welcome.

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

If you have any issue that is not found [query:component=WikiTicketCalendarMacro&order=priority there], create a 
[/newticket?component=WikiTicketCalendarMacro&owner=hasienda new ticket].

Make sure to send feature requests for the macro bundle only (see WikiCalendarMacro).

[[Poll(What do you think of the WikiTicketCalendarMacro?; Great; Useful; Somewhat useful, but could be better; Useless; Horrible; Don't care/don't need such stuff)]]

== Source & Download ==
For the latest code see WikiCalendarMacro. The information below is historic by now.

You can:
 A. check out !WikiTicketCalendarMacro from [http://trac-hacks.org/svn/wikiticketcalendarmacro here] using Subversion;
 B. or [source:wikiticketcalendarmacro browse the source] and just save a file with the Trac repository browser;
    * [browser:wikiticketcalendarmacro/branches/0.12 0.12] with [#Abouti18nl10nsupport i18n support]
    * [browser:wikiticketcalendarmacro/branches/0.11 0.11]/0.12 ''without'' i18n ^1^
    * [browser:wikiticketcalendarmacro/branches/0.10 0.10] depreciated/unmaintained, security concerns unresolved - see #7239.
 C. or download the zipped source from [download:wikiticketcalendarmacro here];

^1^ Note: The 0.11 single-file macro install is significantly smaller than the Python egg with translations,[[BR]]
and there's no visible difference to the genuine 0.12 version, as long as you don't use localization for Trac 0.12.

^2^ Note: The original version of the macro was hosted [http://macgeek.dyndns.org/software/Trac_WikiTicketCalendar here] and it's outdated.

^3^ Note: For `trunk` development branch look at the WikiCalendarMacro, since code for both macros has been merged.


=== Historic notes ===
These are the old instructions for enabling historic versions of the !WikiTicketCalendarMacro:
{{{
[components]
WikiTicketCalendarMacro.* = enabled
}}}
 for Trac <= 0.11

{{{
[components]
wikiticketcalendar.* = enabled
}}}
 for Trac >= ''0.12'' and ''trunk'' branch with i18n support (have a different code structure due to packaging)

The following configuration instructions apply only to the old code as well:
{{{
[wikiticketcalendar]
ticket.due_field.name = due_close
ticket.due_field.format = %y-%m-%d
}}}
    * Note: these are the implicit default values to give backwards compatible behaviour.
    * Real configuration examples:
      * for a custom due date field named 'due-date' that holds US style date with 4-digit year:
{{{
[wikiticketcalendar]
ticket.due_field.name = due-date
ticket.due_field.format = %m/%d/%Y
}}}
      * for a custom due date field named 'due_date' that holds true POSIX microsecond timestamps (see: [t:wiki:TracDev/Proposals/TracTicketsCustomTimeFields custom time fields proposal])
{{{
[wikiticketcalendar]
ticket.due_field.name = due_date
ticket.due_field.format = ts
}}}


== Author/Contributors ==

'''Author:''' [wiki:mcomb][[BR]]
'''Maintainer:''' [wiki:hasienda][[BR]]
'''Contributors:''' Boris Savelev, [wiki:rjollos]

== See also ==

=== Found on the web ===

 * a heavily modified version used [https://wiki.ctdo.de/#DiesenMonatimCTDO as event calendar], source unknown