Theme Files

The Broadleaf Theme module adds support for editing HTML, CSS, and JS files directly through the admin. Furthermore, it works alongside the Enterprise module, allowing you to preview your file changes in a sandbox environment before pushing them live. It's a great way to allow designers to tweak things without requiring an application redeploy.

Editing existing files

Files are not presented in the admin UI based on what exists on the file system. Instead, we rely on database records to control which files are editable. However, when creating new files, if the path given matches the path to a file on disk for the current theme, the system will automatically populate the contents of that file from the file system. In combination with this, restricting the add permission for new files is one way to lock down which files are editable through the admin.

When files are saved through the admin tool, the template HTML is persisted not on the file system, but in the database. This provides all application servers a unified point to search for overridden templates and prevents the need to modify the deployed artifact in production.

As the master source for a template is the database, it's important to consider synchronization with your codebase, especially during new deployments. The recommended approach is to take the modified version of the templates from the database and check those changes into your version control system. Then, once the new version of the application has been deployed, you can replace the contents of the theme file record in the database with null, which will indicate to the system that it should read the file from the file system.

Product and Category templates

The Theme module weaves in a field to both Product and Category that is a reference to a ThemeFile. If set, the system will use the given ThemeFile as a template to render that particular product or category.