[[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). == Usage == `[[TracJSGanttChart(sample=1)]]` displays the sample project from jsgantt.com. `[[TracJSGanttChart(milestone=Test)]]` displays all the tickets in the Test milestone. [[Image(jsGanttSample.PNG)]] === Arguments === The chart display can be controlled with a number of macro arguments: ||'''Argument''' ||'''Version''' ||'''Description''' ||'''Default''' || `caption`|| ||Caption to place to right of tasks: None, `Caption`, `Resource`, `Duration`, `%Complete` || `Resource` || || `comp`|| ||Show (`1`) percent complete column, or do not (`0`). || `1` || || `colorBy`|| ||Field to use to color tasks. Useful fields are `priority`, `owner` and `milestone` but any field can be used. 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. || `priority` || || `dur`|| ||Show (`1`) duration colunn, or do not (`0`). || `1` || || `dateDisplay`|| ||Format to display dates: `mm/dd/yyyy`, `dd/mm/yyyy`, or `yyyy-mm-dd` || `mm/dd/yyyy` || || `endDate`|| ||Show (`1`) end date column, or do not (`0`). || `1` || || `expandClosedTickets`||0.9||Show (`1`) children of closed tickets in the task hierarchy or collapse the subtree (`0`). || `1` || || `format`|| ||Initial display format, one of those listed in `formats` || `day` || || `formats`||||Formats to show for Gantt chart. A pipe-separated list of `minute`, `hour`, `day`, `week`, `month`, and `quarter`. || `day|week|month|quarter` || || `goal`|| 0.9 ||Ticket(s) to show predecessors of. When using something like MasterTicketsPlugin to maintain ticket dependencies, you may create a Gantt showing a ticket and all of its predecessors with `goal=`. The macro uses the configured `succ` field to find all predecessor tasks and build an `id=` argument for Trac's native query handler.[[br]][[br]]Multiple goals may be provided like `goal=1|12|32`.[[br]][[br]]When used in a ticket description or comment, `goal=self` will display the current ticket's predecessors.|| None || || `hoursPerDay`|| ||Hours worked per day || `8.0` || || `lwidth`|| ||Width (in pixels) of left table (The one contains task names, etc. on the left of the Gantt chart.) || None || || `omitMilestones`||0.8||Show milestones for displayed tickets (`0`) or only those specified by `milestone=` (`1`). || `0` || || `openLevel`|| ||How many levels of task hierarchy to show open. `1` = only top level task. || `999` || || `res`|| ||Show (`1`) resource column, or do not (`0`). || `1` || || `root`|| ||Ticket(s) to show descendants of. 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.[[br]][[br]]Multiple roots may be provided like `root=1|12|32`.[[br]][[br]]When used in a ticket description or comment, `root=self` will display the current ticket's descendants.|| None || || `sample`|| ||Display (`1`) sample tasks in Gantt, or do not (`0`) || `0` || || `schedule`|| ||Schedule algorithm: as-last-as-possible (`alap`) or as-soon-as-possible (`asap`) || `alap` || || `showdep`|| ||Show (`1`) dependencies in Gantt, or do not (`0`). || `1` || || `startDate`|| ||Show (`1`) start date column, or do not (`0`). || `1` || || `userMap`||0.8||Map (`1`) user IDs to full names, or do not (`0`). || `1` || Site-wide defaults for macro arguments may be set in the `[trac-jsgantt]` section of `trac.ini`. Where `option.` overrides the built-in default for `` from the table above. All other macro arguments are treated as TracQuery specification (e.g., milestone=MS1|MS2) to control which tickets are displayed. == Installation == 1. '''Install''' globally with: {{{ sudo easy_install https://trac-hacks.org/svn/tracjsganttplugin/0.11/ }}} 1. '''Enable''' the plugin by updating TracIni file (..../trac.ini) as follows: {{{ [components] tracjsgantt.* = enabled }}} 1. '''Configure''' the project management support for the plugin in its own configuration section, placed into 'trac.ini' file as follows: {{{ [TracPM] # To work with TimingAndEstimationPlugin for percent complete, define ticket fields to use as the data source for: fields.estimate = estimatedhours fields.worked = totalhours # Each unit in estimate is 1/8 of a day days_per_estimate = 0.125 # To work with MasterTicketsPlugin for dependencies, define ticket fields to use as the data source for predecessor (pred) and successor (succ). fields.pred = blockedby fields.succ = blocking # To work with SubticketsPlugin for parent/child relationships, ## Ticket field to use as the data source for the parent fields.parent = parents # To work with ChildTickets plugin parent_format, '#%s', # Format of ticket IDs in parent field (default: %s). parent_format = %s # Custom fields for start and due dates ## Ticket field to use as the data source for start date (default: None) fields.start = userstart ## Ticket field to use as the data source for finish date (default: None) fields.finish = userfinish # Format for ''start'' and ''finish'' date strings (default: '%Y-%m-%d') date_format = %Y-%m-%d # Ticket type for milestone-like tickets (default: 'milestone') #milestone_type = milestone # Ticket field to use as the data source for the percent complete column (default: None). fields.percent = complete # Hours represented by each unit of estimated work (default: 1). hours_per_estimate = 1 # Default work for an unestimated task, same units as estimate (default: 4.0). default_estimate = 4.0 # How much work may be remaining when a task goes over estimate, same units as estimate (default: 0.0).. estimate_pad = 0.0 }}} * See [#Configuration configuration details] below for explanations and more options. * Additionally, site-wide defaults for macro arguments may be set at [trac-jsgantt] section. More details about them see [#Arguments #Arguments section]. {{{ [trac-jsgantt] option.formats = day|week|month|quarter option.format = month ## How and which 'columns' to show option.lwidth = 300 option.res = 0 option.dur = 0 option.comp = 0 option.startDate = 0 option.endDate = 1 option.dateDisplay = yyyy-mm-dd ## How and what to show on Gantt graph option.showdep = 1 option.expandClosedTickets = 1 option.schedule = asap option.openLevel = 0 option.colorBy = priority option.userMap = 0 option.omitMilestone = 0 option.caption = Resource option.hoursPerDay = 8.0 }}} 1. '''Restart''' web server on command line: {{{ #!sh $ sudo /etc/init.d/apache2 restart }}} === Configuration details === !TracJsGanttPlugin 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. All of the `fields.*` items name custom fields which may contain data for the Gantt. * When `fields.estimate` and `fields.worked` are both configured, the plugin attempts to display (100 * `fields.worked`/`fields.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 `fields.pred` and `fields.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 `fields.parent` is configured, it is the field which holds the parent ticket number. The example works with SubticketsPlugin. 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. (`parent_format` determines the format of the content of the `parent` field. Use "%s" (default) for SubticketsPlugin, or "#%s" for ChildTicketsPlugin.) * When `fields.start` and `fields.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 `fields.start` and `fields.finish`. If these fields are not configured, all tasks end today and have a 1-day duration. * When `fields.estimate` and `fields.finish` are both configured (and `fields.start` is not configured or not on the ticket), the plugin attempts to determine the start of the task from `fields.finish` and `fields.estimate` as `start = fields.finish - fields.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. == Bugs/Feature Requests == Existing bugs and feature requests for !TracJsGanttPlugin are [report:9?COMPONENT=TracJsGanttPlugin here]. If you have any issues, create a [/newticket?component=TracJsGanttPlugin&owner=ChrisNelson new ticket]. === Known issues === * None === Planned enhancements === 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. Display critical path 1. Display slack time == Source & Download == You can check out !TracJsGanttPlugin from [http://trac-hacks.org/svn/tracjsganttplugin here] using Subversion, or [source:tracjsganttplugin browse the source] with Trac. Download the zipped source from [download:tracjsganttplugin here]. === Recent Changes === [[ChangeLog(tracjsganttplugin, 10)]] == Author/Contributors == '''Author:''' [wiki:ChrisNelson] [[BR]] '''Maintainer:''' [wiki:ChrisNelson] [[BR]] '''Contributors:''' [wiki:rjollos], [wiki:bof], Matt Sable