Theme Variables

Theme variables are a way for authors to allow certain elements of their themes to be configured through the Broadleaf admin tool. We provide access to these attributes in HTML, CSS, JS, and Java files.

A ThemeDefinition provides a List<FieldGroup>, and each FieldGroup contains a List<FieldDefinition>. By creating the appropriate database records that match to these entities, you will be able to present grouped fields to the user. The Broadleaf private demo showcases a few different types of attributes.

HTML Files

The Theme module provides a Thymeleaf Variable Expression object and configures it to be aliased to the #theme expression. Let's take a look at an example assuming that there is a boolean theme variable called showFlags and we want to use it to control whether or not the flags banner at the top of the Heat Clinic renders:

<div th:if="${#theme.attr('showFlags') == null or #theme.attr('showFlags')}">
    ...
</div>

Here, you can see that we're specifying that if the value of showFlags is unset or if it's set to true, we will render the div.

CSS Files

There is no inherent way to assign values to variables in CSS, but Broadleaf has added a pre-processing step that allows you to perform variable substitution. Assuming that there was a theme variable called headerColor, we could utilize this value in CSS as follows:

#myHeaderElement {
    background-color: __headerColor__;
}

As you can see, the syntax that should be used in CSS files is the variable name with 2 underscores on each side. Broadleaf will find these matches and replace it with the appropriate value for the current ThemeConfiguration.

Additionally, the author of a CSS file is able to provide a default value to be used for variables. On the very first match for an attribute, you're able to specify a default value by using an equals sign and the default value. For example:

/* =======================================
   Theme variables:
     headerColor : __headerColor=#E40037__
   ======================================= */

We typically recommend assigning a default value for all variables that will be used in CSS and putting them in a comment at the top of the file. This is a good way to ensure you will match on the default value appropriately. It also makes it easy for other users to see what parts of the CSS file are dynamic and have a corresponding field configured in the database.

JS Files

If you are including the blc-theme.js file in your JavaScript bundle (or directly if you are not using bundles), you will automatically have access to all theme variables via the BLC.theme.vars object.

console.log(BLC.theme.vars.headerColor)
>>> "#E40037"

Java Files

We can leverage the same class that provides access to these variables in Thymeleaf files in Java as well. Simply inject the Spring bean blThemeVariableExpression into your class and then call the attr() method.

@Resource(name = "blThemeVariableExpression")
protected ThemeVariableExpression theme;

public void myMethod() {
    System.out.println(theme.attr("headerColor"));
}

>>> "#E40037"