Template configurations

“模板配置”指的是Configuration(Configuration.setTemplateConfigurations(...))的template_configurations设置。此设置使您可以覆盖来自通用Configuration对象的各个设置，具体取决于模板的名称(路径)。

但是，重要的是要了解，此设置仅在使用Configuration.getTemplate(...)模板时才有效，而在直接使用Template构造函数创建模板时无效。在这种情况下，由您来调用此机制(请参见TemplateCache源代码作为示例)。

您将使用以下类型的对象来声明模板配置规则：

• TemplateConfiguration -s：这些存储您要应用的实际设置分配。例如，此TemplateConfiguration将设置匹配模板的编码和输出格式(并保留其所有其他设置)：

TemplateConfiguration tcUTF8XML = new TemplateConfiguration();
tc.setEncoding("utf-8");
tc.setOutputFormat(XMLOutputFormat.INSTANCE);

• TemplateSourceMatcher(抽象)子类：这些子类定义了一个规则，这些规则根据模板的源名称(它们的源路径；如Template.getSourceName())以及可能与其他TemplateLoader相关的属性来匹配模板。例如，new FileExtensionMatcher("xml")匹配文件 extensions 为xml的模板。请参阅 Java API 文档中的所有子类。

• TemplateConfigurationFactory -es：这是将TemplateConfiguration -s 和TemplateSourceMatcher -s 连接在一起的东西。这是template_configurations设置的 Java 类型。有关更多信息，请参见下面的示例。

Example 1

此设置将前面的两个示例对象与ConditionalTemplateConfigurationFactory结合在一起，使所有带有xmlextensions 的模板都获得 UTF-8 编码和 XML 输出格式：

cfg.setTemplateConfigurations(
        new ConditionalTemplateConfigurationFactory(
                new FileExtensionMatcher("xml"),
                tcUTF8XML));

如果您无权访问配置的 Java 代码，而只能访问 Java *.properties文件或其他类型的字符串-字符串键值对(\ -s 由 Java 属性文件格式指定，则同样的配置也是可行的对于多行值，请在其他地方省略)：

templateConfigurations = \
    ConditionalTemplateConfigurationFactory( \
        FileExtensionMatcher("xml"), \
        TemplateConfiguration( \
            encoding = "utf-8", \
            outputFormat = XMLOutputFormat() \
        ) \
    )

Example 2

假设您只需要专门处理mail目录中的模板，其他模板可以使用来自共享Configuration单例的设置。模板的名称必须包含".subject."或".body."。主题模板必须具有plainText输出格式，而主体模板必须具有HTML输出格式。所以我们必须在这里做出选择，那就是您需要FirstMatchTemplateConfigurationFactory的时候。

假设cfg存储了共享的Configurationsingleton，则可以这样设置：

TemplateConfiguration tcSubject = new TemplateConfiguration();
tcSubject.setOutputFormat(PlainTextOutputFormat.INSTANCE);
        
TemplateConfiguration tcBody = new TemplateConfiguration();
tcBody.setOutputFormat(HTMLOutputFormat.INSTANCE);

cfg.setTemplateConfigurations(
        new ConditionalTemplateConfigurationFactory(
                new PathGlobMatcher("mail/**"),
                new FirstMatchTemplateConfigurationFactory(
                        new ConditionalTemplateConfigurationFactory(
                                new FileNameGlobMatcher("*.subject.*"),
                                tcSubject),
                        new ConditionalTemplateConfigurationFactory(
                                new FileNameGlobMatcher("*.body.*"),
                                tcBody)
                        )
                        .noMatchErrorDetails(
                                "Mail template names must contain \".subject.\" or \".body.\"!")
                ));

使用 Java *.properties文件或其他类型的字符串-字符串键值对的等效配置(\ -s 仅由 Java Properties 文件格式规定，因此在其他地方省略它们)：

