Template + data-model = output

Let's assume that you need a HTML page in a Web shop, similar to this:

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

But the user name ("John Doe" 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 too. Thus you can't enter these into the HTML directly, you can't use static HTML. Instead, you can use a template of the desired output. The template is the same as the static HTML would be, 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, 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. (Of course, the template file stored on the Web server is not changed by this; the substitutions only appear in the Web server's response.)

Note that the template doesn't contain the programming logic to find out who the current visitor is, or to query the database to get the latest product. The data to be displayed is prepared outside FreeMarker, usually by parts written in some "real" programming language like Java. The template author needn't know how these values were calculated. In fact, the way these values are calculated can be completely changed while the templates can remain exactly the same, and also, the look of the page can be completely changed without touching anything but the template. This separation of presentation logic and business logic can be especially useful when the template authors (designers) and the programmers are different individuals, but also helps managing application complexity if they are the same person. Keeping templates focused on presentation issues (visual design, layout and formatting) is a key for using template engines like FreeMarker efficiently.

The totality of data that was prepared for the template is called the data-model. As far as the template author is concerned, the data-model is a tree-like structure (like folders and files on your hard disk), which, in this case, could be visualized as:

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

The above is just a visualization; the data-model is not in a textual format, it's from Java objects. For the Java programmers, the root is perhaps a Java object with getUser() and getLatestProduct() methods, or maybe a Java Map with "user" and "latestProducts" keys. Similarly, latestProduct is perhaps a Java Object with getUrl() and getName() methods.

Earlier, you have picked values from this data-model, with the user and latestProduct.name expressions. If we go on with the analogy that the data model is like a file system, then "(root)" and latestProduct correspond to directories (folders), and user, url and name are files in those directories.

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