Basics

You have seen how to build a data-model in the Getting Started using the standard Java classes (Map, String, etc.). Internally, the variables available in the template are Java objects that implement the freemarker.template.TemplateModel interface. But you could use standard Java collections as variables in your data-model, because these were replaced with the appropriate TemplateModel instances behind the scenes. This facility is called object wrapping. The object wrapping facility can convert any kind of object transparently to the instances of classes that implement TemplateModel interface. This makes it possible, for example, to access java.sql.ResultSet as sequence variable in templates, or to access javax.servlet.ServletRequest objects as a hash variable that contains the request attributes, or even to traverse XML documents as FTL variables (see here). To wrap (convert) these objects, however, you need to plug the proper ObjectWrapper implementation (possibly your custom implementation); this will be discussed later. The point for now is that any object that you want to access from the templates, sooner or later must be converted to an object that implements TemplateModel interface. So first you should familiarize yourself with writing of TemplateModel implementations.

There is roughly one freemarker.template.TemplateModel descendant interface corresponding to each basic type of variable (TemplateHashModel for hashes, TemplateSequenceModel sequences, TemplateNumberModel for numbers, etc.). For example, if you want to expose a java.sql.ResultSet as a sequence for the templates, then you have to write a TemplateSequenceModel implementation that can read java.sql.ResultSet-s. We used to say on this, that you wrap the java.sql.ResultSet with your TemplateModel implementation, as basically you just encapsulate the java.sql.ResultSet to provide access to it with the common TemplateSequenceModel interface. Note that a class can implement multiple TemplateModel interfaces; this is why FTL variables can have multiple types (see: Template Author's Guide/Values, Types/Basics)

Note that a trivial implementation of these interfaces is provided with the freemarker.template package. For example, to convert a String to FTL string variable, you can use SimpleScalar, to convert a java.util.Map to FTL hash variable, you can use SimpleHash, etc.

An easy way to try your own TemplateModel implementation, is to create an instance of that, and drop it directly into the data-model (as put it into the root hash). The object wrapper will expose it untouched for the template, as it already implements TemplateModel, so no conversion (wrapping) needed. (This trick is also useful in cases when you do not want the object wrapper to try to wrap (convert) a certain object.)