Template + data-model = output - Apache FreeMarker Manual

Unsupported web browser - Use a modern browser to view this website!

- Home
- Manual
- Java API

- Contribute
- Report a Bug
- Download

Manual
Previous Next

# Template + data-model = output

Let's assume that you need a HTML page on a website, similar to this:

Output

    <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's name ("John Doe" above) depends on who the logged-in user is, and the latest product information should come from a database. Because this data changes, you cannot 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:

Template

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

Data Model

    (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

Previous Next