Note: this is a transient page for documenting the upcoming change introducing wiki rendering contexts

---

Introduction of Wiki rendering contexts (trac.wiki.api.Context)

The changeset is a bit big, but that was the price to pay for doing a consistent and (hopefully) bug free transition.

Introduction

A Wiki rendering context contains all the information needed for properly rendering Wiki text in the Trac system:

• the resource to which the wiki text belongs (.env, .resource, .id)
• its parent context, if there's one (.parent)
• how the rendered Wiki text is being accessed (.req, .abs_urls) so that the proper links can be generated (.href, .self_href)

Besides, it keeps a handle to a database connection (.db) the way the Formatter objects used to do.

Such a context can be used for generating wiki texts in different flavors, using the .wiki_to_... methods.

It's very easy to manipulate contexts, or create sub-contexts. Here are some examples:

• Context(env, req): a global context, not attached to a particular resource
• Context(env, req, 'wiki', 'WikiStart'): a context for the WikiStart wiki page
• assuming ctxt is a Context instance, ctxt('ticket', ticket.id) creates a subcontext focusing on a specific ticket.

Fixed Issues

Thanks to Wiki rendering contexts, the following issues could be solved:

• relative attachments and comments TracLinks now always refer to the correct context resource, irrelevant from where they are displayed (ticket query with description #3711, headings #3842, timeline, etc.)
• relative links (i.e. [#anchor see this] kind of TracLinks) are now always refering to the correct resource (#4144)

Besides, a few other fixes were done at the same time:

• the formatter stores the wiki text it is currently parsing (.source), so that it can be made available to macros; for example, this means that the rendering of PageOutline macro is now consistent, and the outline is always the one of the text being currently formatted (#3936)
• remove support for old wiki-macros (they were not going to work anymore since the HDF is gone)
• fix the TracGuideToc macro, which is now part of the default set of trac.wiki.macros (#3958)

Finally, rows in TracReports can now refer to other resources than just tickets, when specifying a resource column. That way, reports for changesets can now be linked to the corresponding changesets.

Example, for showing the last 10 changesets:

select 'changeset' as _resource, rev as id, time, author, 
       message as description
from revision order by time desc limit 10;

API Changes

Besides the new trac.wiki.api.Context class, a few existing interfaces have been modified:

• IWikiMacroProvider.render_macro now takes a formatter instead of a req as its first argument (#4139)
• IHTMLPreviewRenderer.render takes a context instead of a req as its first argument
• TimelineEvent.set_context takes a context first argument and a wikitext second argument. That wiki text can now be retrieved in the .wikitext property instead of the .message one.