Changes between Version 34 and Version 35 of TracJsGanttPlugin


Ignore:
Timestamp:
Mar 23, 2012, 7:32:35 PM (12 years ago)
Author:
Chris Nelson
Comment:

Add notes about interfaces

Legend:

Unmodified
Added
Removed
Modified
  • TracJsGanttPlugin

    v34 v35  
    4848All other macro arguments are treated as TracQuery specification (e.g., milestone=MS1|MS2) to control which tickets are displayed.
    4949
     50== Interfaces ==
     51
     52The 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`.
     53
     54=== ITaskSorter ===
     55
     56TracPM defers decisions about ticket ordering to an `ITaskSorter` implementation.
     57
     58 * 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.
     59
     60 * 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()`.
     61
     62{{{
     63#!py
     64class ITaskSorter(Interface):
     65    # Process task list to precompute keys or otherwise make
     66    # compareTasks() more efficient.
     67    def prepareTasks(self, ticketsByID):
     68        """Called to prepare tasks for sorting."""
     69
     70    # Provide a compare function for sorting tasks.
     71    # Maybe be used as cmp argument for sorted(), and list.sort().
     72    # Returns -1 if t1 < t2, 0 if they are equal, 1 if t1 > t2.
     73    def compareTasks(self, t1, t2):
     74        """Called to compare two tasks"""
     75}}}
     76
     77==== Provided Implementations ====
     78
     79TracPM provides two implementations of `ITaskSorter`:
     80
     81 * `SimpleSorter`
     82  * `prepareTasks()` prefetches the numeric priority values and gives an average priority to any ticket without one.
     83  * `compareTasks()` compares tickets based only on their numeric priority
     84 * `ProjectSorter`
     85  * `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.
     86  * `compareTasks()` compares tickets based only on their effective priority.
     87
     88`SimpleSorter` is used by default if no sorter is enabled in `trac.ini`.
     89
     90==== Support Functions ====
     91
     92`SimpleSorter` and `ProjectSorter` are both derived from `BaseSorter` which provides several functions which may be useful in implementing custom sorters.
     93
     94 * `_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').
     95 * `averageEnum()` computes the average value in the hash returned by `_buildEnumMap()`.
     96 * `compareOneField(field, t1, t2)` compares two tickets based on just one field.
     97
     98=== IResourceCalendar ===
     99
     100TracPM defers decisions about resource availability to an `IResourceCalendar` implementation.
     101
     102 * When scheduling a task, TracPM calls `IResourceCalendar.hoursAvailable()` to determine how much of a task can be done on a date.
     103
     104{{{
     105#!py
     106class IResourceCalendar(Interface):
     107    # Return the number of hours available for the resource on the
     108    # specified date.
     109    def hoursAvailable(self, date, resource = None):
     110        """Called to see how many hours are available on date"""
     111}}}
     112
     113=== ITaskScheduler ===
     114
     115An interface for task schedulers exists but it not yet well documented.
     116
     117==== Provided Implementations ====
     118
     119TracPM provides one implementation of `IResourceCalendar`
     120
     121 * `SimpleCalendar`
     122  * `hoursAvailable()` returns 8 for Monday through Friday and 0 for Saturday and Sunday.
     123
     124An adapter to interface TeamCalendarPlugin` with TracPM is underdevelopment.
     125
    50126
    51127== Installation ==