| 50 | == Interfaces == |
| 51 | |
| 52 | 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`. |
| 53 | |
| 54 | === ITaskSorter === |
| 55 | |
| 56 | TracPM 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 |
| 64 | class 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 | |
| 79 | TracPM 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 | |
| 100 | TracPM 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 |
| 106 | class 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 | |
| 115 | An interface for task schedulers exists but it not yet well documented. |
| 116 | |
| 117 | ==== Provided Implementations ==== |
| 118 | |
| 119 | TracPM provides one implementation of `IResourceCalendar` |
| 120 | |
| 121 | * `SimpleCalendar` |
| 122 | * `hoursAvailable()` returns 8 for Monday through Friday and 0 for Saturday and Sunday. |
| 123 | |
| 124 | An adapter to interface TeamCalendarPlugin` with TracPM is underdevelopment. |
| 125 | |