| 59 | | Then, the return type for the `get_timeline_events` event has changed. It can now be a `TimelineEvent` object instead of a tuple, though the tuple return value will still be supported for compatibility reasons in 0.11. |
| 60 | | |
| 61 | | (Please note that this API hasn't been 100% agreed on yet, so you probably want to stick to just returning tuples for now.) |
| | 59 | Then, the return type for the `get_timeline_events` event has changed. |
| | 60 | Instead of a 6-tuple `(kind, href, title, date, author, markup)` (which still supported for compatibility reasons in 0.11), |
| | 61 | the returned value can now be a 4 or 5-tuple `(kind, date, author, data[, provider])`, which is far more flexible than |
| | 62 | before, especially because the `data` can be anything that will be used by a new `render_timeline_event(context, field, event)` |
| | 63 | method called when actually displaying the events. |
| 83 | | The `req` was not enough for most of the macros, which needed to resort to various hacks to get more information about the formatting at work. The more adequate `formatter` object is now provided instead. The `req` object can still be obtained from the formatter, with `formatter.req`. Better yet, the formatter now always know about the WikiContext in which it operates (use `formatter.context` to retrieve it). |
| 84 | | The context object provides the information about the Trac resource which "owns" the text being processed. |
| | 85 | The `req` was not enough for most of the macros, which needed to resort to various hacks to get more information about the formatting at work. |
| | 86 | The more pertinent `formatter` object is now provided instead. The `req` object can still be obtained from the formatter, with `formatter.req`, |
| | 87 | but this is going to be deprecated. Instead, you should access to the following set of information: |
| | 88 | - `formatter.resource` is the resource identifier which owns the text being formatted (this is a `trac.resource.Resource`, see below), |
| | 89 | - `formatter.context` is the rendering context in which this wiki formatting takes place (this is a `trac.mimeview.api.Context`, see below) |
| | 90 | - `formatter.perm` the permission cache which can be used in order to perform fine-grained permission checks (this is a `trac.perm.PermissionCache`). |
| 90 | | Similar to the above change, `render(req, mimetype ...)` is now `render(context, mimetype ...)`. It doesn't matter that much however, as it looks like that this interface is going to be integrated in `IContentConverter` anyway (see #3332). |
| | 96 | Similar to the above change, `render(req, mimetype ...)` is now `render(context, mimetype ...)`, `context` being a rendering `Context` (see below). |
| | 97 | It doesn't matter that much however, as it looks like that this interface is going to be integrated in `IContentConverter` anyway (see #3332 - 0.12 topic unfortunately). |
| 94 | | Several new interfaces have been added in 0.11. |
| | 101 | Several new interfaces and modules have been added in 0.11. |
| | 102 | |
| | 103 | TODO: document the various new trac.util modules. |
| | 104 | |
| | 105 | === `trac.resource.Resource` === |
| | 106 | |
| | 107 | The '''resource identifier''' class `Resource` is used to specify in a convenient way which Trac ''resources'' is being manipulated. |
| | 108 | A Trac resource is mostly anything in Trac that can be addressed with its own URL and to which some content is attached. |
| | 109 | A resource is mainly identified by a `realm` string and an `id` string or a number. |
| | 110 | Also, a `version` can be specified in a Resource object, in order to refer to the content of a resource at a particular moment of its history. |
| | 111 | A version specification of `None` simply refers to the latest version of the resource. |
| | 112 | Finally, a resource can be parented in another resource. This relationship usually means that a removal of the parent resource implies a removal of the children resources. |
| | 113 | |
| | 114 | === `trac.resource.IResourceManager` === |
| | 115 | |
| | 116 | The `IResourceManager` let components claim ownership of some realms. |
| | 117 | For the managed realms, the manager component will know how to build URLs to access the resources belonging to that realm and will know how to describe those resources. |
| | 118 | Various utility functions exist in the `trac.resource` module in order to manipulate the `Resource` identifier objects in a generic way. |
| | 119 | |
| | 120 | === `trac.mimeview.api.Context` === |
| | 121 | |
| | 122 | The '''rendering context''' class is used to specify ''how'' the content should be rendered. |
| | 123 | It holds together all the needed contextual information that will be needed by individual renderer components. |
| | 124 | It is notably hodling together a `Resource` identifier for specifying the owning resource of the content being rendered, |
| | 125 | a `PermissionCache` for restricting the display of information to the authorized parts only and an `Href` object that |
| | 126 | can be used for creating links. |
| | 127 | Also, `Context` can be parented and this relationship usually correspond to some kind of embedding of the data |
| | 128 | (typical example, ticket information displayed within a Wiki page by the way of a macro). |
| | 129 | |
| | 130 | === `trac.perm.IPermissionPolicy` === |
| | 131 | |
| | 132 | TBD. |
| | 133 | |
| | 134 | === `trac.ticket.api.ITicketActionController` === |
| | 135 | |
| | 136 | TBD. See TracWorkflow. |
| | 137 | |
| | 138 | === `trac.ticket.roadmap.ITicketGroupStatsProvider` === |
| | 139 | |
| | 140 | TBD. |
| | 141 | |
| | 142 | === `trac.web.ITemplateStreamFilter` === |
| | 143 | |
| | 144 | TBD. |
| | 145 | |
| | 146 | === `trac.prefs.api.IPreferencePanelProvider` === |
| | 147 | |
| | 148 | TBD. |
| 107 | | [This section could probably be done better, but I figure getting the info in here is better than having it left out] |
| 108 | | |
| 109 | | * {{{webadmin.web_ui.IAdminPageProvider}}} -> {{{trac.admin.api.IAdminPanelProvider}}}. Also its {{{get_admin_pages}}} method became {{{get_admin_panels}}}. |
| 110 | | * some module names, such as {{{trac.Timeline}}} and {{{trac.Search}}}, were de-capitalized, e.g. {{{trac.timeline}}} |
| | 161 | * The previously external interface `webadmin.web_ui.IAdminPageProvider` is now a core interface: `trac.admin.api.IAdminPanelProvider`. |
| | 162 | Also its `get_admin_pages` method became `get_admin_panels`. |
| | 163 | [[comment(some module names, such as {{{trac.Timeline}}} and {{{trac.Search}}}, were de-capitalized, e.g. {{{trac.timeline}}} => see above, there's a full section for each)]] |
