[[PageOutline(2-5,Contents,pullout)]]
= Add custom date fields to tickets and helps date selection =

== Description ==

This plugin allows for validating custom fields as dates in tickets and also for milestones `due_date` field (some restriction apply).

Currently this will only validate that the given input looks like the specified date format (see below). Date range checking could be added if someone asks nicely enough.

== Usage ==

 1. Install and configure
 2. Pick a date on tickets and milestones

{{{
#!NewsFlash

= Development News =

 * 1.1.0: The jQuery UI component has been downgraded to 1.6 to ensure compatibility with jQuery 1.2.6 that ships with Trac 0.11.x
 * The 0.12 branch is a development branch has been created to support work towards version 2.0 of the plugin. This branch will be far less stable than the 0.11 branch, and only supports Trac 0.12+ at the moment.

}}}

'''0.11 branch''' ------------------- '''Development branch'''

[[Image(DatePickerTrac011.png, 13%)]] [[Image(DateFieldPlugin.png, 15%)]]

== Installation ==

 1. '''Install''' globally with:
{{{
  sudo easy_install https://trac-hacks.org/svn/datefieldplugin/0.11/
}}}
 1. '''Enable''' the plugin by updating TracIni file (..../trac.ini) as follows:
{{{
  [components]
  datefield.* = enabled
}}}
 1. '''Configure''' the project management support for the plugin in its own configuration section, placed into 'trac.ini' file as follows: 
    1. To add a Due Date, just set up the field as a [http://trac.edgewall.org/wiki/TracTicketsCustomFields custom field], or use the CustomFieldAdminPlugin (image right) to create a date field: [[Image(customfields.jpg, right, 20%)]]
{{{
  [ticket-custom]
  due_date = text
  due_date.date = true
  due_date.label = Due Date
  due_date.value = MM-DD-YYYY
  due_date.date_empty = true
}}}
    1. Site-wide defaults for macro arguments may be set at [datefield] section. More details about them see [#Arguments #Arguments section].
{{{
  [datefield]
  format = mdy
  separator = -
  first_day = 1
}}}
 1. '''Restart''' web server on command line:
{{{
#!sh
    $ sudo /etc/init.d/apache2 restart
}}}

=== Arguments ===

This plugin can be controlled with a number of arguments, inside `[datefield]` section contained in `trac.ini` configuration file:

||'''Argument'''  ||'''Version'''  ||'''Description'''	||'''Default[[BR]]value'''
|| `format`|| ||The format to use for dates. valid formats are `dmy`, `mdy`, and `ymd` || `dmy` ||
|| `separator`|| ||The separator character to use for dates. Possible values are `-` or `.` or `/` || `/` ||
|| `first_day`|| >= [6118] ||First day of the week (0=Sunday .. 6=Saturday) || `0` ||
|| `months`|| >= [7192] ||How many months to show at once? || `1` ||
|| `milestone`|| >= [7192] ||Use datepicker for milestone due/complete fields? (format= must match your locale) If you turn this on, you must use `MM/DD/YYYY` for the date format. Set format to `mdy` and separator to `/`. || `false` ||
|| `weeknumbers`|| >= [7192] ||Show ISO8601 week number in calendar? || `false` ||
|| `panel`|| >= [7192] ||Show panel with a "Today" and "Done" buttons (at bottom)? || `false` ||
|| `change_month`|| >= [7192] ||Show a dropdown with month selection?  || `false` ||
|| `change_year`|| >= [7192] ||Show a dropdown with year selection?  || `false` ||
|| `match_request`|| >= [7192] ||Use datepicker on arbitrary request paths. Use text fields with class=datepick in your template, and configure the start of request path (in list format), like: ''match_request = /query,/other_path'' || `` ||
|| `months`|| >= [7192] ||Number of months visible in datepicker  || `1` ||

 * There are many other options, but you need to modify the `datefield.html` template if you want to use them. See [http://docs.jquery.com/UI/Datepicker]

== Bugs/Feature Requests == 

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

If you have any issues, create a '''[/newticket?component=DateFieldPlugin&owner=doki_pen&cc=rjollos new ticket]'''.

=== Known issues ===

 1. If you have the AutoQueryPlugin installed, you'll need to patch the !DateFieldPlugin to work with it, see [http://trac-hacks.org/ticket/6796#comment:4 comment:4:ticket:6796].

== Source & Download ==

You can check out !DateFieldPlugin from '''[http://trac-hacks.org/svn/datefieldplugin here]''' using Subversion, or '''[source:datefieldplugin browse the source]''' with Trac.

Download the zipped source from '''[download:datefieldplugin here]'''.

== Recent Changes ==

[[ChangeLog(datefieldplugin, 2)]]

== Author/Contributors ==

'''Author:''' [wiki:coderanger] [[BR]]
'''Maintainer:''' [wiki:doki_pen], rjollos [[BR]]
'''Contributors:''' [wiki:terje] [[BR]]