FreeMarker模板引擎快速实现HTML生成教程

烟幕缭绕

于 2024-08-31 16:15:41 发布

阅读量199

点赞数 15

本文链接：https://blog.csdn.net/weixin_35987118/article/details/141787441

版权

本文还有配套的精品资源，点击获取

简介：FreeMarker是一个用于Java应用程序的模板引擎，可以生成包括HTML在内的多种文本格式。它通过结合模板文件和数据模型来分离视图层并实现MVC模式。本教程将引导你完成从安装FreeMarker、创建模板文件、构建数据模型，到配置、加载模板，以及最终输出HTML结果的整个过程。此外，还会介绍如何将JSON数据转换为模板引擎的数据模型，以及如何处理异常、优化性能等高级应用。实现FreeMark读取模板生成HTML

1. FreeMarker介绍与用途

FreeMarker是一个开源的Java类库，被广泛用于生成文本输出，特别是在MVC模式中用于生成HTML页面。它通过模板文件和数据模型的结合来生成文本，这个过程类似于JSP和PHP，但是FreeMarker是作为普通的Java类库在Servlet外面运行，而不是在Servlet里面。

FreeMarker不仅仅可以用于Web应用。事实上，它能应用于任何需要根据数据动态生成文本的地方，比如生成配置文件、源代码等。FreeMarker的模板文件是用FreeMarker模板语言（FTL）编写的，这是一种简单的用于输出文本的模板语言。

FreeMarker的核心在于将业务数据模型展示给用户。它有一个强大的模板引擎，提供了一种简单的方式来分离业务逻辑和内容展示。模板设计师可以专注于设计模板而无需关注底层的业务逻辑，而开发人员可以集中精力在后端的业务逻辑上。

flowchart LR
    A[业务数据模型] -->|传递给| B[FreeMarker模板引擎]
    B -->|处理| C[生成最终文本]

上述流程图展示了FreeMarker如何将业务数据模型转换为最终文本的过程。在下一章中，我们将探讨如何在项目中安装和引入FreeMarker依赖，并开始构建我们的第一个模板。

2. 安装与引入FreeMarker依赖

2.1 环境准备和安装步骤

2.1.1 选择合适的FreeMarker版本

FreeMarker 是一个用于生成文本输出的 Java 库，其版本迭代遵循语义化版本控制。在选择版本时，应考虑以下因素：

项目依赖的 Java 版本 ：确保选定的 FreeMarker 版本与你的项目依赖的 Java 版本兼容。
功能需求 ：每个版本更新可能包含新功能、bug修复或性能优化。根据你的项目需求，可能需要特定版本以获得所需的特性。
安全性 ：避免使用已知含有安全漏洞的旧版本。
支持与维护 ：选择一个仍被积极维护的版本。

