Changes between Version 3 and Version 4 of WikiContext

Timestamp:

Feb 7, 2007, 11:13:09 AM (17 years ago)

Author:

Christian Boos

Comment:

Possible future directions for the wiki context usage

WikiContext

@@ -2 +2 @@
 = Wiki Rendering Context =
  
- '''`trac.wiki.api.Context`''' ''(Since [milestone:0.11], r4451)''
+ '''`trac.wiki.api.Context`''' ''(current [milestone:0.11]dev, r4451)''
 
+ '''`trac.resource.Context`''' ''(see [#FutureDirections])''
 
-=== Introduction ===
+== 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`)
+ - 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.
+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 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`.
+ - `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 ===
+== 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)
+ - 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:
@@ -44 +52 @@
 
 
-=== API Changes ===
+== 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)
+ - `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)