Context Navigation

Changes between Version 50 and Version 51 of TracJsGanttPlugin

Timestamp:: Mar 9, 2015, 1:08:52 PM (9 years ago)
Author:: figaro
Comment:: Cosmetic changes

Legend:

: Unmodified
: Added
: Removed
: Modified

TracJsGanttPlugin

-                      v50
+                      v51
 [[PageOutline(2-5,Contents,pullout)]]
 = Trac jsGantt plugin =
 == Description ==
+= Display a jsGantt chart in a wiki page
+== 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.
 …
 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.
 == Usage ==
 `[[TracJSGanttChart(sample=1)]]` displays the sample project from jsgantt.com.  `[[TracJSGanttChart(milestone=Test)]]` displays all the tickets in the Test milestone.
+== 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)]]
 …
 `[[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 a number of macro arguments:
+=== 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 (e.g., by `milestone` or `owner`) use arbitrary, unique colors. || `priority` ||
+|| `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||
 …
 || `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.[[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 ||
+|| `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 ||
 || `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  ||
+|| `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 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  ||
+|| `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  ||
 || `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`  ||
 …
 || `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||
+|| `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.<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 ===
+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, 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.
 …
 }}}
 ==== Provided Implementations ====
+==== Provided Implementations
 TracPM provides two implementations of `ITaskSorter`:
 …
 `SimpleSorter` is used by default if no sorter is enabled in `trac.ini`.
 ==== Support Functions ====
+==== Support Functions
 `SimpleSorter` and `ProjectSorter` are both derived from `BaseSorter` which provides several functions which may be useful in implementing custom sorters.
 …
  * `compareOneField(field, t1, t2)` compares two tickets based on just one field.
 === IResourceCalendar ===
+=== IResourceCalendar
 TracPM defers decisions about resource availability to an `IResourceCalendar` implementation.
 …
 }}}
 ==== Provided Implementations ====
+==== Provided Implementations
 TracPM provides one implementation of `IResourceCalendar`
 …
 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 it not yet well documented.
+=== ITaskScheduler
+An interface for task schedulers exists, but is not yet well documented.
 {{{
 …
 }}}
 == Scheduling ==
+== Scheduling
 If the `TicketRescheduler` module is enabled, `TracPM` maintains private tables with task scheduling information. The `schedule` table has the current schedule:
 …
 }}}
 The `schedule_change` table holds a record of changes in the schedule over time.
+The `schedule_change` table holds a record of changes in the schedule over 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.
+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:
 …
  * writes any changes to `schedule` (updating history in `schedule_change`)
 With this data in place, you can show a Gantt of scheduled tickets with dates as in the database (`[[TracJSGanttChart(scheduled=1)]]`) or create reports of the scheduled tickets.
+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.
 {{{
 …
    est.value as est,
    act.value as act,
+   -- This bit is specific to Postgres.
+   (SELECT to_date(to_timestamp((sched.finish/1000000))::text,
+                                'YYYY-MM-DD')) AS due,
+   -- 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
 …
 }}}
 == Installation ==
+== Installation
+The following installation steps apply:
 . '''Install''' globally with:
 {{{#!sh
 …
 . '''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.
+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.  (`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.
 == Bugs/Feature Requests ==
+ * 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.
+== 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 ===
+[[TicketQuery(component=TracJsGanttPlugin&group=type,format=progress)]]
+=== Known issues
+The following is a list of known issues:
 [[TicketQuery(status=accepted&status=assigned&status=new&status=reopened&type=defect&component=TracJsGanttPlugin&col=id&col=summary&col=component&col=status&col=owner&col=type&col=priority&order=priority)]]
 === Planned enhancements ===
 . Display a legend of task colors and their meaning (e.g., which milestone or owner they represent).
+=== Planned enhancements
+. Display a legend of task colors and their meaning, eg which milestone or owner they represent.
 . Allow some tasks to be open or closed by default.
 . Display critical path
 . Display slack time
 == Source & Download ==
+. Display critical path.
+. 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 ==
+=== Recent Changes
+[[ChangeLog(tracjsganttplugin, 3)]]
+== Author/Contributors
 '''Author:''' [wiki:ChrisNelson] [[BR]]
 '''Maintainer:''' [wiki:ChrisNelson] [[BR]]
+'''Maintainer:''' [[Maintainer]] [[BR]]
 '''Contributors:''' [wiki:rjollos], [wiki:bof], Matt Sable