[[PageOutline(3-6,inline)]]
= Wiki Rendering Context =
 
 '''`trac.wiki.api.Context`''' ''(current [milestone:0.11]dev, r4451)''

 '''`trac.resource.Context`''' ''(see [#FutureDirections])''

== 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 extension, 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
   - `.self_href`: a link targeting the current Wiki context itself [[br]]
     ''renamed to `.resource_href` in the security branch''
 - ''Allow easy access to the corresponding resource itself (`.resource`) - security branch only''

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. ''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.wiki.api.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.


== Future Directions ==

=== Fine-grained Permission Checking ===

The source:sandbox/security branch already contains a much empowered version of the Context class.

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 the fine-grained PermissionPolicy (see also the [PermissionPolicy@16 design document]).

In order to be used as a lightweight descriptor of a resource, Context can also be subclassed. 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), PermissionPolicy (reuse Context as permission resource identifiers)