Template Resolution

Overview

The typical return value from Spring MVC controllers is a String that corresponds to a template path. Normally, this corresponds to one distinct file on the file system. However, when the theme module is in place, the specified template needs to come from the currently active theme, which requires modifying the resource path to include the theme folder. Furthermore, if a given template has been modified via the admin, it's possible that the template needs to come from the database instead.

File system resolution

First, let's take a look at the bean utilized for the file system based resolution (in bl-theme-base-applicationContext.xml):

<bean id="blWebTemplateResolver" class="org.broadleafcommerce.common.web.BroadleafThymeleafServletContextTemplateResolver">
    <property name="prefix" value="/WEB-INF/" />
    <property name="templateFolder" value="${theme.templates.folder}" />
    <property name="suffix" value=".html" />
    <property name="templateMode" value="HTML5" />
    <property name="cacheable" value="false"/>
    <property name="characterEncoding" value="UTF-8" />
    <property name="order" value="200"/>         
</bean>

The BroadleafThymeleafServletContextTemplateResolver class understands how to resolve a path to a file based on some fixed setup data as well as the current theme. First, we need to resolve the correct prefix, which is typically /WEB-INF/. This is the path, relative to src/main/webapp, where all of your theme folders live. Inside each folder, you will typically have different assets, such as CSS, JS, and HTML. The HTML utilized for templates is the name of the folder given by the templateFolder property. By default, this property resolves to templates/.

Once that is configured, the template resolver will take care of the rest. If the value returned from a controller is catalog/product and the current theme's path property is default-theme, the resolved file will be located at /WEB-INF/default-theme/templates/catalog/product.html.

Database resolution

Second, we'll inspect the configuration for the database template resolver (in bl-framework-web-applicationContext.xml):

<bean id="blWebDatabaseTemplateResolver" class="org.broadleafcommerce.core.web.resolver.DatabaseTemplateResolver">
    <property name="resourceResolver" ref="blDatabaseResourceResolver" />
    <property name="templateMode" value="HTML5" />
    <property name="characterEncoding" value="UTF-8" />
    <property name="cacheable" value="${cache.page.templates}"/>
    <property name="cacheTTLMs" value="${cache.page.templates.ttl}" />
    <property name="order" value="100"/>         
</bean>  

As you can see, there are no real configuration elements necessary for the database template resolver. It comes pre-configured with a higher priority than other out-of-box resolvers, and specifies a reference to the blDatabaseResourceResolver bean. The theme module then hooks into the execution of this class via the ThemeDatabaseResourceResolverExtensionHandler, which is responsible for streaming the contents column from the database to Thymeleaf.

See Also: File Resolution