Enabling the Content Tests Module

These are the steps to enable this module in your custom Broadleaf Commerce project. These steps are based on projects that are similar to the Broadleaf Commerce demo application which contains a core, site, and admin project which are all contained in a "parent project".

Prerequisites

This module depends on the Scheduled Jobs and Events module. Perform these steps after that module has been installed.

Steps

Step 1. Add the following to the dependency management section of your parent pom.xml:
The parent pom is the one located in the root directory of the Broadleaf Commerce project.

    <dependency>
        <groupId>com.broadleafcommerce</groupId>
        <artifactId>broadleaf-contenttests</artifactId>
        <version>1.0.0-GA</version>
        <type>jar</type>
        <scope>compile</scope>
    </dependency>                

Note: Content Tests also requires the Enterprise Common and Jobs and Events modules

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

    <dependency>
        <groupId>com.broadleafcommerce</groupId>
        <artifactId>broadleaf-contenttests</artifactId>
    </dependency>

Step 3. Update the patchConfigLocation files in your admin/web.xml file:

    classpath:/bl-contentTest-applicationContext.xml
    classpath:/bl-contentTest-admin-applicationContext.xml 

Note: This line should go before the classpath:/applicationContext.xml line

Step 4. Update the contextConfigLocation for DispatcherServlet files in your admin/web.xml file:

    classpath:/bl-contentTest-admin-applicationContext-servlet.xml             

Note: This line should go just before the /WEB-INF/applicationContext-servlet-admin.xml line

Step 5. Update the patchConfigLocation files in your site/web.xml file:

    classpath:/bl-contentTest-applicationContext.xml

Note: This line should go before the classpath:/applicationContext.xml line

Step 6. Update the contextConfigLocation for DispatcherServlet files in your site/web.xml file:

    classpath:/bl-contentTest-applicationContext-servlet.xml

Note: This line should go just before the /WEB-INF/applicationContext-servlet.xml line

Step 7. Update the blPostSecurityFilterChain in the site/src/main/webapp/WEB-INF/applicationContext-filter.xml file.

After the security filter runs, the ContentTest filter will run to see if that user and request should be involved in a test.

Add ...

    blContentTestRequestFilter

as the last entry in the list.

Note: Ensure that the prior entry has no whitespace after the "," that was added.

Template Changes

Add the following code to the template that renders your HTML head tag. (head.html in the Broadleaf demo site).

This code should appear just before the call to Google Universal Analytics, if applicable. If Google Tag Manager is used on this site, then the location of this tag is irrelevant.

Note: Having a duplicate Google Universal Analytics tag in addition to a Google Tag Manager Universal Analytics is not recommended.

    <blc:google_experiments execute="true" />

You will also need to include the content tests Javascript file. This file allows ajax views that are involved in content tests to report the views back to Google.

To enhance the demo site, you would include the content tests JavaScript file as part of the JavaScript bundle in the footer.html.

<blc:bundle name="heatclinic.js" 
    mapping-prefix="/js/"
    files="BLC.js,
        contentTestsClient.js,// <--- THIS IS THE FILE THAT WAS ADDED
        heatClinic.js,
        cartOperations.js,
        checkoutOperations.js,
        globalOnReady.js,
        manageAccountOperations.js,
        reviewOperations.js" />

You'll need to include contentTestClient.js as appropriate for your installation. If you are not using the BLC.ajax function to make ajax calls, then you'll need to examine BLC.js and contentTestsClient.js and make similar modifications to your code if you want to allow experiments on views delivered via ajax.

Data Changes

Admin Security Changes

To create the Content Tests menu section in the Broadleaf admin, you will need to load new permissions. The recommended changes are located in the following files:

/config/bc/sql/load_content_tests_admin_security.sql

Note: In development, you can automatically load this SQL files by adding it to the blPU.hibernate.hbm2ddl.import_files property in the development-shared.properties file.

Load Content Test Data

The Content Test module has two required data elements. The goals for content tests are stored in the table named BLC_CONTENT_TEST_GOAL.
For sites that want to maintain the Google integration properties in the admin (recommended), the file also adds in the
appropriate records to the BLC_SYSTEM_PROPERTY table.

You can load the following file to load the Goal list and System Property Settings.

/config/bc/sql/load_content_tests_data.sql

Some implementations may wish to customize this SQL to match their Google Analytics Configuration more closely. The table contains a column named REFERENCE which represents the way the Google Experiments API requires Broadleaf to communicate the Goals for the test. The name column can be changed to other values as appropriate for your installation including specific names that match the goals you have setup in Google Analytics.

Note: In development, you can automatically load this SQL files by adding it to the blPU.hibernate.hbm2ddl.import_files property in the development-shared.properties file.

Load Scheduled Job Data

The Content Test module needs to periodically poll Google Experiments to see which variation is winning. Broadleaf uses this data and an algorithm prescribed by Google to ensure that users see the most appropriate variation based on the stage of the test.

To configure the job, you'll need to run the following file.

/config/bc/sql/load_content_tests_required_jobs.sql

Google reports that experiment data is updated three times a day. This job runs every hour by default and can be configured to run on a different schedule. This job will produce little to no additional load on your system.

Note: In development, you can automatically load this SQL files by adding it to the blEventPU.hibernate.hbm2ddl.import_files property in the development-shared.properties file.

Schema Changes

If you are allowing hibernate to create and modify your tables, this will be done automatically when you restart with the new configuration settings.

Otherwise, you will need to run the file docs/load_content_tests_tables.sql in order to create the necessary tables for content tests.