[[PageOutline(2-5,Contents,pullout)]] = Display a ​jsGantt chart in a wiki page == Description This is a plugin which allows Trac ticket data to be displayed in a [http://jsgantt.com jsGantt] chart in a wiki page. The library jsGantt itself is BSD licensed and no longer under active development since 2009. 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). Over time, the project management aspects of the Gantt chart have been isolated in the `TracPM` module which has grown to include a query helper (which allows finding tickets based on dependencies) and a ticket change listener (which reschedules tickets based on various constraints) and other support functions. Ultimately, these features - which really have nothing to do with the Gantt chart - will be moved to a separate `TracPM` plugin. == Examples `[[TracJSGanttChart(sample=1)]]` displays the sample project from jsgantt.com. `[[TracJSGanttChart(milestone=Test)]]` displays all the tickets in the Test milestone. [[Image(jsGanttSample.PNG, border=2)]] `[[TracJSGanttChart(goal=1234,schedule=asap)]]` finds all the tickets required for ticket 1234 (by following the Required For dependency) and schedules them As Soon As Possible. In a ticket description or comment, the ticket ID may be replaced by `self`. `[[TracJSGanttChart(root=self)]]` (when used in a ticket description or comment) finds all the tickets which are descendants of the current ticket (by following the parent/child relationship) and scheduled them As Late As Possible (the default algorithm). (`self` can be replaced by one or more pipe-delimited ticket IDs as for the `id` option, e.g., `root=1|3|5|9`.) `[[TracJSGanttChart(scheduled=1,display=owner:chrisn)]]` find all the scheduled tickets and display only those owned by user `chrisn`. === Arguments The chart display can be controlled with the following 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, eg by `milestone` or `owner`, use arbitrary, unique colors. || `priority` || || `dateDisplay`|| ||Format to display dates: `mm/dd/yyyy`, `dd/mm/yyyy`, or `yyyy-mm-dd` || `mm/dd/yyyy` || || `display`||0.10||Filter for limiting display of tickets. `owner:fred` shows only tickets owned by fred. `status:closed` shows only closed tickets.||None|| || `doResourceLeveling`||0.10||Resolve resource conflicts (1) or not (0) when scheduling tickets.||0|| || `dur`|| ||Show (`1`) duration colunn, or do not (`0`). || `1` || || `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 or `parentchild` relation 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` || || `order`||||Order of fields used to sort tickets before display. `order=milestone` sorts by milestone. May include ticket fields, including custom fields, or "wbs" (work breakdown structure).||wbs|| || `scrollTo`||||Date to scroll to when chart is initially drawn. A date in `yyyy-mm-dd` format or "today".||None|| || `linkStyle`||||How to handle clicks on task in the chart. JSGantt style opening a dedicated window (`jsgantt`) or standard ticket link behaviour (`standard`).||`jsgantt`|| 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, eg `milestone=MS1|MS2`, to control which tickets are displayed. == Interfaces The TracPM module provides several interfaces that can be implemented to adapt the Project Management (PM) features to local business rules. The TracPM module will be a separate plugin in the future. These interfaces are defined in `pmapi.py`. === ITaskSorter TracPM defers decisions about ticket ordering to an `ITaskSorter` implementation. * Before any comparison is done, `ITaskSorter.prepareTasks()` is called so that complex keys can be precomputed, external data can be prefetched, etc. to make the comparisons faster and easier.[[br]][[br]]`prepareTasks()` is passed a hash of ticket (tasks). The index of the hash is the ticket ID. The elements of the hash are hashes of Trac ticket attributes. They are not Trac ticket objects.[[br]][[br]]`prepareTasks()` can add to or modify attributes of the ticket. The changes or additions will be available through the life of the scheduling process but will be safely removed before the tickets are returned to the caller. * When making decisions about which ticket to schedule first, TracPM sorts the candidate tickets with `ITaskSorter.compareTasks()`.[[br]][[br]]`compareTasks()` is passed two hashes, the attributes of the two tickets to compare. Any attributes added or changed by `prepareTasks()` are available to `compareTasks()`. {{{#!py class ITaskSorter(Interface): # Process task list to precompute keys or otherwise make # compareTasks() more efficient. def prepareTasks(self, ticketsByID): """Called to prepare tasks for sorting.""" # Provide a compare function for sorting tasks. # Maybe be used as cmp argument for sorted(), and list.sort(). # Returns -1 if t1 < t2, 0 if they are equal, 1 if t1 > t2. def compareTasks(self, t1, t2): """Called to compare two tasks""" }}} ==== Provided Implementations TracPM provides two implementations of `ITaskSorter`: * `SimpleSorter` * `prepareTasks()` prefetches the numeric priority values and gives an average priority to any ticket without one. * `compareTasks()` compares tickets based only on their numeric priority * `ProjectSorter` * `prepareTasks()` prefetches the numeric priority values and computes an "effective priority" for each ticket that takes into account its parent's ticket's priority. A high priority child of a low priority parent has a lower effective priority than a low priority child of a high priority parent. * `compareTasks()` compares tickets based only on their effective priority. `SimpleSorter` is used by default if no sorter is enabled in `trac.ini`. ==== Support Functions `SimpleSorter` and `ProjectSorter` are both derived from `BaseSorter` which provides several functions which may be useful in implementing custom sorters. * `_buildEnumMap(field)` gets numeric values from the Trac database for enums such as priority and severity. The built-in sorters use it to retrieve values for the priority field in their constructor. It returns a hash, containing numeric values and indexed by name (e.g., 'major'). * `averageEnum()` computes the average value in the hash returned by `_buildEnumMap()`. * `compareOneField(field, t1, t2)` compares two tickets based on just one field. === IResourceCalendar TracPM defers decisions about resource availability to an `IResourceCalendar` implementation. * When scheduling a task, TracPM calls `IResourceCalendar.hoursAvailable()` to determine how much of a task can be done on a date. {{{#!py class IResourceCalendar(Interface): # Return the number of hours available for the resource on the # specified date. def hoursAvailable(self, date, resource = None): """Called to see how many hours are available on date""" }}} ==== Provided Implementations TracPM provides one implementation of `IResourceCalendar` * `SimpleCalendar` * `hoursAvailable()` returns 8 for Monday through Friday and 0 for Saturday and Sunday. TeamCalendarPlugin provides an implementation which returns 0 hours for any day that a developer is marked unavailable in the calendar. === ITaskScheduler An interface for task schedulers exists, but is not yet well documented. {{{#!py class ITaskScheduler(Interface): # Schedule each the ticket in tickets with consideration for # dependencies, estimated work, hours per day, etc. # # Assumes tickets is a list returned by TracPM.query(). # # On exit, each ticket has a start and finish that can be accessed # with TracPM.start() and finish(). No other changes are made. def scheduleTasks(self, options, tickets): """Called to schedule tasks""" }}} == Scheduling If the `TicketRescheduler` module is enabled, `TracPM` maintains private tables with task scheduling information. The `schedule` table has the current schedule: {{{ Column | Type | Modifiers --------+---------+----------- ticket | integer | not null start | bigint | finish | bigint | Indexes: "schedule_pkey" PRIMARY KEY, btree (ticket) "schedule_ticket_idx" btree (ticket) }}} The `schedule_change` table holds a record of changes in the schedule over time: {{{ Column | Type | Modifiers -----------+---------+----------- ticket | integer | not null time | bigint | not null oldstart | bigint | oldfinish | bigint | newstart | bigint | newfinish | bigint | Indexes: "schedule_change_pk" PRIMARY KEY, btree (ticket, "time") "schedule_change_ticket_idx" btree (ticket) "schedule_change_time_idx" btree ("time") }}} It is possible, but not yet supported, to use the data in `schedule_change` to reconstruct a baseline schedule for an effective date and then report changes from that baseline. These tables are maintained by a ticket change listener which looks for changes to fields which might affect schedule then: * identifies all tickets that were active (required for an open milestone or an active ticket of the configured milestone ticket type) * identifies all tickets that are now active (as a result of the changes) * removes any tickets that were active but are no longer from `schedule` (updating the history in `schedule_change`) * runs the scheduling algorithm on all tickets that are now active * writes any changes to `schedule` (updating history in `schedule_change`) With this data in place, you can show a Gantt chart of scheduled tickets with dates as in the database (`[[TracJSGanttChart(scheduled=1)]]`) or create reports of the scheduled tickets. {{{#!sql SELECT p.value AS __color__, t.id AS ticket, summary, priority, description AS _description, est.value AS est, act.value AS act, -- This bit is specific to PostgreSQL (SELECT to_date(to_timestamp((sched.finish/1000000))::text, 'YYYY-MM-DD')) AS due, status FROM ticket AS t INNER JOIN schedule AS sched ON (t.id = sched.ticket) INNER JOIN enum AS p ON (p.name = t.priority AND p.type = 'priority') LEFT OUTER JOIN ticket_custom AS est ON (t.id = est.ticket AND est.name = 'estimatedhours') LEFT OUTER JOIN ticket_custom AS act ON (t.id = act.ticket AND act.name = 'totalhours') WHERE t.owner = '$USER' AND status <> 'closed' ORDER BY due NULLS FIRST, p.value }}} == 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 new ticket]. [[TicketQuery(component=TracJsGanttPlugin&group=type,format=progress)]] === Planned enhancements 1. Display a legend of task colors and their meaning, eg 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. == Download Download the zipped source from [export:tracjsganttplugin here]. == Source You can check out !TracJsGanttPlugin from [/svn/tracjsganttplugin here] using Subversion, or [source:tracjsganttplugin browse the source] with Trac. == Installation The following installation steps apply: 1. '''Install''' globally with: - For Trac 1.2 and later: {{{#!sh pip install svn+https://trac-hacks.org/svn/tracjsganttplugin/1.2/ # or easy_install -UZ https://trac-hacks.org/svn/tracjsganttplugin/1.2/ }}} - For Trac 1.0 and earlier: {{{#!sh pip install svn+https://trac-hacks.org/svn/tracjsganttplugin/0.11/ # or easy_install -UZ https://trac-hacks.org/svn/tracjsganttplugin/0.11/ }}} 1. '''Enable''' the plugin by updating your TracIni file (`../conf/trac.ini`) as follows: {{{#!ini [components] tracjsgantt.* = enabled }}} 1. '''Configure''' the project management support for the plugin in its own configuration section, placed into `trac.ini` file as follows: {{{#!ini [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 # Alternatively, configure a pred-succ relation like: # relation.pred-succ = mastertickets,source,dest # This causes TracPM to query the mastertickets table rather than # parse blockedby and blocking custom fields. This can be somewhat # faster. # To work with SubticketsPlugin for parent/child relationships, # Ticket field to use as the data source for the parent fields.parent = parents # Alternatively, configure a parent-child relation like: # relation.parent-child = subtickets,parent,child # This causes TracPM to query the subtickets table rather than parse # the `parents` custom field. This can be somewhat faster. # When using SubticketsPlugin via a parent-child relation, do not # configure a parent_format (next). # 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'). # Used to be milestone_type, that setting is now deprecated. goal_ticket_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 [#Configurationdetails 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]. {{{#!ini [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.omitMilestones = 0 option.caption = Resource option.hoursPerDay = 8.0 }}} 1. '''Restart''' web server on command line: {{{#!sh sudo /etc/init.d/apache2 restart }}} == Configuration !TracJsGanttPlugin is intended to be flexible enough to get data from 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. The `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 `goal_ticket_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. == Recent Changes [[ChangeLog(tracjsganttplugin, 3)]] == Author/Contributors '''Author:''' [wiki:ChrisNelson] [[BR]] '''Maintainer:''' [[Maintainer]] [[BR]] '''Contributors:''' [wiki:rjollos], [wiki:bof], Matt Sable