Changes between Version 53 and Version 54 of TracJsGanttPlugin
- Timestamp:
- Nov 25, 2015, 8:38:12 AM (8 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
TracJsGanttPlugin
v53 v54 5 5 == Description 6 6 7 A plugin which allows Trac ticket data to be displayed in a [http://jsgantt.com jsGantt] chart in a wiki page. 7 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. 8 8 9 9 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). 10 10 11 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. 11 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. 12 12 13 13 == Examples … … 17 17 [[Image(jsGanttSample.PNG)]] 18 18 19 `[[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`.)19 `[[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`. 20 20 21 21 `[[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`.) … … 27 27 The chart display can be controlled with the following macro arguments: 28 28 29 ||'''Argument''' ||'''Version'''||'''Description''' ||'''Default'''29 ||'''Argument''' ||'''Version''' ||'''Description''' ||'''Default''' 30 30 || `caption`|| ||Caption to place to right of tasks: None, `Caption`, `Resource`, `Duration`, `Complete` || `Resource` || 31 || `comp`|| ||Show (`1`) percent complete column, or do not (`0`). || `1`||32 || `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 33 || `dateDisplay`|| ||Format to display dates: `mm/dd/yyyy`, `dd/mm/yyyy`, or `yyyy-mm-dd` || `mm/dd/yyyy`||34 || `display`||0.10||Filter for limiting display of tickets. 31 || `comp`|| ||Show (`1`) percent complete column, or do not (`0`). || `1` || 32 || `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` || 33 || `dateDisplay`|| ||Format to display dates: `mm/dd/yyyy`, `dd/mm/yyyy`, or `yyyy-mm-dd` || `mm/dd/yyyy` || 34 || `display`||0.10||Filter for limiting display of tickets. `owner:fred` shows only tickets owned by fred. `status:closed` shows only closed tickets.||None|| 35 35 || `doResourceLeveling`||0.10||Resolve resource conflicts (1) or not (0) when scheduling tickets.||0|| 36 || `dur`|| ||Show (`1`) duration colunn, or do not (`0`). || `1`||37 || `endDate`|| ||Show (`1`) end date column, or do not (`0`). || `1`||38 || `expandClosedTickets`||0.9||Show (`1`) children of closed tickets in the task hierarchy or collapse the subtree (`0`). || `1`||39 || `format`|| ||Initial display format, one of those listed in `formats` || `day`||40 || `formats`||||Formats to show for Gantt chart. 41 || `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=<ticket#>`. 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.|| 42 || `hoursPerDay`|| ||Hours worked per day || `8.0`||43 || `lwidth`|| ||Width (in pixels) of left table. The one contains task names, etc. on the left of the Gantt chart. || None||44 || `omitMilestones`||0.8||Show milestones for displayed tickets (`0`) or only those specified by `milestone=` (`1`). || `0`||45 || `openLevel`|| ||How many levels of task hierarchy to show open. `1` = only top level task. || `999`||46 || `res`|| ||Show (`1`) resource column, or do not (`0`). || `1`||47 || `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=<ticket#>`. 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||48 || `sample`|| ||Display (`1`) sample tasks in Gantt, or do not (`0`) || `0`||49 || `schedule`|| ||Schedule algorithm: as-last-as-possible (`alap`) or as-soon-as-possible (`asap`) || `alap`||50 || `showdep`|| ||Show (`1`) dependencies in Gantt, or do not (`0`). || `1`||51 || `startDate`|| ||Show (`1`) start date column, or do not (`0`). || `1`||52 || `userMap`||0.8||Map (`1`) user IDs to full names, or do not (`0`). || `1`||36 || `dur`|| ||Show (`1`) duration colunn, or do not (`0`). || `1` || 37 || `endDate`|| ||Show (`1`) end date column, or do not (`0`). || `1` || 38 || `expandClosedTickets`||0.9||Show (`1`) children of closed tickets in the task hierarchy or collapse the subtree (`0`). || `1` || 39 || `format`|| ||Initial display format, one of those listed in `formats` || `day` || 40 || `formats`||||Formats to show for Gantt chart. A pipe-separated list of `minute`, `hour`, `day`, `week`, `month`, and `quarter`. || `day|week|month|quarter` || 41 || `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=<ticket#>`. 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 || 42 || `hoursPerDay`|| ||Hours worked per day || `8.0` || 43 || `lwidth`|| ||Width (in pixels) of left table. The one contains task names, etc. on the left of the Gantt chart. || None || 44 || `omitMilestones`||0.8||Show milestones for displayed tickets (`0`) or only those specified by `milestone=` (`1`). || `0` || 45 || `openLevel`|| ||How many levels of task hierarchy to show open. `1` = only top level task. || `999` || 46 || `res`|| ||Show (`1`) resource column, or do not (`0`). || `1` || 47 || `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=<ticket#>`. 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 || 48 || `sample`|| ||Display (`1`) sample tasks in Gantt, or do not (`0`) || `0` || 49 || `schedule`|| ||Schedule algorithm: as-last-as-possible (`alap`) or as-soon-as-possible (`asap`) || `alap` || 50 || `showdep`|| ||Show (`1`) dependencies in Gantt, or do not (`0`). || `1` || 51 || `startDate`|| ||Show (`1`) start date column, or do not (`0`). || `1` || 52 || `userMap`||0.8||Map (`1`) user IDs to full names, or do not (`0`). || `1` || 53 53 || `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|| 54 54 || `scrollTo`||||Date to scroll to when chart is initially drawn. A date in `yyyy-mm-dd` format or "today".||None|| … … 61 61 == Interfaces 62 62 63 The TracPM module provides several interfaces that can be implemented to adapt the Project Management (PM) features to local business rules. 63 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`. 64 64 65 65 === ITaskSorter … … 67 67 TracPM defers decisions about ticket ordering to an `ITaskSorter` implementation. 68 68 69 * 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.70 71 * 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. 69 * 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. 70 71 * 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()`. 72 72 73 73 {{{#!py … … 93 93 * `compareTasks()` compares tickets based only on their numeric priority 94 94 * `ProjectSorter` 95 * `prepareTasks()` prefetches the numeric priority values and computes an "effective priority" for each ticket that takes into account its parent's ticket's priority. 95 * `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. 96 96 * `compareTasks()` compares tickets based only on their effective priority. 97 97 … … 102 102 `SimpleSorter` and `ProjectSorter` are both derived from `BaseSorter` which provides several functions which may be useful in implementing custom sorters. 103 103 104 * `_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').104 * `_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'). 105 105 * `averageEnum()` computes the average value in the hash returned by `_buildEnumMap()`. 106 106 * `compareOneField(field, t1, t2)` compares two tickets based on just one field. … … 141 141 # 142 142 # On exit, each ticket has a start and finish that can be accessed 143 # with TracPM.start() and finish(). 143 # with TracPM.start() and finish(). No other changes are made. 144 144 def scheduleTasks(self, options, tickets): 145 145 """Called to schedule tasks""" … … 196 196 summary, 197 197 priority, 198 description as_description,198 description AS _description, 199 199 est.value AS est, 200 200 act.value AS act, … … 233 233 1. Display slack time. 234 234 235 == Source & Download 236 237 You can check out !TracJsGanttPlugin from [http://trac-hacks.org/svn/tracjsganttplugin here] using Subversion, or [source:tracjsganttplugin browse the source] with Trac. 238 239 Download the zipped source from [download:tracjsganttplugin here]. 235 == Download 236 237 Download the zipped source from [export:tracjsganttplugin here]. 238 239 == Source 240 241 You can check out !TracJsGanttPlugin from [/svn/tracjsganttplugin here] using Subversion, or [source:tracjsganttplugin browse the source] with Trac. 240 242 241 243 == Installation … … 246 248 sudo easy_install https://trac-hacks.org/svn/tracjsganttplugin/0.11/ 247 249 }}} 248 1. '''Enable''' the plugin by updating TracIni file (..../trac.ini) as follows:250 1. '''Enable''' the plugin by updating your TracIni file (`../conf/trac.ini`) as follows: 249 251 {{{#!ini 250 252 [components] 251 253 tracjsgantt.* = enabled 252 254 }}} 253 1. '''Configure''' the project management support for the plugin in its own configuration section, placed into 'trac.ini'file as follows:255 1. '''Configure''' the project management support for the plugin in its own configuration section, placed into `trac.ini` file as follows: 254 256 {{{#!ini 255 257 [TracPM] … … 267 269 # relation.pred-succ = mastertickets,source,dest 268 270 # This causes TracPM to query the mastertickets table rather than 269 # parse blockedby and blocking custom fields. 271 # parse blockedby and blocking custom fields. This can be somewhat 270 272 # faster. 271 273 … … 277 279 # relation.parent-child = subtickets,parent,child 278 280 # This causes TracPM to query the subtickets table rather than parse 279 # the `parents` custom field. 281 # the `parents` custom field. This can be somewhat faster. 280 282 # When using SubticketsPlugin via a parent-child relation, do not 281 283 # configure a parent_format (next). … … 286 288 287 289 # Custom fields for start and due dates 288 # Ticket field to use as the data source for start date (default: None) 290 # Ticket field to use as the data source for start date (default: None). 289 291 fields.start = userstart 290 # Ticket field to use as the data source for finish date (default: None) 292 # Ticket field to use as the data source for finish date (default: None). 291 293 fields.finish = userfinish 292 294 … … 294 296 date_format = %Y-%m-%d 295 297 296 # Ticket type for milestone-like tickets (default: 'milestone') 298 # Ticket type for milestone-like tickets (default: 'milestone'). 297 299 # Used to be milestone_type, that setting is now deprecated. 298 300 goal_ticket_type = milestone … … 304 306 hours_per_estimate = 1 305 307 306 # Default work for an unestimated task, same units as estimate 308 # Default work for an unestimated task, same units as estimate (default: 4.0). 307 309 default_estimate = 4.0 308 310 309 # How much work may be remaining when a task goes over estimate, same units as estimate (default: 0.0). .311 # How much work may be remaining when a task goes over estimate, same units as estimate (default: 0.0). 310 312 estimate_pad = 0.0 311 313 }}} … … 342 344 == Configuration 343 345 344 !TracJsGanttPlugin is intended to be flexible enough to get data from plugins by configuring the field names for those plugins in `trac.ini`. 346 !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. 345 347 346 348 All of the `fields.*` items name custom fields which may contain data for the Gantt.