This page contains information about advanced HTML encoding for Confluence plugins.
In some cases a method may return a collection of values, each of which contain HTML markup to be treated literally in a Velocity template. If a collection returning method is marked as , then all of its members will be treated as as well should they be written to a Velocity template.
More precisely, a value retrieved from a collection will be treated as in the following situations:
One of the things that has become painfully obvious in the implementation of this system is the inadequacy of the class for returning markup. The need for a annotation is only necessary because a return type does not convey any information about the data returned other than it is a sequence of characters. The class is a type that can be used to indicate that the method of a particular object returns markup to be interpreted as literal HTML during rendering.
HtmlFragment aHtmlFragment = new HtmlFragment("<span>This string contains literal HTML</span">); HtmlFragment anotherHtmlFragment = new HtmlFragment(new MyHtmlClass());
The class' method delegates to the wrapped object's method and will be treated as being safe for use in HTML templates. This is useful for adding your own values directly to a Velocity context or as a return type for methods returning HTML markup.
The class defines methods of the form for convenient rendering of a template to a . Unfortunately the only information available to this mechanism is the template name and Velocity context, neither of which indicate directly whether the template is to be used for HTML output. It is using HTML encoding by default, unless you explicitly opt-out using the directive. Opting out is recommended only for troubleshooting purposes.
To help track down any Velocity reference that might be encoded incorrectly, Confluence attaches a logging event listener to the Velocity context. This event listener will print the reference name and the template that contains the reference if the reference value contains HTML like markup (either element markup or encoded entities) but the reference hasn't been marked as HTML safe. Naturally some values may contain HTML markup that are not meant to be interpreted as literal HTML, as is the case in HTML injection attacks.
This event listener will only be active if the log4j logger category has been set to log at .
Confluence employs a specialisation of Velocity's pluggable, federated introspection strategy known as an . The Velocity runtime delegates all method calls, property accesses and iterator strategy retrieval via the configured uberspect. The default Velocity uberspect implementation provides all of the facilities to call methods and access properties of objects in the Velocity context by making heavy use of the Java reflection API. It also provides the mechanism for case insensitive property access, Velocity's map getter syntactic sugar and uses an internal introspection cache to optimise performance.
To enable the tracking of values retrieved from sources, Confluence is configured to use a specialised uberspect that boxes any annotations with the method return value. Return values from method calls that do not have any such annotations are treated exactly as before. Of course any of these uberspect boxed values may be subsequently used as arguments or targets of other method calls, so the annotation boxing uberspect is also responsible for unboxing these values before a method is executed, providing a mostly transparent operation.
For those developers who are more interested in the exact implementation details, you will want to examine the source of the classes in the new package, with the being the best place to start.
Rate this page: