Mugo Web main content.

A simple Sass integration for eZ Publish

By: Philipp Kamps | June 14, 2017 | eZ Publish add-ons, eZ Publish development tips, and Productivity tools

Working with CSS preprocessors like Sass or Less is much more fun than working with pure CSS. Here's a simple shell script to integrate Sass into your eZ Publish project.

For most of our eZ Publish projects, we use CSS preprocessors or entire front-end frameworks like bootstrap or foundation. If image sprites are required, we use Compass.

This blog post has a much smaller scope: it presents a shell script that will find and compile all of your Sass source files (.scss) in all your eZ Publish extensions. You can run the script on your local development machine or vagrant box. Here are a few options:

  1. On every update in one of your Sass sources, manually run the script:
  1. Run the script in the background and have it monitor for updates automatically. The output will be logged to var/log/sass.log
./bin/shell/ -w -l
  1. If your development IDE (for example PHPStorm) allows you to configure a 'File watcher', you can specify this script and the IDE will execute it after an update in a Sass source file.

If you work with a development environment and a production environment (and maybe even a staging/testing environment), we recommend you run this script only in the development environments and then commit the resulting CSS files into your code repository. Do not run the CSS preprocessors on stage or production; it makes the deployment more difficult and risky. Here is the script:


### About this script ###
# This script is compiling scss files in your extensions. It expects the *.scss files
# in extension/<ext name>/design/<design name>/scss/*.scss.
# It will then place the CSS files into the ezp stylesheets folders.
# Make sure you call this script from the ezp root directory.
# This script expects that you have the 'sass' command line tool installed.

### script parameters ###
# -w watch the scss directories - otherwise it only run once
# -l log the output to var/log/sass.log
# -c resulting CSS is compressed - for production use
# -m write the sourcemap files - easier to debug the scss files
# -h help

style='--style expanded'

while getopts ':wlchmp:' OPTION ; do
case "$OPTION" in
w) optWatch='--watch';;
l) toLogFile='>>var/log/sass.log';;
c) style='--style compressed';;
m) sourceMap='--sourcemap=auto';;
h) echo -e "OPTIONS:\n-w watch the scss directories - otherwise it only run once\n-l log the output to var/log/sass.log\n-c resulting CSS is compressed - for production use\n-m write the sourcemap files - easier to debug the scss files\n-h help\n"; exit;;
#p) echo "Backup path is: $OPTARG";; #keep as an example
*) echo "Unknown parameter"

# Find scss folders in the extension directory
altDir=( $( find . -maxdepth 5 -type d | grep "/extension/.*/.*/.*/scss$" ) )

# build paths option
for ((i=0; i < ${#altDir[*]} ; i++))
path="$path ${altDir[$i]}:${altDir[$i]/scss/stylesheets}"

command="sass --cache-location ~/.sass-cache ${style} ${sourceMap} ${optWatch} ${path} ${toLogFile}"

#echo $command
eval $command

We recommend you place the script into the directory 'bin/shell' and then run it from your eZ Publish root directory:

./bin/shell/ -h

Happy front-end coding.