Template + data model = output

FreeMarker is based on the notion that designers and programmers are different individuals with different specialized skills. Ideally, there is a division of labor in which designers concentrate on presentation -- they create HTML files, images, and other visual aspects of the web page. Meanwhile, programmers create systems that generate the data that the designers' pages will display.

The problem is that often you have to display information on a web page (or possibly some other kind of document) which is not available when you design the page. A typical e-commerce application is based on this kind of dynamic data -- for example, the up-to-the-minute state of inventory, the conversion ratio between the dollar and yen, whether a customer's order has been sent. And so on. These are values that constantly change. In such cases, you will put some special instructions in your HTML (or whatever text you want as output; FreeMarker's output is not limited to HTML) and FreeMarker will replace those codes with the appropriate data when it comes time to output the page to an end-user. Let's start with a very simple example: You have to greet the user with his name and mention your company's latest product on the welcome page:

<html>
<head>
  <title>Welcome!</title>
</head>
<body>
  <h1>Welcome ${user}!</h1>
  <p>Our latest product:
  <a href="${latestProduct.url}">${latestProduct.name}</a>!
</body>
</html>  

The above is just like a normal snippet of HTML except for certain special codes surrounded by ${...}. These codes are instructions to FreeMarker that tell it to where to put certain pieces of timely text when it sends the output to an end-user. Files like this are called templates.

Where do the user, latestProduct.url and latestProduct.name come from? They are copied from the data model. The data model is something that exists in the memory of the computer. The program written by the programmers creates the data model, and it is the mechanism by which the template is provided with changing information. This information may come from a database, a file, or even be generated on the spot by the program. But it's irrelevant to the template author where the data comes from. The template author just uses the already built data model.

We say that the output is created by merging a template and a data model:

Template + data model = output

This is a possible data model:

(root)
  |
  +- user = "Big Joe"
  |
  +- latestProduct
      |
      +- url = "products/greenmouse.html"
      |
      +- name = "green mouse"  

(To prevent misunderstandings: The data model is not a text file, the above is just a visualization of a data model for you.)

As an analogy, it is something like the file system of computers: the root and latestProduct correspond to directories (folders) and the user, url and name correspond to files. url and name are in the latestProduct directory. But this was just a simile; there are no real files or directories here.

When FreeMarker merges the above data model with the example template, the visitor to the Web page gets the following output:

<html>
<head>
  <title>Welcome!</title>
</head>
<body>
  <h1>Welcome Big Joe!</h1>
  <p>Our latest product:
  <a href="products/greenmouse.html">green mouse</a>!
</body>
</html>  

Page generated: 2006-03-15 13:49:01 GMT FreeMarker Manual -- For FreeMarker 2.3.6