Welcome to the Instant FreeMarker Starter. This book has been specially created to provide you with all the information that you need to get set up with FreeMarker. You will learn the basics of FreeMarker, get started with building your first template, and discover some tips and tricks for using FreeMarker.
This document contains the following sections:
So, what is FreeMarker? explains what FreeMarker actually is, what you can do with it, and why it’s so great.
Installation discusses how to download and install FreeMarker with the minimum fuss and then set it up so that you can use it as soon as possible.
Quick start – creating your first template shows you how to use the primary function of FreeMarker: creating text by populating a template with data. We will create a small command-line Java application called “Hello FreeMarker” that shows the essential operations.
Top 9 features you need to know about discusses how to perform tasks with the most important features of FreeMarker. By the end of this section you will be able to create sophisticated templates for producing dynamic output using powerful expressions, macros, functions, and flow control directives. You will also see how to integrate FreeMarker with popular web application frameworks.
People and places you should get to know provides you with many useful links to the project page and forums, as well as a number of helpful articles, tutorials, blogs, and the Twitter feed of FreeMarker super-contributors.
Just as I began writing this guide, I spoke with a colleague who told me this about his new project. "We're using something I haven't heard of before. It's like JSP, but much cleaner. It's called FTL," he explained.
He was referring to FreeMarker Template Language (FTL), which is the notation used to create a template with FreeMarker. FTL resembles JSP, and if that description makes FreeMarker seem instantly familiar to you, then it's a good introduction. It's not a perfect introduction because FreeMarker has some important differences from JSP. The good news for those familiar with JSP is that almost everything that makes FreeMarker different makes it simpler.
To see how much simpler, let's step away from the world of N-tier client-server applications and look at one of the oldest information technologies of the industrial age: the fill in the blank form. These forms feature boilerplate text that is customized by entering values into gaps left open for that purpose. A common example is a lease contract which is mostly text, but needs you to fill in a few variables such as your name, number of months for the lease, and the monthly rent amount. The contract may also feature conditional sections, such as an addendum if you have pets. This is in every sense a dynamic, data-driven document, and it's been around since the printing press became a commonplace.
Producing dynamic content—when web pages, e-mails, or even generated source code—is not fundamentally different than completing the hypothetical paper contract. The final document is a mosaic of static text (for example, HTML markup) and variable text. In FreeMarker, we call the boilerplate document a template and the variable text a model. These cleanly implement the "model" and "view" of the standard MVC architecture used in modern web applications.
JSP can be used the same way, but it requires a great deal of discipline. You can write an entire application (badly) using only JSPs. However, you cannot write an application in FTL—it is a view-only technology. For example, JSP can fetch data from a database to display, but FTL requires that controller logic to do this beforehand and collect the results in a model object. In a properly-implemented MVC application, JSP code should not be making database calls—or a great deal more that it can do—but such code frequently slips in over time and the application becomes an unmaintainable mess.
Tackling complexity is frequently accomplished by breaking code blocks into smaller parts. Because JSP is a part of the Servlet API, breaking a page across JSPs requires heavyweight Servlet dispatch operations. FreeMarker is lightweight, and breaking a page across templates introduces very little overhead.
Another approach to handling complexity in JSPs is to create custom tag libraries. You can do this with either customized Java code, or using JSP. JSP tags allow for complex variable passing including allowing them to share state across tags. FreeMarker offers a couple of different mechanisms to script and encapsulate customized logic using lightweight constructs that are easy to learn and master.
You may be starting with FreeMarker because your organization has become fed up with JSP (or another page-scripting language) because of its history. Perhaps FreeMarker is seen as a clean new start. Make the most of this fresh start and learn how to create a solid foundation for your FreeMarker view layer. That is what we are going to do in the following sections.