Usage on framework

In this page, we explain ways that integrate with an application framework.

1. Spring Boot

1.1. Basic configuration

If you are using the mybatis-spring-boot-starter(Spring Boot), you can configure using configuration properties(properties or yaml file) as follow:

src/main/resources/application.properties

mybatis.configuration.default-scripting-language=org.mybatis.scripting.thymeleaf.ThymeleafLanguageDriver

# Workaround for https://github.com/spring-projects/spring-boot/issues/16079
# Adding if need (If you use the Spring Boot 2.1.4+, this configuration not need)
spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.thymeleaf.ThymeleafAutoConfiguration

src/main/resources/application.yml

mybatis:
  configuration:
    default-scripting-language: org.mybatis.scripting.thymeleaf.ThymeleafLanguageDriver

# Workaround for https://github.com/spring-projects/spring-boot/issues/16079
# Adding if need (If you use the Spring Boot 2.1.4+, this configuration not need)
spring:
  autoconfigure:
    exclude: org.springframework.boot.autoconfigure.thymeleaf.ThymeleafAutoConfiguration

1.2. Customizing a configuration

You can customize a configuration using mybatis-thymeleaf.properties. Furthermore, you can customize using the Spring Boot configuration properties instead of mybatis-thymeleaf.properties as follow:

src/main/resources/application.properties

mybatis.configuration-properties.use-2way=false # (1)
mybatis.configuration-properties.template-file.cache-ttl=3600000

src/main/resources/application.yml

mybatis:
  configuration-properties:
    use-2way: false # (1)
    template-file.cache-ttl: 3600000

Configuration class

@Bean
ConfigurationCustomizer mybatisConfigurationCustomizer(MyBatisProperties properties) {
  return configuration -> {
    configuration.getLanguageRegistry().register(new ThymeleafLanguageDriver(
      ThymeleafLanguageDriverConfig.newInstance(properties.getConfigurationProperties()))); // (2)
    configuration.setDefaultScriptingLanguage(ThymeleafLanguageDriver.class); // (3)
  };
}

1. Specify the configuration property of mybatis.configuration.configuration-properties.{property key} format

2. Create a ThymeleafLanguageDriverConfig instance using Properties object that holds values of mybatis.configuration.configuration-properties.{property key} and register a ThymeleafLanguageDriver correspond with it.

3. Set the ThymeleafLanguageDriver class as default scripting language driver at after registering a ThymeleafLanguageDriver instance instead of Spring Boot configuration properties (Very Important!!)

1.3. Full customizing a configuration

Also, you can fully customize a template engine using the ConfigurationCustomizer.

Configuration class

@Bean
ConfigurationCustomizer mybatisConfigurationCustomizer() {
  return configuration -> {
    TemplateEngine templateEngine = new TemplateEngine(); // (1)
    templateEngine.addDialect(new MyBatisDialect());
    templateEngine.setEngineContextFactory(new MyBatisIntegratingEngineContextFactory(
      targetTemplateEngine.getEngineContextFactory()));
    // ...
    configuration.getLanguageRegistry().register(new ThymeleafLanguageDriver(templateEngine)); // (2)
    configuration.setDefaultScriptingLanguage(ThymeleafLanguageDriver.class); // (3)
  };
}

1. Create an instance of class that implements org.thymeleaf.ITemplateEngine

2. Register an instance of ThymeleafLanguageDriver that associate with user-defined template engine instance

3. Set the ThymeleafLanguageDriver class as default scripting language driver at after registering a ThymeleafLanguageDriver instance instead of Spring Boot configuration properties (Very Important!!)