[[PageOutline(2-5,Contents,pullout)]] = Trac jsGantt plugin = == Description == A plugin which allows Trac ticket data to be displayed in a [http://jsgantt.com jsGantt] chart in a wiki page. Tasks and milestones are links to the corresponding ticket or milestone. Configurable field names allow integration with other plugins such as MasterTicketsPlugin (for dependencies), SubticketsPlugin (for parent/child relationships) and TimingAndEstimationPlugin (for estimated and total hours). == Bugs/Feature Requests == Existing bugs and feature requests for TracJsGanttPlugin are [report:9?COMPONENT=TracJsGanttPlugin here]. If you have any issues, create a [http://trac-hacks.org/newticket?component=TracJsGanttPlugin&owner=ChrisNelson new ticket]. == Download == Download the zipped source from [download:tracjsganttplugin here]. == Source == You can check out TracJsGanttPlugin from [http://trac-hacks.org/svn/tracjsganttplugin here] using Subversion, or [source:tracjsganttplugin browse the source] with Trac. == Installation == 1. [#Download Download] the source and run: {{{ python setup.py bdist_egg }}} 2. Install it in one of the following ways: {{{ cp dist/*.egg path/to/trac/env/plugins }}} {{{ easy_install dist/*.egg }}} 3. Enable the plugin in {{{trac.ini}}} as follows: {{{ [components] tracjsgantt.* = enabled }}} == Example == `[[TracJSGanttChart(sample=1)]]` displays the sample project from jsgantt.com. `[[TracJSGanttChart(milestone=Test)]]` displays all the tickets in the Test milestone. [[Image(jsGanttSample.PNG)]] == Configuration == Trac-jsGantt is intended to be flexible enough to get data from various plugins by configuring the field names for those plugins in `trac.ini`. It is known to work with TimingAndEstimationPlugin (for estimated and total hours), MasterTicketsPlugin (for FS dependencies), and SubticketsPlugin for parent/child relationships. Custom fields for start and finish date are also supported. Tasks are colored based on ticket attributes. When colored by priority colors are consistent with the colors used in Trac reports. Other coloring choices (e.g., by milestone or owner) use arbitrary, unique colors. Your `trac.ini` may include: {{{ [trac-jsgantt] # To work with Timing and Estimation for percent complete fields.estimate = estimatedhours fields.worked = totalhours # Each unit in estimate is 1/8 of a day days_per_estimate = 0.125 # To work with Master Tickets for dependencies fields.pred = blockedby fields.succ = blocking # To work with Subtickets for parent/child relationships fields.parent = parents # Custom fields for start and due dates fields.start = userstart fields.finish = userfinish # date_format = %Y-%m-%d milestone_type = milestone }}} All of the `fields.*` items name custom fields which may contain data for the Gantt. When `estimate` and `worked` are both configured, the plugin attempts to display (100 * worked/estimate) as the percent complete. The example works with TimingAndEstimationPlugin. Alternatively, if `percent` is configured, the plugin attempts to display it as the percent complete (it should be a number from 0 to 100). If none of those are configured, all tasks will be marked as 0% complete. When `pred` and `succ` are configured the plugin uses them to determine the task dependencies. The example works with MasterTicketsPlugin. If these fields are not configured, no dependencies are shown. When `parent` is configured, it is the field which holds the parent ticket number. The example works with Subtickets. If this field is not configured, no parent/child relationship will be displayed. If it is configured, the Gantt can be collapsed by the user to show or hide subtasks. When `start` and `finish` are configured, the plugin uses them to set task start and finish dates. The `date_format` field is a Python `strptime()` format specifier which describes the contents of `start` and `finish`. If these fields are not configured, all tasks end today and have a 1-day duration. When `estimate` and `finish` are both configured (and `start` is not configured or not on the ticket), the plugin attempts to determine the start of the task from `finish` and `estimate` as `start = finish - estimate` with consideration for weekends and hours per day. The `milestone_type` may be used to have a custom ticket type show up as milestones on the chart. If this field is not specified, only Trac milestones are displayed as milestones. == Arguments == The chart display can be controlled with a number of macro arguments: * format - Initial display format: day (default), week, month, or quarter * sample - Display sample tasks (1) or not (0; default) * res - Show resource column (1; default) or not (0) * dur - Show duration colunn (1; default) or not (0) * comp - Show percent complete column (1; default) or not (0) * caption - Caption to place to right of tasks: None, Caption, Resource (default), Duration, %Complete * startDate - Show start date column (1; default) or not (0) * endDate - Show end date column (1; default) or not (0) * dateDisplay - Date display format: 'mm/dd/yyyy' (default), 'dd/mm/yyyy', or 'yyyy-mm-dd' * openLevel - Number of levels of tasks to show. 1 = only top level task. 999 is the default. * colorBy - Field to use to choose task colors. Each unique value of the field will have a different color task. Defaults to priority. Other likely useful values are owner and milestone but any field can be used. * root - When using something like Subtickets plugin to maintain a tree of tickets and subtickets, you may create a Gantt showing a ticket and all of its descendants with `root=`. The macro uses the configured `parent` field to find all descendant tasks and build an `id=` argument for Trac's native query handler. (Note multiple roots may be provided like `root=1|12|32`.) * lwidth - The width, in pixels, of the table of task names, etc. on the left of the Gantt. All other macro arguments are treated as TracQuery specification (e.g., milestone=MS1|MS2) to control which tickets are displayed. == Known issues == 1. Only one chart can be displayed per page. == Planned enhancements == 1. Allow configuration of default task duration. 1. Display a legend of task colors and their meaning (e.g., which milestone or owner they represent). 1. Allow some tasks to be open or closed by default. 1. Figure out finish date if start and estimate are provided. == Recent Changes == [[ChangeLog(tracjsganttplugin, 3)]] == Author/Contributors == '''Author:''' [wiki:ChrisNelson] [[BR]] '''Maintainer:''' [wiki:ChrisNelson] [[BR]] '''Contributors:'''