ST condensed -- Key topics

Studying StringTemplate: Key topics of interests

The following bullet points touch on most of the main features of templates. The details for all these topics are to be found in subsequent articles of this series.

• Templates and Expressions
  • A template has a Template text or body
    • Template text = literal text (to be output verbatim) alternating with expressions (to be processed to generate text to insert)
    • To distinguish expressions within the template text, they are marked off by expression delimiter characters.
    • You can set the delimiters to be either $...$ or <...> depending on which is most distinct from the surrounding literal text. (Each StringTemplate or StringTemplateGroup constructor sets a particular default for expression delimiter, which can be overridden in various ways. See later details.)
    • IMPORTANT: StringTemplate documentation examples may show either delimiter. Avoid mistakenly thinking that these mean different things. They are equivalent.
  • StringTemplate class (and objects)
    • Encapsulates preparation and processing of templates
    • Your program provides template text to a StringTemplate object
      • from a String, or...
      • loaded from a stream or file (from a template file xxx.st, or from a template group file, see below).
    • Your program provides values to the StringTemplate object by way of named attributes
  • During processing of a StringTemplate, eg: myStringTemplate.toString():
    • Literal text within the template text is copied verbatim to the result, interspersed with expression results.
    • Expressions within the template text obtain their values by name from the StringTemplate's list of attributes (which your program provided), and produce string results to be inserted in the template's result text.
    • Expressions can also refer to other templates:
      • subtemplates defined on-the-spot in expressions in the current template
      • named templates defined elsewhere and belonging to the same template group
• Template Groups
  • StringTemplateGroup class (and objects)
    • Encapsulates preparation and processing of a group of named templates whose expressions can invoke by name other templates belonging to the group
    • Though your program could invoke directly a StringTemplate from a group, instead usually your program would treat a template group like a library of templates:
      • make an instance of a desired template from the template group, and provide that with the attributes (values) for this specific invocation.
  • Can be created with settings to get templates from:
    • A template group directory containing individual template files: xxx.st
    • A Reader object, which reads
      • A template group file: xxx.stg, or...
      • A String containing text in the same sytax as an stg file.
• Three slightly different modes of operation
  • Different modes involve more or less features relating to managing multiple templates, and complex relationship between templates.
  • Depending on mode, features include:
    • Formal arguments: template definitions can include declaration of arguments. (stg files only)
    • Template group inheritance and interface feature
      • Inheritance: A StringTemplateGroup can have an inheritance relationship with another group ("Supergroup"). The subgroup acts as though it contains all the features of the supergroup, and can provide overrides only for features that need to be different.
      • Interfaces: A StringTemplateGroup file can provide an interface definition which other StringTemplateGroups can commit to implement.

Look for an elaboration on all of these features in subsequent articles in this series.

Next: ST condensed -- Templates and groups