Module Installation

Steps to enable this module in your custom Broadleaf Commerce project

Steps

Step 1 Create a folder called default-theme inside of site/src/main/webapp/WEB-INF

Step 2 Move the css, fonts, img, js, and template folders inside of the new default-theme folder.

When using themes, the typical project structure for site changes slightly. Basically, we need to get all of the templates/css/images/js folders under a parent theme folder so that we can dynamically select themes.

Step 3 Pull this dependency into your core/pom.xml:

<dependency>
   <groupId>org.broadleafcommerce</groupId>
   <artifactId>broadleaf-theme</artifactId>
</dependency>

This assumes that you are using the Broadleaf BOM that pins all version information. If not, you will need to also add a <version> qualifier

Step 4 In site/src/main/webapp/WEB-INF/applicationContext-servlet.xml, delete the following lines:

<mvc:resources order="-10" location="/img/, classpath:/common_style/img/" mapping="/img/**" />
<mvc:resources order="-10" location="/fonts/, classpath:/common_style/fonts/" mapping="/fonts/**" />

and add in these to the SimpleUrlHandlerMapping bean:

<prop key="/img/**">blImageResources</prop>
<prop key="/fonts/**">blFontResources</prop>

Step 5 In site/src/main/webapp/WEB-INF/applicationContext.xml, delete the following beans:

<bean id="jsLocations" ... >
<bean id="cssLocations" ... >
<bean id="blJsResources" ... >
<bean id="blCssResources" ... >

along with the two LateStageMergeBeanPostProcessor beans that are defined below them.

After that, add in the following lines:

<bean id="resourceBase" abstract="true" class="com.broadleafcommerce.theme.web.resource.ThemeResourceHttpRequestHandler">
    <property name="themesBaseDirectory" value="/WEB-INF/" />
</bean>

<bean id="blJsResources" parent="resourceBase">
    <property name="locations" ref="blJsLocations"/>
    <property name="themeDirectory" value="/js/" />
    <property name="handlers" ref="blJsHandlers" />
</bean>

<bean id="blCssResources" parent="resourceBase">
    <property name="locations" ref="blCssLocations"/>
    <property name="themeDirectory" value="/css/" />
    <property name="handlers" ref="blCssHandlers" />
</bean>

<bean id="blImageResources" parent="resourceBase">
    <property name="locations" ref="blImageLocations"/>
    <property name="themeDirectory" value="/img/" />
</bean>

<bean id="blFontResources" parent="resourceBase">
    <property name="locations" ref="blFontLocations"/>
    <property name="themeDirectory" value = "/fonts/" />
</bean>

Step 6 The following subfolder locations have been added to the configuration via the blSubfolderResourceLocations bean:

js/
css/
img/

This will allow resources found under themed folders to be versioned correctly. If any additional subfolders are added within a theme folder such as /js/core/, etc., they will need to be added to the blSubfolderResourceLocations list. To do so add the following configuration in site/src/main/webapp/WEB-INF/applicationContext.xml:

    <bean id="customSubfolderResourceLocations" class="org.springframework.beans.factory.config.ListFactoryBean">
        <property name="sourceList">
            <list>
                <value>js/core/</value>
            </list>
        </property>
    </bean>

    <bean class="org.broadleafcommerce.common.extensibility.context.merge.LateStageMergeBeanPostProcessor">
        <property name="collectionRef" value="customSubfolderResourceLocations"/>
        <property name="targetRef" value="blSubfolderResourceLocations"/>
    </bean>

Step 7 In order to set up theme parent hierarchy, add the following bean to your frontend or servlet configuration:

@Bean
public ThemeParentTemplateResolver blThemeParentTemplateResolver() {
    ThemeParentTemplateResolver templateResolver = new ThemeParentTemplateResolver();
    templateResolver.setPrefix("classpath:themes/");
    templateResolver.setSuffix(".html");
    templateResolver.setTemplateFolder(templateFolder);
    templateResolver.setTemplateMode(BroadleafTemplateMode.HTML5);
    templateResolver.setCacheable(cacheTemplate);
    templateResolver.setCacheTTLMs(cacheTTL);
    templateResolver.setOrder(275);
    return templateResolver;
}

Demo Site Changes (optional)

Step 1 If you would like access to the theme variables through JavaScript, you will want to add blc-theme.js to list of JavaScript files that you will be using. Typically, this is configured through footer.html, but it will be application specific if you are not basing your project on the Heat Clinic.

Step 2 Modify site/src/main/webapp/WEB-INF/default-theme/css/style.css to take advantage of the theme variable replacement.
- Add the following line to the comment block at the top of the file:

__headerColor=blue__
- Replace the border-top definition in the header element:

border-top: 15px solid __headerColor__;
- Replace the background-color definition in the #header_content #cart_info element:

background-color: __headerColor__;

Data Changes

Schema Changes

To add all of the necessary database tables and columns for this module, please follow the Liquibase update documentation.

Admin Security Changes

The data in the following SQL file is required to establish Admin sections and permissions for this module:

classpath:/config/bc/sql/load_theme_admin_security.sql

This file is automatically included if you have set blPU.hibernate.hbm2ddl.auto=create and you have not set import.sql.enabled=false in your properties files. If you are not using Hibernate's auto DDL process and are using Liquibase, you can add a new changeSet that references this file:

<?xml version="1.1" encoding="UTF-8" standalone="no"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.5.xsd">
    <changeSet author="broadleaf" id="some-unique-id">
        <sqlFile path="config/bc/sql/load_theme_admin_security.sql" encoding="utf8" stripComments="true" />
    </changeSet>
</databaseChangeLog>

Finally, you can unpack the downloaded .jar file and look at the files in the config/bc/sql folder to execute this sql manually.

Demo Data

If you want to augment the Heat Clinic demo with some theme configurations, you can utilize the /config/bc/sql/samples/load_theme_demo_data.sql file provided with the theme module.