通常，官方推荐使用最新的稳定版本。你可以在 [FreeMarker 官方网站](*** 上查找最新版本信息，以及与版本相关的支持和下载链接。

2.1.2 安装FreeMarker的环境要求

在安装 FreeMarker 前，需要确保你的开发环境满足以下要求：

Java 开发环境 ：FreeMarker 是一个 Java 库，因此你的开发机器上必须安装有 Java 开发工具包（JDK）。支持的 JDK 版本可在 [FreeMarker 官网](*** 上找到。
构建工具 ：如果你的项目使用 Maven 或 Gradle，确保安装了相应的构建工具，并且配置了正确的仓库源。
集成开发环境 （IDE）：对于 Java 开发，推荐使用 Eclipse、IntelliJ IDEA 等集成开发环境，这些环境对 FreeMarker 的支持良好。

2.2 引入FreeMarker依赖到项目

2.2.1 Maven项目的依赖引入方法

Maven 是目前 Java 社区中广泛使用的项目管理工具，要将 FreeMarker 集成到 Maven 项目中，需要编辑项目的 pom.xml 文件，并添加以下依赖：

<dependencies>
    <dependency>
        <groupId>org.freemarker</groupId>
        <artifactId>freemarker</artifactId>
        <version>2.3.31</version> <!-- 请替换为你所需版本号 -->
    </dependency>
</dependencies>

2.2.2 Gradle项目的依赖引入方法

对于使用 Gradle 构建的项目，你需要在 build.gradle 文件中加入以下依赖声明：

dependencies {
    implementation 'org.freemarker:freemarker:2.3.31' // 请替换为你所需版本号
}

一旦添加了依赖，构建工具会自动下载所需的 FreeMarker 库到本地或项目依赖仓库，并且在编译和运行项目时自动引入。

安装与配置小结

安装 FreeMarker 并将其集成到你的项目中是一个相对简单的步骤，但确保你遵循了最佳实践，如选择合适的版本、准备合适的开发环境和正确地使用构建工具来管理依赖。接下来的章节中，我们将深入学习如何创建与编写 FreeMarker 模板文件，并探索其丰富的模板指令和语法。

3. 创建与编写FreeMarker模板文件

在本章节中，我们将深入了解FreeMarker模板文件的创建与编写，包括模板的基本结构、高级特性，以及如何使用这些特性来构建动态内容丰富的Web页面。

3.1 模板文件的基本结构

3.1.1 模板指令和语法基础

FreeMarker模板文件通常具有 .ftl （FreeMarker Template Language）扩展名。模板由静态文本、FreeMarker指令和插值表达式组成。指令以 # 符号开始，例如 <#if> 或 <#list> ，用于控制模板逻辑流程，如条件判断和循环。

在编写指令时，以下是一些基本规则： - 指令总是以 # 开始，后跟指令名称。 - 指令参数之间用空格分隔。 - 指令可以有可选的内嵌文本，通常由 <#-- ... --> 来包围。

举例来说， <#if condition> 是用来进行条件判断的指令，其中 condition 是需要评估的表达式。

3.1.2 模板变量与表达式的使用

模板变量通常用于存储数据模型中的数据。变量在模板中的语法是 <#assign variable = value> ，这里 variable 是变量名， value 是从数据模型中获取的值。例如：

<#assign user = users[0]>

表达式则用于在模板中处理变量或常量，执行操作如比较、算术运算等。FreeMarker表达式使用 <#== ... #> 来包围，例如：

Hello, <#== user.name #>!

在这个例子中， user.name 是从数据模型 user 对象中获取的名字，并将被替换为相应的值。

3.2 模板的高级特性

3.2.1 内建函数和宏的使用

FreeMarker 提供了丰富的内建函数，用于字符串处理、数学运算等常见任务。例如：

${someVar?upper_case}

upper_case 是一个内建函数，用于将变量 someVar 的值转换为大写。

宏（Macros）是一种定义可重复使用的代码片段的方法。创建宏的基本语法如下：

<#macro repeatMessage msg count>
    <#list 1..count as i>
        ${msg}
    </#list>
</#macro>

这里定义了一个名为 repeatMessage 的宏，它接受两个参数 msg 和 count ，并重复显示 msg 指定次数。

3.2.2 模板的继承和包含机制

继承和包含是模板设计中实现代码复用的关键特性。 <#nested> 是一个特殊的变量，用于在子模板中指定插入点。

<#-- 定义一个基础模板结构 -->
<#-- base.ftl -->
<html>
<head>
    <title>${title}</title>
</head>
<body>
    <#-- 内容插入点 -->
    <#nested>
</body>
</html>

继承该基础模板的其他模板可以这样写：

<#-- 使用基础模板 -->
<#-- page.ftl -->
<#inherit base>
<title>My Page Title</title>
<p>This is the content that goes inside the base template.</p>

使用 <#inherit> 指令可以继承 base.ftl 模板，并用新内容覆盖 <#nested> 指定的位置。这样，我们可以创建一个标准的页面结构，并在不同的页面中复用它。

通过这些高级特性的应用，开发者可以构建出更模块化、更易于管理的模板结构，从而提高开发效率和维护的便利性。

在下一节，我们将继续深入了解如何构建数据模型，并将其与模板绑定以生成动态内容。

4. 构建数据模型及数据绑定

4.1 数据模型的概念与构建

4.1.1 数据模型的基本构成

在FreeMarker中，数据模型是用于渲染模板的基础。它本质上是一个键值对集合，其中键是字符串，值可以是任何基本数据类型、容器（如哈希表、列表）或自定义对象。数据模型构建是将业务数据整理成可以被FreeMarker模板引擎识别和处理的结构。

要构建一个数据模型，首先需要理解业务逻辑，确定哪些数据需要传递给模板进行展示。例如，在一个用户管理系统中，我们可能会有一个显示用户信息的页面，这里的数据模型将包含用户的姓名、年龄、性别、邮箱等属性。

// 示例：构建一个简单的数据模型
Map<String, Object> userData = new HashMap<>();
userData.put("name", "张三");
userData.put("age", 30);
userData.put("gender", "男");
userData.put("email", "***");

上述代码定义了一个名为 userData 的HashMap，用于存储用户数据。这样的数据模型可以很容易地与FreeMarker模板结合，实现数据的动态展示。

4.1.2 数据模型的逻辑组织

为了使数据模型更加清晰和易于管理，合理组织数据结构是非常重要的。在实际开发中，数据模型通常具有层次性，可能包含多个子集，它们之间存在逻辑关系。通过合理设计数据模型的结构，可以使得模板更加简洁，并且在业务发生变化时可以更容易地进行维护。

例如，对于一个电商网站，我们可能会有一个包含多个子集的数据模型，如下所示：

Map<String, Object> productModel = new HashMap<>();
productModel.put("id", 12345);
productModel.put("name", "Smartphone");
Map<String, Object> priceModel = new HashMap<>();
priceModel.put("original", 499.99);
priceModel.put("discounted", 449.99);
productModel.put("price", priceModel);
productModel.put("description", "Latest smartphone with AI capabilities.");
productModel.put("inStock", true);

在这个例子中， productModel 是一个代表产品的复杂数据模型，它包含了产品ID、名称、价格信息、描述和库存状态。而价格信息又进一步细化为 priceModel ，其中包含原始价格和折扣后价格。通过这样的组织方式，我们可以很容易地在FreeMarker模板中展示产品信息，同时保持代码的可读性和可维护性。

4.2 数据绑定机制详解

4.2.1 数据绑定的流程和原理

FreeMarker的核心功能之一是数据绑定。数据绑定是指将数据模型与模板结合，通过模板指令将数据模型中的变量展示到最终生成的文档中。数据绑定的过程涉及到解析模板文件中的变量占位符，然后将相应的数据模型中的值替换进这些占位符，最终输出到HTML或其它格式的文件中。

数据绑定的过程通常在模板渲染之前进行。首先，应用层代码需要构建好数据模型，然后将这个数据模型传递给FreeMarker的模板引擎。FreeMarker引擎会遍历模板中的指令和变量，并根据提供的数据模型来填充这些指令或变量。

以Java为例，下面是一个简单的数据绑定流程：

Configuration cfg = new Configuration(Configuration.VERSION_2_3_28);
cfg.setClassForTemplateLoading(this.getClass(), "/templates");

Template temp = cfg.getTemplate("user_info.ftl");

Map<String, Object> root = new HashMap<>();
root.put("user", new User("张三", 30));

Writer out = new OutputStreamWriter(System.out);
temp.process(root, out);

上述代码首先创建了一个 Configuration 对象并设置了模板加载路径。之后，通过模板名称获取到一个 Template 对象。然后创建了一个数据模型 root ，其中包含一个 User 对象。最后，调用 process 方法将数据模型与模板合并，输出到标准输出流。

4.2.2 实现数据与模板的绑定

要实现数据与模板的绑定，必须清楚地定义模板文件中的变量，并确保在数据模型中有对应的数据结构。模板文件使用FreeMarker模板语言（FTL）编写，可以包含指令、变量和文本。

举个简单的例子来展示如何在FreeMarker模板中绑定数据：

<#-- user_info.ftl -->
<html>
  <head>
    <title>${user.name}'s Profile</title>
  </head>
  <body>
    <h1>Informations</h1>
    <p>Name: ${user.name}</p>
    <p>Age: ${user.age}</p>
    <p>Gender: ${user.gender}</p>
    <p>Email: ${user.email}</p>
  </body>
</html>

在这个 user_info.ftl 模板中， ${user.name} 、 ${user.age} 、 ${user.gender} 和 ${user.email} 都是要从数据模型中获取值的变量。在数据模型中，这些变量应该映射到相应的对象或值上。

当模板引擎解析此模板时，会查找 user 对象的 name 、 age 、 gender 和 email 属性，并将其值替换到模板的相应位置。最终生成的HTML将展示具体的用户信息。

<html>
  <head>
    <title>张三的Profile</title>
  </head>
  <body>
    <h1>Informations</h1>
    <p>Name: 张三</p>
    <p>Age: 30</p>
    <p>Gender: 男</p>
    <p>Email: ***</p>
  </body>
</html>

这样，通过数据绑定机制，我们可以将业务数据和模板结构相结合，生成符合业务需求的文档输出。

5. FreeMarker配置与模板加载

5.1 FreeMarker配置概述

5.1.1 配置文件的编写与读取

FreeMarker配置是整个模板引擎运行的基础，它负责控制模板的行为，包括错误处理、输出格式、模板加载机制等。FreeMarker通过属性文件、XML文件或Java代码的方式进行配置。这里以属性文件为例，介绍如何编写和读取配置。

首先，创建一个名为 freemarker.properties 的配置文件，以下是一个配置文件的简单例子：

# 设置模板文件的默认字符集
default_encoding = UTF-8

# 设置错误页面的路径
template_update_delay = 2

# 设置模板文件的目录
template_loader_class = freemarker.cache.ClassTemplateLoader

在Java代码中读取配置文件可以使用 Configuration 类的 setSettings 方法：

Configuration cfg = new Configuration(Configuration.VERSION_2_3_28);
// 设置配置文件的位置，可以是文件路径或类路径资源名
cfg.setSettings("freemarker.properties");

5.1.2 配置项详解及其作用

FreeMarker的配置项很多，这里列举一些常用配置项，并解释它们的作用：

default_encoding ：设置模板文件默认的字符编码。如果在模板中没有特别指定编码，将使用此配置项指定的编码。
template_update_delay ：设置模板文件更新检查的周期，单位为秒。此配置用于检测模板文件变化，当模板文件被外部修改时，可以在一定周期后重新加载。
template_loader_class ：设置模板加载类。模板加载器负责从文件系统或类路径中加载模板文件，FreeMarker提供了多种内置的模板加载器实现。

表格：常见FreeMarker配置项列表

| 配置项 | 描述 | 默认值 | |----------------------|--------------------------------------------------------------|------------------| | default_encoding | 模板文件的默认字符编码。 | UTF-8 | | template_update_delay | 模板文件变化检查周期，以秒为单位。 | 2 | | template_loader_class | 模板文件加载类。 | ClassTemplateLoader | | whitespace_stripping | 控制空白字符的处理策略。 | true | | number_format | 控制数字输出格式，类似Java中的DecimalFormat。 | ***.00 |

理解这些配置项对于定制化模板引擎的行为至关重要，能够帮助开发者优化模板处理流程，提升性能和用户体验。

5.2 模板的加载与缓存策略

5.2.1 模板加载机制

模板加载机制决定了FreeMarker如何找到并读取模板文件。FreeMarker提供了多种模板加载器，其中最常用的是 ClassTemplateLoader 和 FileTemplateLoader 。前者从类路径中加载模板，后者从文件系统中加载模板。

模板加载器的配置通常在初始化 Configuration 对象时完成，例如：

// 使用类路径作为模板加载器
cfg.setTemplateLoader(new ClassTemplateLoader(getClass(), "/templates/"));

// 或使用文件系统路径作为模板加载器
cfg.setTemplateLoader(new FileTemplateLoader(new File("/path/to/templates/")));

5.2.2 模板缓存的使用和管理

模板缓存是FreeMarker为了提升性能，减少文件系统的I/O操作而引入的机制。当模板被首次加载后，它会被存储在内存中。后续的请求可以直接从内存中获取模板，而不需要重新读取文件。

FreeMarker提供了两种缓存控制方式：全局和模板级别的缓存控制。全局缓存控制影响所有模板，而模板级别的缓存控制允许对单个模板进行单独设置。

全局缓存控制 ：

// 设置全局缓存策略
cfg.setInMemoryCache(true);
cfg.setDefaultCacheSize(100);

模板级别缓存控制 ：

// 获取模板对象
Template template = cfg.getTemplate("my_template.ftl");

// 设置模板特定的缓存策略
template.setInMemoryCache(true);
template.setCacheSize(10);

mermaid流程图：模板加载与缓存流程

graph LR
A[开始] --> B{模板是否存在}
B -->|是| C[从缓存中获取模板]
B -->|否| D{是否启用缓存}
D -->|是| E[从文件系统加载模板并缓存]
D -->|否| F[从文件系统加载模板]
E --> G[返回模板实例]
F --> G
C --> H[返回模板实例]
H --> I[模板处理]

模板缓存的正确使用可以显著提升Web应用的响应时间，特别是在高并发的环境下。开发者需要根据应用的实际情况，合理配置缓存策略，平衡内存使用和性能需求。

6. 模板与数据模型合并生成HTML

在使用FreeMarker生成HTML页面时，关键步骤之一是将设计好的模板与相应的数据模型合并，以动态生成内容。这一过程不仅涉及到技术实现，更体现了FreeMarker强大的动态内容生成能力。

6.1 合并过程的基本原理

6.1.1 模板与数据模型合并的步骤

模板与数据模型合并的过程简单来说，就是将预定义的模板中的变量和指令替换为实际的数据模型中的值。这个过程涉及到几个核心步骤：

初始化配置 ：首先，需要创建一个 Configuration 对象，它是FreeMarker处理的核心，用于管理模板加载、处理等配置信息。
模板加载 ：通过 Configuration 对象加载模板文件，这一步会将模板文件的内容读取到内存中。
数据模型准备 ：准备一个数据模型，通常是一个包含键值对的Map或其他数据结构，这些数据将用于替换模板中的变量。
合并与渲染 ：使用 Template.process 方法，将数据模型和模板合并，并进行渲染处理，输出最终的HTML内容。

6.1.2 合并结果的输出与控制

合并后的输出可以控制在控制台、文件、或者是网络响应等多种方式。FreeMarker提供了灵活的输出选项，可以根据具体需求进行调整。

// Java示例代码展示如何合并模板与数据模型，并输出为HTML文件
Writer out = new FileWriter("output.html");
Configuration cfg = new Configuration(Configuration.VERSION_2_3_30);
cfg.setClassForTemplateLoading(this.getClass(), "/templates");
Template template = cfg.getTemplate("template.ftl");

Map<String, Object> dataModel = new HashMap<>();
dataModel.put("message", "Hello, FreeMarker!");

template.process(dataModel, out);
out.close();

在上述代码中，首先创建了输出流指向一个HTML文件，然后配置了FreeMarker并加载了模板文件，之后创建了一个数据模型，并最终通过 process 方法合并模板和数据模型，将结果输出到文件中。

6.2 实际案例分析

6.2.1 动态内容的生成与展示

假设我们需要生成一个用户列表页面，其中包含用户的姓名、年龄等信息。我们可以在模板中创建占位符，然后通过数据模型动态填充这些信息。

<!-- template.ftl 文件内容 -->
<html>
<head><title>User List</title></head>
<body>
<h1>User List</h1>
<ul>
<#list users as user>
  <li>${user.name} - ${user.age}</li>
</#list>
</ul>
</body>
</html>

// Java代码准备数据模型
Map<String, Object> dataModel = new HashMap<>();
List<Map<String, Object>> users = new ArrayList<>();
users.add(new HashMap<String, Object>(){{ put("name", "Alice"); put("age", "28"); }});
users.add(new HashMap<String, Object>(){{ put("name", "Bob"); put("age", "32"); }});
dataModel.put("users", users);

// 模板处理和输出的代码同上

上述例子展示了如何将用户数据列表动态插入到HTML模板中，生成一个用户列表页面。

6.2.2 静态页面的模板化处理

不仅仅动态内容，静态页面也可以使用FreeMarker来增强其模板化能力。举个例子，可以将一些固定的页面结构，如头部、导航栏等，设计为模板，然后在不同的页面中复用。

<!-- base.ftl 文件内容 -->
<html>
<head>
    <title>${title}</title>
    <#-- 其他静态内容 -->
</head>
<body>
    <div id="header">
        <#-- 头部内容 -->
    </div>
    <div id="content">
        ${content}
    </div>
    <div id="footer">
        <#-- 尾部内容 -->
    </div>
</body>
</html>

// Java代码展示如何使用基础模板
Map<String, Object> dataModel = new HashMap<>();
dataModel.put("title", "Welcome Page");
dataModel.put("content", "<h1>Welcome to My Website</h1>");

Template baseTemplate = cfg.getTemplate("base.ftl");
baseTemplate.process(dataModel, out);

在这个例子中， base.ftl 作为基础模板，定义了整个页面的结构，而具体的内容部分通过 content 变量动态填充。这样的设计不仅使得页面的维护变得更加容易，而且还能快速适应网站风格的变化。

通过以上章节的详细解析，我们可以看到FreeMarker在模板和数据模型合并生成HTML方面的强大能力。这一过程涉及到了模板的初始化、数据模型的准备、以及合并渲染输出等关键步骤。此外，通过实际案例的分析，进一步加深了对FreeMarker在动态内容生成、静态页面模板化方面的理解。

本文还有配套的精品资源，点击获取

烟幕缭绕

关注

15
点赞
踩
4

收藏

觉得还不错? 一键收藏
0
评论
FreeMarker模板引擎快速实现HTML生成教程

本文还有配套的精品资源，点击获取简介：FreeMarker是一个用于Java应用程序的模板引擎，可以生成包括HTML在内的多种文本格式。它通过结合模板文件和数据模型来分离视图层并实现MVC模式。本教程将引导你完成从安装FreeMarker、创建模板文件、构建数据模型，到配置、加载模板，以及最终输出HTML结果的整个过程。此外，还会介绍如何将JSON数据转换为模板引擎的数据...
复制链接

扫一扫