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

= iCalendar plugin for ticket queries

== Description

This plugin provides iCalendar feeds for ticket queries as standard [http://trac.edgewall.org/roadmap roadmap module]. It uses 2 optional custom fields: event date and duration.

With this plugin you can add a iCalendar link in the ticket's queries footer. A current limitation of this plugin is that the calendar is read only.

There is no configuration needed to start using the plugin. Without start date and duration, tickets can use the due date of associated milestone. To plan tickets the date and duration fields must be set in your `trac.ini` file.

=== Setup custom fields for date and duration

To transform a ticket to an event, we need at least one date. Trac only provides a creation date or an update date. So we need a planned date by adding a custom field, and set this new field as the dtstart field for events in (see [http://tools.ietf.org/html/rfc2445 RFC/2445]).

Sample `trac.ini` file:

{{{#!ini
[ticket-custom]
my_custom_dtstart_field = text
my_custom_dtstart_field.label = Planned Date

[icalendar]
dtstart = my_custom_dtstart_field
}}}

We also need a duration field:
{{{#!ini
[ticket-custom]
...
my_custom_duration_field = text
my_custom_duration_field.label = Duration

[icalendar]
duration = my_custom_duration_field
}}}

=== Date and duration input format

Default input date format are: 
 * "'%m/%d/%Y" (month/day/year) for strict date.
 * "%m/%d/%Y %H:%M" for date and time.

To customize this format, use the "short_date_format" and "date_time_format" configuration options:

{{{#!ini
[icalendar]
short_date_format = %d/%m/%Y
date_time_format = %d/%m/%Y %H:%M
}}}

To support multiple formats, use a ';' to separate them:

{{{#!ini
[icalendar]
short_date_format = %d/%m/%Y;%Y-%m-%d
date_time_format = %d/%m/%Y %H:%M;%Y-%m-%d %H:%M
}}}

Duration field supports the following syntaxes:
 * Standard hours:minutes format: H:MM, examples: "8:45", "12:30".
 * A number of days ending by a 'd', example: 15d.
 * Standard [http://tools.ietf.org/html/rfc2445#section-4.3.6 RFC/2445] duration beginning  with a "P": "P1W" "P1D".

Some tips:
 * Tickets with a planned date and no duration are planned as a day event.
 * Tickets without a planned date are transformed as TODO. For tickets attached to a milestone, the due date of the milestone is used as TODO due date (since 0.2).

=== Priority

iCalendar supports the priority tags, but uses an integer from 1 (highest) to 9 (lowest). So we need a map to transform Trac priorities to integer. The plugin integrates a default mapping:

{{{
'blocker': 1
'critical': 2
'major': 6
'minor': 8
'trivial': 9
}}}

You can customise the mapping and adding other values with the configuration option 'custom_priority_map':

{{{#!ini
[icalendar]
custom_priority_map = major:3;lessmajor:4;lessmajorbutnotminor:5;crazy:1;undefined:0
}}}

== Bugs/Feature Requests

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

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

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

== Download

Download the zipped source from [export:icalviewplugin here].

== Source

You can check out IcalViewPlugin from [/svn/icalviewplugin here] using Subversion, or [source:icalviewplugin browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

== Release notes

=== 0.4

 * Adding description of tickets (#6323 thanks to clown for the patch). We do not yet filter Wiki tags from description, I hope to fix it in a future release.
Resolve some problems:
 * Fix #6325 : charset bug which can stop installation (thanks to clown for the patch)
 * Fix #6322 : bug with user defined priority (thanks to clown for the patch)

=== 0.3

 * Better support for timezone.

=== 0.2

 * Adding support for milestone due date for tickets without not planned.

=== 0.1

 * Initial release

== Recent Changes

[[ChangeLog(icalviewplugin, 3)]]

== Author/Contributors

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