templateConfigurations = \
    ConditionalTemplateConfigurationFactory( \
        PathGlobMatcher("mail/**"), \
        FirstMatchTemplateConfigurationFactory( \
            ConditionalTemplateConfigurationFactory( \
                FileNameGlobMatcher("*.subject.*"), \
                TemplateConfiguration(outputFormat = PlainTextOutputFormat()) \
            ), \
            ConditionalTemplateConfigurationFactory( \
                FileNameGlobMatcher("*.body.*"), \
                TemplateConfiguration(outputFormat = HTMLOutputFormat()) \
            ), \
            noMatchErrorDetails = 'Mail template names must contain ".subject." or ".body."!' \
        ) \
    )

Example 3

假设您希望与应用程序中共享的Configuration设置存在以下差异：

• 名称包含".stats."的所有模板均应使用 ISO 日期/时间格式和 UTC 时区

• mail目录中的所有模板均应使用 UTF-8 编码

• extensions 为xml的模板应使用 XML output_format，extensions 为html或htm的模板应使用 HTML 输出格式。对于其他模板，共享的Configuration可以指示output_format。

这里我们有 3 个独立的关注点，可能有多个(或没有)适用于模板；那就是您需要MergingTemplateConfigurationFactory的时候。在上述与文件 extensions 相关的规则中，您具有互斥的选择，因此需要FirstMatchTemplateConfigurationFactory，但这一次也不允许选择。这是源代码，假设cfg存储共享的Configuration实例：

TemplateConfiguration tcStats = new TemplateConfiguration();
tcStats.setDateTimeFormat("iso");
tcStats.setDateFormat("iso");
tcStats.setTimeFormat("iso");
tcStats.setTimeZone(DateUtil.UTC);

TemplateConfiguration tcMail = new TemplateConfiguration();
tcMail.setEncoding("utf-8");

TemplateConfiguration tcHTML = new TemplateConfiguration();
tcHTML.setOutputFormat(HTMLOutputFormat.INSTANCE);

TemplateConfiguration tcXML = new TemplateConfiguration();
tcXML.setOutputFormat(XMLOutputFormat.INSTANCE);

cfg.setTemplateConfigurations(
        new MergingTemplateConfigurationFactory(
                new ConditionalTemplateConfigurationFactory(
                        new FileNameGlobMatcher("*.stats.*"),
                        tcStats),
                new ConditionalTemplateConfigurationFactory(
                        new PathGlobMatcher("mail/**"),
                        tcMail),
                new FirstMatchTemplateConfigurationFactory(
                        new ConditionalTemplateConfigurationFactory(
                                new FileExtensionMatcher("xml"),
                                tcXML),
                        new ConditionalTemplateConfigurationFactory(
                                new OrMatcher(
                                        new FileExtensionMatcher("html"),
                                        new FileExtensionMatcher("htm")),
                                tcHTML)
                ).allowNoMatch(true)
        )
);

使用 Java *.properties文件或其他类型的字符串-字符串键值对的等效配置(\ -s 仅由 Java Properties 文件格式规定)：

templateConfigurations = \
    MergingTemplateConfigurationFactory( \
        ConditionalTemplateConfigurationFactory( \
            FileNameGlobMatcher("*.stats.*"), \
            TemplateConfiguration( \
                dateTimeFormat = "iso", \
                dateFormat = "iso", \
                timeFormat = "iso", \
                timeZone = TimeZone("UTC") \
            ) \
        ), \
        ConditionalTemplateConfigurationFactory( \
            PathGlobMatcher("mail/**"), \
            TemplateConfiguration(encoding = "utf-8") \
        ), \
        FirstMatchTemplateConfigurationFactory( \
            ConditionalTemplateConfigurationFactory( \
                FileExtensionMatcher("xml"), \
                TemplateConfiguration(outputFormat = XMLOutputFormat()) \
            ), \
            ConditionalTemplateConfigurationFactory( \
                OrMatcher( \
                    FileExtensionMatcher("html"), \
                    FileExtensionMatcher("htm") \
                ), \
                TemplateConfiguration(outputFormat = HTMLOutputFormat()) \
            ), \
            allowNoMatch = true \
        ) \
    )