ST condensed -- Introduction
Introduction
This series of "ST condensed" articles is aimed at providing a collection of information about StringTemplate that is substantially complete in its coverage of features, and coherent and current, while also being compact. "Current" means as of this writing, StringTemplate version 3.2, May 2009.
The hope is to have at least mentioned all important topics and how they fit together. These articles may then serve as an initial map of the whole territory, and also as a reference to many of the oft-needed details. However, for more extensive discussions of the whys and wherefores, please refer to the lengthier users' guide articles, starting here: StringTemplate 3 Documentation .
Note on Java
All the examples of application code (calling StringTemplate) are written in Java. Unlike the users' guide, I have not gone to the lengths of including examples in Python or C# as this series of articles is more focused on just bringing attention to features of StringTemplate, rather than covering every language.
The Basic Idea
The StringTemplate library eases the task of composing some possibly complex text from an application's data. The inputs to the process are some template text in which are embedded expressions understood by StringTemplate, plus some attribute values supplied by the program for a particular invocation of the template.
- Application creates a StringTemplate object, and provides the text of a template (from string or file).
- Application sets template attributes and their values.
- Application invokes StringTemplate's toString to get the result of merging the attributes into the template.
A special focus of StringTemplate is the maintaining of a strict separation of concerns between your application's (data) model and the view created via the StringTemplate apparatus. You can read the rationales behind StringTemplate's design and feature set in this paper: Enforcing Model-View Separation in Template Engines
Preview of The Details
The remainder of the story involves two main elaborations of the template idea:
- Features relating to use and management of a large number of possibly complicated and inter-related templates.
- Features of the template expression "language" which facilitate the insertion of data into the template in various ways.
The next article in the series, ST condensed -- Key topics, provides an overview of the features of the StringTemplate world. Subsequent articles detail the topics of managing templates, the template expression language, and then other subsidiary subjects.
Finally, there are annotated versions of the javadocs for two of the key classes: StringTemplate and StringTemplateGroup, drawing attention to and commenting upon the main methods of interest.
Comment
The information here is based on the author's reading of the existing documentation, and to a certain extent the javadocs and the source code. The author has not been involved in actual development of StringTemplate, and quite possibly has misinterpreted some feature or other or made actual mistakes! Feel free to update points that are incorrect, or add comments. Possibly at some point ideas from this document might be used to revisit the older StringTemplate user guide documents.