Template + data-model = output

Assume you need a HTML page in an e-shop application, similar to this:

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

Let's say that the user name ("Big Joe" above) should depend on who the logged in Web page visitor is, and the latest product should come from a database and thus it potentially changes at any moment. In this situation you can't just enter the user name nor the URL and name of the latest product into the HTML, you can't use static HTML.

FreeMarker's solution for this problem is using a template instead of the static HTML. The template is the same as the static HTML, except that it contains some instructions to FreeMarker that makes it dynamic:

<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 template is stored on the Web server, usually just like the static HTML page would be. But whenever someone visits this page, FreeMarker will step in and transform the template on-the-fly to plain HTML by replacing the ${...}-s with up-to-date content (e.g., replacing ${user} with Big Joe or whoever the visitor is) and send the result to the visitor's Web browser. So the visitor's Web browser will receive something like the first example HTML (i.e., plain HTML without FreeMarker instructions), and it will not perceive that FreeMarker is used on the server. The template file itself (which is, again, stored on the Web server) is not changed during this, so the transformation will happen again and again for each visiting. This ensures that the displayed information is always up-to-date.

Now, you already may have noticed that the template contains no instructions regarding how to find out who the current visitor is, or how to query the database to find out what the latest product is. It seems it just already know these values. And indeed that's the case. An important idea behind FreeMarker (actually, behind Web MVC) is that presentation logic and "business logic" should be separated. In the template you only deal with presentation issues, that is, visual design issues, formatting issues. The data that will be displayed (such as the user name and so on) is prepared outside FreeMarker, usually by routines written in Java language or other general purpose language. So the template author doesn't have to know how these values are calculated. In fact, the way these values are calculated can be completely changed while the templates can remain the same, and also, the look of the page can be completely changed without touching anything but the template. This separation can be especially useful when the template authors (designers) and the programmers are different individuals.

While for FreeMarker (and for the template author) it's not interesting how the data was calculated, FreeMarker still have to know what the actual data is. All the data that the template can use is packed into the so called data-model. It's created by the already mentioned routines that calculate the data. As far as the template author is concerned, the data-model is a tree-like structure (like folders and files on your hard disk), that in this case could be visualized as:

(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. It's from Java objects, but let that be the problem of the Java programmers.)

Compare this with what you saw in the template earlier: ${user} and ${latestProduct.name}. As an analogy, the data model 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. So latestProduct.name is like saying name in the latestProduct directory. But as I said, it was just a simile; there are no files or directories here.

To recapitulate, a template and a data-model is needed for FreeMarker to generate the output (like the HTML shown first):

Template + data-model = output


FreeMarker Manual -- For FreeMarker 2.3.20 HTML generated: 2013-06-27 20:54:33 GMT