Module org.klojang.templates
Package org.klojang.templates

Class VarGroup

java.lang.Object
org.klojang.templates.VarGroup
public final class VarGroup extends Object
Variable groups allow you to group template variables across one or more templates. This, in turn, allows you to format or escape their values in an identical manner — using a shared Stringifier. Within a template, variables can be assigned to a variable group by using the variable group's name as a prefix. For example: ~%html:firstName% or ~%js:firstName% or ~%myDateFormat:birthDate%. The first two examples specify the predefined HTML and JS variable groups, which provide HTML-escaping and ECMASScript-escaping, respectively. The predefined variable groups mostly rely on apache.commons.text to do the actual escaping. The third example is a custom group that you can define using the StringifierRegistry class. Variable groups can also be assigned in a more ad hoc manner using the API. Many methods of the RenderSession class take a VarGroup argument.

Note that variable groups are assigned at the variable occurrence level. For example, a template may contain multiple instances of a variable named firstName. For occurrences inside a <script> tag you might want to use the js: prefix, for the others the html: prefix. Therefore, stringifiers associated with a variable group take the highest precedence, even higher, perhaps counterintuitively, than stringifiers associated with a variable.

Author:
Ayco Holleman

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final VarGroup
    ATTR
    A predefined variable group corresponding to the attr: prefix.
    static final VarGroup
    DEF
    A predefined variable group corresponding to the def: prefix.
    static final VarGroup
    HTML
    A predefined variable group corresponding to the html: prefix.
    static final VarGroup
    JS
    A predefined variable group corresponding to the js: prefix.
    static final VarGroup
    JS_ATTR
    A predefined variable group corresponding to the jsattr: prefix.
    static final VarGroup
    PARAM
    A predefined variable group corresponding to the param: prefix.
    static final VarGroup
    PATH
    A predefined variable group corresponding to the path: prefix.
    static final VarGroup
    TEXT
    A predefined variable group corresponding to the text: prefix.

  • Method Summary

    Modifier and Type
    Method
    Description
    static VarGroup
    forName(String name)
    Returns the VarGroup with the specified name (which is also the prefix to be used inside a template).
    String
    getName()
    Returns the name of this VarGroup, which is also the prefix to be used inside a template.
    String
    toString()
    Returns the name of this VarGroup, which is also the prefix to be used inside a template.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • TEXT

      public static final VarGroup TEXT
      A predefined variable group corresponding to the text: prefix. Forces the variable instance to be stringified using the default stringifier.

    • HTML

      public static final VarGroup HTML
      A predefined variable group corresponding to the html: prefix. Variables with this prefix are HTML-escaped. Note that the fact alone that a variable appears inside an HTML element, as in <td>~%age%</td>, does not mean that the variable has to have the html: prefix. The age variable likely is an integer, which does not require any HTML escaping.

    • JS

      public static final VarGroup JS
      A predefined variable group corresponding to the js: prefix. Variables with this prefix are ECMASScript-escaped. Especially for use in <script> tags.

    • ATTR

      public static final VarGroup ATTR
      A predefined variable group corresponding to the attr: prefix. Works just like the html: prefix except that single and double quote characters are also escaped. Especially for use in element attribute values.

    • JS_ATTR

      public static final VarGroup JS_ATTR
      A predefined variable group corresponding to the jsattr: prefix. Variables with this prefix are first JavaScript-escaped and then HTML-escaped like the ATTR variable group. Especially for use in HTML attributes that contain JavaScript, like onclick .

    • PARAM

      public static final VarGroup PARAM
      A predefined variable group corresponding to the param: prefix. To be used for template variables placed inside a URL as the value of a query parameter, like http://example.com/?id=~%param:id%. It could also be used in the more unlikely case that the variable functions as the name of the query parameter, because names and values are escaped identically in a URL. Note that it does not matter whether the URL as a whole is the value of a JavaScript variable or the contents of an HTML tag. Further escaping using either JavaScript-escaping rules or HTML-escaping rules would not change the value.

    • PATH

      public static final VarGroup PATH
      A predefined variable group corresponding to the path: prefix. To be used for template variables placed inside a URL as a path segment. For example: http://example.com/~%path:city%/~%path:restaurant%.

    • DEF

      public static final VarGroup DEF

      A predefined variable group corresponding to the def: prefix. This prefix will cause null values to be replaced with the placeholder value defined within the template. The example below will render as "Good morning, John" if firstName was null. 

      
 Good morning, <!-- ~%def:firstName% -->John<!--%-->

      See Regex.REGEX_CMT_VARIABLE for an explanation of the syntax and purpose of placeholder values.

  • Method Details

    • forName

      public static VarGroup forName(String name)
      Returns the VarGroup with the specified name (which is also the prefix to be used inside a template). Throws an IllegalArgumentException if there is no VarGroup with the specified name.
      Parameters:
      name - the name or prefix
      Returns:
      the VarGroup instance corresponding to the specified name

    • getName

      public String getName()
      Returns the name of this VarGroup, which is also the prefix to be used inside a template.
      Returns:
      the name of this VarGroup

    • toString

      public String toString()
      Returns the name of this VarGroup, which is also the prefix to be used inside a template.
      Overrides:
      toString in class Object
      Returns:
      the name of this VarGroup