This page last changed on Jan 17, 2007 by mryall.
Rendering frameworks
There are two frameworks that do the template rendering in Confluence: Webwork and Sitemesh. The confusing bit is that both of them use Velocity as their templating engine. We try to distinguish them by using *.vm for templates processed by Webwork, and *.vmd for those processed by Sitemesh.
Rendering contexts
There are four different Velocity contexts used in Confluence:
- templates processed by Webwork use the context defined in ConfluenceVelocityContext
- templates processed by Sitemesh as a result of the #applyDecorator() directive use the context defined in ApplyDecoratorDirective
- templates processed by Sitemesh as a result of the URL mapping in decorators.xml use the context defined in ProfilingPageFilter
- templates processed by the notification queue use the context defined in VelocityRenderedQueueItem.
The two Sitemesh contexts are pretty much the same, but the Webwork velocity context contains a lot more stuff than either of the Sitemesh ones.
Rendering pipeline
So the general flow of control goes:
- Webwork gets request, maps request URL to action using xwork.xml
- Webwork maps response of action to a Velocity template using xwork.xml
- Webwork launches Velocity handler on template (*.vm) with context defined in ConfluenceVelocityContext
- Velocity process content in *.vm file
- Within an #applyDecorator() directive:
- Velocity calls the ApplyDecoratorDirective class with the parameters and body content of the directive
- Any #decoratorParam() directives are processed by the ParamDirective class, which pushes bits of the current Velocity context into the ApplyDecoratorDirective parameters
- ApplyDecoratorDirective matches the name parameter of the directive with a *.vmd file from decorators.xml
- ApplyDecoratorDirective launches Sitemesh on a decorator template (*.vmd) with context defined in ApplyDecoratorDirective
- Sitemesh returns decorated content
- Velocity template finished processing rest of *.vm file, returns to Webwork
- Web.xml servlet filter 'sitemesh' maps to ProfilingPageFilter, a Sitemesh page filter
- Sitemesh uses the request URL mapping in decorators.xml to launch a decorator template (*.vmd) with context defined in ProfilingPageFilter
- Sitemesh returns decorated content as response.
You can find out which beans are in which context by looking in the classes above. A full list would be too long to include here. Note that even though the ApplyDecoratorDirective launches a Sitemesh decorator template, the Sitemesh template doesn't get automatic access to the Velocity context. The only bits that are passed through are done with the #decoratorParam() directive.
Wow, pretty complicated. But it lets us do cool stuff like implement custom themes, apply layouts and more.
|