public interface SafeHtmlTemplates

A tag interface that facilitates compile-time binding of HTML templates to generate SafeHtml strings.

Example usage:

   public interface MyTemplate extends SafeHtmlTemplates {
     @Template("<span class=\"{3}\">{0}: <a href=\"{1}\">{2}</a></span>")
     SafeHtml messageWithLink(SafeHtml message, String url, String linkText,
       String style);
   }

   private static final MyTemplate TEMPLATE = GWT.create(MyTemplate.class);

   public void useTemplate(...) {
     SafeHtml message;
     String url;
     String linkText;
     String style;
     // ...
     SafeHtml messageWithLink =
       TEMPLATE.messageWithLink(message, url, linkText, style);
   }
 

Instantiating a SafeHtmlTemplates interface with GWT.create() returns an instance of an implementation that is generated at compile time. The code generator parses the value of each template method's @Template annotation as an HTML template, with template variables denoted by curly-brace placeholders that refer by index to the corresponding template method parameter.

The code generator's template parser is lenient, and will accept HTML that is not well-formed; the accepted set of HTML is similar to what is typically accepted by browsers. However, the following constraints on the HTML template are enforced:

1. Template variables may not appear in a JavaScript context (inside a <script> tag, or in an onClick etc handler).
2. Template variables may not appear inside HTML comments.
3. If a template variable appears inside the value of an attribute, the value must be enclosed in quotes.
4. Template variables may not appear in the context of an attribute name, nor elsewhere inside a tag except within a quoted attribute value.
5. The template must end in "inner HTML" context, and not inside a tag or attribute.

Limitation: For templates with template variables in a CSS (style) context, the current implementation of the code generator does not guarantee that the generated template method produces values that adhere to the SafeHtml type contract. When the code generator encounters a template with a variable in a style attribute or tag, such as, <div style=\"{0}\">, a warning will be emitted. In this case, developers are advised to carefully review uses of this template to ensure that parameters passed to the template are from a trusted source or suitably sanitized.

Future implementations of the code generator may place additional constraints on template parameters in style contexts.