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.)