1. Overview
1.概述
Yet Another Report Generator (YARG) is an open source reporting library for Java, developed by Haulmont. It allows creating templates in most common formats (.doc, .docs, .xls, .xlsx, .html, .ftl, .csv) or custom text formats and filling it with data loaded by SQL, Groovy, or JSON.
Yet Another Report Generator (YARG) 是一个开源的Java报告库，由Haulmont开发。它允许创建大多数常见格式（.doc, .docs, .xls, .xlsx, .html, .ftl, .csv）或自定义文本格式的模板，并以SQL、Groovy或JSON加载的数据填充它。
In this article, we’re going to demonstrate how to use a Spring @RestController that outputs a .docx document with JSON-loaded data.
在这篇文章中，我们将演示如何使用一个Spring @RestController，输出一个带有JSON加载数据的.docx文档。
2. Setting up the Example
2.设置实例
In order to start using YARG, we need to add the following dependencies to our pom:
为了开始使用YARG，我们需要在我们的pom:中添加以下依赖项。
<repositories>
<repository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>bintray-cuba-platform-main</id>
<name>bintray</name>
<url>http://dl.bintray.com/cuba-platform/main</url>
</repository>
</repositories>
...
<dependency>
<groupId>com.haulmont.yarg</groupId>
<artifactId>yarg</artifactId>
<version>2.0.4</version>
</dependency>Next, we need a template for our data; we’re going to use a simple Letter.docx :
接下来，我们需要一个数据模板；我们将使用一个简单的Letter.docx。
${Main.title}
Hello ${Main.name},
${Main.content}
Notice how YARG uses a markup/templating language – which allows the insertion of content in the different sections. These sections are divided in terms of the data group that they belong to.
请注意YARG是如何使用一种标记/模板语言的–它允许在不同的部分插入内容。这些部分是按照它们所属的数据组来划分的。
In this example, we have a “Main” group that contains the title, name, and content of the letter.
在这个例子中，我们有一个 “主 “组，包含信件的标题、名称和内容。
These groups are called ReportBand in YARG and they are very useful for separating the different types of data you can have.
这些组在YARG中被称为ReportBand，它们对于分离你可以拥有的不同类型的数据非常有用。
3. Integrating Spring With YARG
3.将Spring与YARG相结合
One of the best ways to use a report generator is to create a service that can return the document for us.
使用报告生成器的最好方法之一是创建一个可以为我们返回文件的服务。
And so, we’ll use Spring and implement a simple @RestController that will be responsible for reading the template, getting the JSON, loading it into the document and returning a formatted .docx.
因此，我们将使用Spring并实现一个简单的@RestController，它将负责读取模板，获得JSON，将其加载到文档中并返回一个格式化的.docx.。
First, let’s create a DocumentController:
首先，让我们创建一个DocumentController。
@RestController
public class DocumentController {
@GetMapping("/generate/doc")
public void generateDocument(HttpServletResponse response)
throws IOException {
}
}
This will expose the creation of the document as a service.
这将把文件的创建暴露为一种服务。
Now we will add the loading logic for the template:
现在我们将添加模板的加载逻辑。
ReportBuilder reportBuilder = new ReportBuilder();
ReportTemplateBuilder reportTemplateBuilder = new ReportTemplateBuilder()
.documentPath("./src/main/resources/Letter.docx")
.documentName("Letter.docx")
.outputType(ReportOutputType.docx)
.readFileFromPath();
reportBuilder.template(reportTemplateBuilder.build());
The ReportBuilder class is going to be responsible for the creation of the report, grouping up the template and the data. ReportTemplateBuilder loads our previously defined Letter.docx template by specifying the path, name, and output-type of the document.
ReportBuilder类将负责报告的创建，将模板和数据分组。ReportTemplateBuilder通过指定文档的路径、名称和输出类型来加载我们之前定义的Letter.docx模板。
Then we’ll add the loaded template to the report builder.
然后，我们将添加加载的模板到报告生成器中。
Now we need to define the data that is going to be inserted in the document, this will be a Data.json file with the following:
现在我们需要定义将被插入文档的数据，这将是一个Data.json文件，内容如下。
{
"main": {
"title" : "INTRODUCTION TO YARG",
"name" : "Baeldung",
"content" : "This is the content of the letter, can be anything we like."
}
}This is a simple JSON structure with a “main” object containing the title, name, and content that our template needs.
这是一个简单的JSON结构，其中的 “main “对象包含了我们的模板需要的标题、名称和内容。
Now, let’s continue to load the data into our ReportBuilder:
现在，让我们继续将数据加载到我们的ReportBuilder。
BandBuilder bandBuilder = new BandBuilder();
String json = FileUtils.readFileToString(
new File("./src/main/resources/Data.json"));
ReportBand main = bandBuilder.name("Main")
.query("Main", "parameter=param1 $.main", "json")
.build();
reportBuilder.band(main);
Report report = reportBuilder.build();Here we define a BandBuilder in order to create a ReportBand, which is the abstraction that YARG uses for the groups of data that we defined earlier in the template document.
这里我们定义了一个BandBuilder，以便创建一个ReportBand，这是YARG对我们在模板文件中早期定义的数据组的抽象。
We can see that we define the name with the exact same section “Main”, then we use a query method to find the “Main” section and declare a parameter that will be used to find the data needed to fill the template.
我们可以看到，我们定义了具有完全相同部分的名称“Main”，然后我们使用查询方法找到 “Main “部分并声明一个参数，该参数将被用来寻找填充模板所需的数据。
It’s important to note that YARG uses JsonPath to traverse the JSON, which is why we see this “$.main” syntax.
值得注意的是，YARG使用JsonPath来遍历JSON，这就是为什么我们看到这个”$.main “语法。
Next, let’s specify in the query that the format of the data is “json”, then add the band to the report and finally, build it.
接下来，让我们在查询中指定数据的格式为 “json”，然后将带子添加到报告中，最后，构建它。
The last step is to define the Reporting object, which is responsible for inserting the data into the template and generate the final document:
最后一步是定义Reporting对象，它负责将数据插入模板并生成最终文件。
Reporting reporting = new Reporting();
reporting.setFormatterFactory(new DefaultFormatterFactory());
reporting.setLoaderFactory(
new DefaultLoaderFactory().setJsonDataLoader(new JsonDataLoader()));
response.setContentType(
"application/vnd.openxmlformats-officedocument.wordprocessingml.document");
reporting.runReport(
new RunParams(report).param("param1", json),
response.getOutputStream());We use a DefaultFormatterFactory that supports the common formats listed at the beginning of the article. After that, we set the JsonDataLoader that is going to be responsible for parsing the JSON.
我们使用一个DefaultFormatterFactory，它支持文章开头列出的常见格式。之后，我们设置JsonDataLoader，它将负责解析JSON。
In the final step, we set the appropriate content type for the .docx format and run the report. This will wire up the JSON data and insert it into the template outputting the result into the response output stream.
在最后一步，我们为.docx格式设置适当的内容类型并运行报告。这将连接JSON数据并将其插入模板，将结果输出到响应输出流。
Now we can access the /generate/doc URL to download the document and we shall see the following result in our generated .docx:
现在我们可以访问/generate/doc URL来下载文件，我们将在我们生成的.docx中看到以下结果。
4. Conclusion
4.结论
In this article, we showed how we can easily integrate YARG with Spring and use its powerful API to create documents in a simple way.
在这篇文章中，我们展示了如何轻松地将YARG与Spring集成，并使用其强大的API以简单的方式创建文档。
We used JSON as the data input, but Groovy and SQL are also supported.
我们使用JSON作为数据输入，但也支持Groovy和SQL。
If you want to learn more about it you can find the documentation here.
如果你想了解更多关于它的信息，你可以找到文件这里。
And as always, you can find the complete example over on GitHub.
和往常一样，你可以在GitHub上找到完整的例子。