Version 36 (modified by 12 years ago) (diff) | ,
---|
Contents
Trac jsGantt plugin
Description
A plugin which allows Trac ticket data to be displayed in a 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.
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
| |
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=<ticket#> . The macro uses the configured succ field to find all predecessor tasks and build an id= argument for Trac's native query handler.Multiple goals may be provided like goal=1|12|32 .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=<ticket#> . The macro uses the configured parent field to find all descendant tasks and build an id= argument for Trac's native query handler.Multiple roots may be provided like root=1|12|32 .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.<opt>
overrides the built-in default for <opt>
from the table above.
All other macro arguments are treated as TracQuery specification (e.g., 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.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.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()
.compareTasks()
is passed two hashes, the attributes of the two tickets to compare. Any attributes added or changed byprepareTasks()
are available tocompareTasks()
.
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.
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.
An adapter to interface TeamCalendarPlugin` with TracPM is underdevelopment.
ITaskScheduler
An interface for task schedulers exists but it not yet well documented.
Installation
- Install globally with:
sudo easy_install https://trac-hacks.org/svn/tracjsganttplugin/0.11/
- Enable the plugin by updating TracIni file (..../trac.ini) as follows:
[components] tracjsgantt.* = enabled
- 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 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 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
- Restart web server on command line:
$ 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
andfields.worked
are both configured, the plugin attempts to display (100 *fields.worked
/fields.estimate
) as the percent complete. The example works with TimingAndEstimationPlugin. Alternatively, ifpercent
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
andfields.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 theparent
field. Use "%s" (default) for SubticketsPlugin, or "#%s" for ChildTicketsPlugin.)
- When
fields.start
andfields.finish
are configured, the plugin uses them to set task start and finish dates. Thedate_format
field is a Pythonstrptime()
format specifier which describes the contents offields.start
andfields.finish
. If these fields are not configured, all tasks end today and have a 1-day duration.
- When
fields.estimate
andfields.finish
are both configured (andfields.start
is not configured or not on the ticket), the plugin attempts to determine the start of the task fromfields.finish
andfields.estimate
asstart = 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 here.
If you have any issues, create a new ticket.
Known issues
- None
Planned enhancements
- Display a legend of task colors and their meaning (e.g., which milestone or owner they represent).
- Allow some tasks to be open or closed by default.
- Display critical path
- Display slack time
Source & Download
You can check out TracJsGanttPlugin from here using Subversion, or browse the source with Trac.
Download the zipped source from [download:tracjsganttplugin here].
Recent Changes
- 17888 by rjollos on 2020-12-03 05:44:28
-
Trac-jsGantt 1.2.0.0dev: Fix typo in section name
- 17707 by rjollos on 2020-04-29 19:05:19
-
Trac-jsGantt 1.2.0.0dev: Handle milestone with no tickets
Refs #13627.
- 17638 by jun66j5 on 2019-12-19 18:34:55
-
Trac-jsGantt 1.2.0.0dev: make compatible with Trac 1.4 (closes #13713)
- 17250 by rjollos on 2018-07-30 21:52:52
-
Trac-jsGantt 1.2.0.0dev: Fix exception when ticket field is None
Patch by Rochi.
Fixes #13463.
- 17150 by rjollos on 2018-04-24 19:26:48
-
Trac-jsGantt 1.2.0.0dev: Make compatible with Trac 1.2+
Fixes #13175.
- 17149 by rjollos on 2018-04-24 18:25:26
-
Trac-jsGantt 1.2.0.0dev: Branch for Trac 1.2 and conform to PEP8
Refs #13175.
- 14208 by ChrisNelson on 2014-10-14 17:39:23
-
Fix a typo. Refs #9648.
- 14207 by ChrisNelson on 2014-10-14 17:18:33
-
Use Trac 1.0 DB API to find active tickets. Refs #9648.
- 14206 by ChrisNelson on 2014-10-14 17:18:28
-
Use Trac 1.0 DB API to find tickets by owner. Refs #9648.
- 14205 by ChrisNelson on 2014-10-14 17:18:23
-
Use Trac 1.0 DB API to find owners. Refs #9648.
Conflicts:
tracjsgantt/tracpm.py
(more)
Author/Contributors
Author: ChrisNelson
Maintainer: ChrisNelson
Contributors: rjollos, bof, Matt Sable
Attachments (1)
-
jsGanttSample.PNG (45.6 KB) - added by 13 years ago.
jsGantt sample tasks in a wiki page
Download all attachments as: .zip