[[PageOutline(3-6)]]
= Wiki Rendering Context =

 '''`trac.context.Context`''' ''(current [milestone:0.11]dev)''
 
 '''(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`) [[br]]
   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:
{{{
#!sql
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 [TracDev/SecurityBranch 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)