Changes between Version 3 and Version 4 of TracDev/ContextRefactoring

Timestamp:

Sep 27, 2007, 10:13:42 AM (17 years ago)

Author:

Christian Boos

Comment:

Document the RenderingContext part

TracDev/ContextRefactoring

@@ -149 +149 @@
  * in '''Towards Resource Descriptors''', only the identification aspect of resource is addressed. So the list of (realm,id,version) tuple is at most a Resource Identifier, and can't really be called a Resource Descriptor, as it can't describe usefully a resource. I don't think there would be any noticeable performance impact for using objects for that, as opposed to having to revert to the actual data model for representation needs (as suggested in the example `TicketSystem.resolve_resource`). Still, if this is a concern, I agree we could delegate the dynamic description  of identifiers to Components.[[br]]Also, the manipulation of those list-based resource identifiers would be quite cumbersome (see the same resolve_resource example) and even more if one checks for the presence or absence of version information. It would be much easier/cleaner to use r.realm, r.id and r.version in the code.[[br]]Finally, another important reason why it's preferable to use an object rather than a list of tuple is that the notion of "identity" will evolve. Currently we have realm+id (+ eventually revision), but in the future we'll probably add the project information as well. It will be far easier to deal with the project information by adding r.project calls where relevant rather than changing all the code accessing the tuples.
  * '''Context Factories and Subclasses:'''[[br]]We need some kind of dynamic description of resources, for all the parts that are generic about resources in Trac: the attachments, the history and diffs of resource content (#2945), the generic reports, etc.[[br]]Those things have been built some time after the `WikiContext` integration, so it's true that they are separate enhancements. But I think that they are very worthwhile ones that have to be kept and probably expanded upon (generic comments, content change annotation, etc.)[[br]]If there's really a need to decouple the way resources can be identified from the way resources can be described, then we could eventually have simple Resource objects and "rendering" methods from a manager component like the one suggested. That would actually make some parts of the implementation simpler, as we could create very simple Resource objects which could delegate their dynamic aspects to their managing component.
- * '''Wiki Rendering Context:'''[[br]]We can't simply move all the responsibilities of the rendering context to the Formatter class, as Formatter objects are only present when explicitly rendering Wiki text, not generally available when rendering "content", in the mimeview module (the "content" which is rendered is coming from resources and that content may be wiki content). So we need something (a `RenderingContext` class?) that would be made available to the content renderers, and from there to the formatter, and from the formatter conveyed to the wiki processors. ''I'm still not yet fully satisfied with this aspect in my prototype implementation -Christian Boos 9/24/07 3:24 PM''
+ * '''Wiki Rendering Context:'''[[br]]We can't simply move all the responsibilities of the rendering context to the Formatter class, as Formatter objects are only present when explicitly rendering Wiki text, not generally available when rendering "content", in the mimeview module (the "content" which is rendered is coming from resources and that content may be wiki content). So we need something (a `RenderingContext` class?) that would be made available to the content renderers, and from there to the formatter, and from the formatter conveyed to the wiki processors. For example, the "blame" kind of annotation, now available for repository source file, later for other resources (#5821) is done at the mimeview layer, and doesn't depend on the wiki layer, so using a Formatter here is not appropriate. Another example of the use of a context which knowns about the "parent" context is to provide a way to guard against recursive content display. This is not yet that common for now, as the possibility to embed one content into another are limited so far (the !TicketQuery macro in table mode could lead to such a situation, though). So the `RenderingContext` is really something that belongs to the `trac.mimeview` layer and could be used in further developments to refactor/simplify that API as well (see #3332).
  * '''Permission System:''' if the permission system is not to be bound to the req, then I see no good reason why we use req.perm as its main entry point (other than backward compatibility issues). The rendering context  seems to be a possible place to store this information (who is accessing the content?). Alternatively, we could introduce an User object, for now as simple as a wrapper for the authname and a place to store the authentification cache.
    * About osimons points 2. and 3.: I think this is an interesting proposal. In order to get a resource descriptor at all, the accessor should at least have read access to it. This could for example be enforced by requiring a mandatory user argument when creating a resource descriptor: `ResourceManager(self.env, user).ticket(42)`.[[br]]Also, regardless from how the `PermissionCache` is obtained (currently req.perm), I think using it as the principal way to produce the resource identifiers is a good idea.