Changes between Version 53 and Version 54 of TracJsGanttPlugin


Ignore:
Timestamp:
Nov 25, 2015, 8:38:12 AM (8 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified
  • TracJsGanttPlugin

    v53 v54  
    55== Description
    66
    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.
     7A 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.
    88
    99Configurable field names allow integration with other plugins such as MasterTicketsPlugin (for dependencies), SubticketsPlugin (for parent/child relationships) and TimingAndEstimationPlugin (for estimated and total hours).
    1010
    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.
     11Over 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.
    1212
    1313== Examples
     
    1717[[Image(jsGanttSample.PNG)]]
    1818
    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`.
    2020
    2121`[[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`.)
     
    2727The chart display can be controlled with the following macro arguments:
    2828
    29 ||'''Argument'''  ||'''Version''' ||'''Description'''  ||'''Default'''
     29||'''Argument''' ||'''Version''' ||'''Description'''    ||'''Default'''
    3030|| `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  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||
     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||
    3535|| `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.  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` ||
     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` ||
    5353|| `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||
    5454|| `scrollTo`||||Date to scroll to when chart is initially drawn. A date in `yyyy-mm-dd` format or "today".||None||
     
    6161== Interfaces
    6262
    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`.
     63The 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`.
    6464
    6565=== ITaskSorter
     
    6767TracPM defers decisions about ticket ordering to an `ITaskSorter` implementation.
    6868
    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()`.
     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()`.
    7272
    7373{{{#!py
     
    9393  * `compareTasks()` compares tickets based only on their numeric priority
    9494 * `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.  A high priority child of a low priority parent has a lower effective priority than a low priority child of a high priority parent.
     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.
    9696  * `compareTasks()` compares tickets based only on their effective priority.
    9797
     
    102102`SimpleSorter` and `ProjectSorter` are both derived from `BaseSorter` which provides several functions which may be useful in implementing custom sorters.
    103103
    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').
    105105 * `averageEnum()` computes the average value in the hash returned by `_buildEnumMap()`.
    106106 * `compareOneField(field, t1, t2)` compares two tickets based on just one field.
     
    141141    #
    142142    # On exit, each ticket has a start and finish that can be accessed
    143     # with TracPM.start() and finish().  No other changes are made.
     143    # with TracPM.start() and finish(). No other changes are made.
    144144    def scheduleTasks(self, options, tickets):
    145145        """Called to schedule tasks"""
     
    196196   summary,
    197197   priority,
    198    description as _description,
     198   description AS _description,
    199199   est.value AS est,
    200200   act.value AS act,
     
    233233 1. Display slack time.
    234234
    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
     237Download the zipped source from [export:tracjsganttplugin here].
     238
     239== Source
     240
     241You can check out !TracJsGanttPlugin from [/svn/tracjsganttplugin here] using Subversion, or [source:tracjsganttplugin browse the source] with Trac.
    240242
    241243== Installation
     
    246248sudo easy_install https://trac-hacks.org/svn/tracjsganttplugin/0.11/
    247249}}}
    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:
    249251 {{{#!ini
    250252[components]
    251253tracjsgantt.* = enabled
    252254}}}
    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:
    254256 {{{#!ini
    255257[TracPM]
     
    267269#    relation.pred-succ = mastertickets,source,dest
    268270# This causes TracPM to query the mastertickets table rather than
    269 # parse blockedby and blocking custom fields.  This can be somewhat
     271# parse blockedby and blocking custom fields. This can be somewhat
    270272# faster.
    271273
     
    277279#    relation.parent-child = subtickets,parent,child
    278280# This causes TracPM to query the subtickets table rather than parse
    279 # the `parents` custom field.  This can be somewhat faster.
     281# the `parents` custom field. This can be somewhat faster.
    280282# When using SubticketsPlugin via a parent-child relation, do not
    281283# configure a parent_format (next).
     
    286288 
    287289# 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).
    289291fields.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).
    291293fields.finish = userfinish
    292294
     
    294296date_format = %Y-%m-%d
    295297
    296 # Ticket type for milestone-like tickets (default: 'milestone')
     298# Ticket type for milestone-like tickets (default: 'milestone').
    297299# Used to be milestone_type, that setting is now deprecated.
    298300goal_ticket_type = milestone
     
    304306hours_per_estimate = 1
    305307   
    306 # Default work for an unestimated task, same units as estimate  (default: 4.0).
     308# Default work for an unestimated task, same units as estimate (default: 4.0).
    307309default_estimate = 4.0
    308310   
    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).
    310312estimate_pad = 0.0
    311313}}}
     
    342344== Configuration
    343345
    344 !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.
     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.
    345347
    346348All of the `fields.*` items name custom fields which may contain data for the Gantt.