Wiki Rendering Context

trac.context.Context (current 0.11dev)

(see #FutureDirections and TracDev/ContextRefactoring)

Introduction

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

• Identify the resource to which the wiki text belongs (.env, .realm, .id)
• Access to parent context, if there's one (.parent)
  By following that link, this enables one to unwind the stack of context embedding
• Knows about how the rendered Wiki text is being accessed (.req, .abs_urls) so that the proper links can be generated:
  • .href: the appropriate Href instance for generating any kind of links
  • .resource_href: a link targeting the current Wiki context itself
• Provide access to the corresponding resource itself (.resource)

Besides, it keeps a handle to a database connection (.db) the way the Formatter objects used to do. — will probably change in milestone:0.12

The wiki_to_xyz(ctx, wiki) template functions currently expect a Context for the first argument, and the wiki text as the second argument. Note: this is susceptible to change

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

• Context(env, req): a toplevel context, not attached to a particular resource
• Context(env, req)('wiki', 'WikiStart'): a context for the WikiStart wiki page
• assuming ctxt is already some Context instance, ctxt('ticket', ticket.id) creates a sub-context for 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 referring 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.context.Context class, a few existing interfaces have been modified:

• IWikiMacroProvider.render_macro still takes a req as its first argument (#4139), but it's now deprecated and IWikiMacroProvider.expand_macro should be preferred, as it takes a formatter as its first argument. This is more useful than a req, as the formatter also provides access to the current wiki Context (formatter.context).
• 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. Note: this is still subject to change

Future Directions

Fine-grained Permission Checking

As a context can describe precisely which resource is accessed and at the same time how it is accessed (and more specifically who accesses it), it is also a perfect fit for TracFineGrainedPermissions (see also the design document).

In order to be used as a lightweight descriptor of a resource, Context can also be sub-classed. The user of a context doesn't need to have to think about this, as the correct subclass is always used, based on the .realm information.

Multiple Project Support

Attaching the .project information to a Context, as an additional identifier for a Context would be a convenient way to convey the notion of a "current" project. Therefore, TracLinks found in a wiki text will naturally be based in the same project as the one specified by the current WikiContext.

InterTrac links, on the other hand, would have to be used to refer to a resource found in another project. This is a natural extension for InterTrac prefixes, which are already used to refer to resources located in external environments. It would only take to identify the InterTrac prefixes corresponding to sibling projects for having this mechanism working for targeting other projects in the same environment.

---

See also: r4442 (relative TracLinks changes), TracDev/SecurityBranch (reuse Context as permission resource identifiers)