Server Side Compiling of Sass Files - Documentation topics on: compiling,css,less,preprocessor,sass,server side,.

Server Side Compiling of Sass Files

dotCMS offers server side editing/compiling of Sass files “on the fly.” Sass is a modern CSS pre-processor which extends the CSS language, allows for additional features (such as variables, mixins and functions), and allows CSS to be more maintainable, themable and extendible.


Important:

By default, dotCMS is configured to use the libsass compiler. However the libsass compiler must be installed as a system library on your system, so in order to use Sass files in dotCMS you must first do one of the following:

  • Install (or ensure that the libsass compiler is already installed) on your dotCMS server, or
  • Configure dotCMS to use the legacy (deprecated) jruby-based Sass compiler.

For more information, please see below.


Why Sass?

The Sass pre-processor is actively developed, widely adopted (including adoption by Bootstrap and other major frameworks), provides excellent compatibility with multiple browsers and CSS versions, and has extensive documentation and a well established community. For more information about Sass, please see the sass-lang.com site.

Advantages of Uploading Sass Files to dotCMS

There are a number of advantages to uploading and using your Sass files in dotCMS:

  • Your Sass files may be edited in the dotCMS back-end.
  • Files are compiled instantly when accessed.
  • Files are minified on compile to reduce space and network bandwidth.
  • Compiled CSS code is intelligently cached to minimize recompiles and improve performance.
  • A revertable change and workflow history is kept on every Sass file.
  • The cache automatically refreshes each time a file is changed.

How to Reference Sass files in dotCMS

Enabling Sass

dotCMS supports two versions of the Sass compiler: libsass and a legacy jruby-based compiler. The default Sass compiler is libsass.

Unfortunately the libsass compiler is not included with the dotCMS distribution, and can not be since it must be installed as a system library on your system. Therefore to use Sass in dotCMS you must do one of the following:

For more information on why libsass is used as the default Sass compiler, please see Sass Compiler Selection below.

Referencing Sass files in Templates

When properly referenced in your Template code, Sass files are compiled server side “on the fly” and are cached. Sass files can be uploaded and edited via webDAV or from the Site Browser in the dotCMS backend. Each saved change to the file is stored in the file change history and triggers an update of the cache.

Since Sass files are not regognized by some older browsers, dotCMS uses a special notation to access Sass files which “disguises” your Sass files as regular CSS files. However when the browser makes the request to load the file, dotCMS recognizes the special notation, locates the appropriate Sass file, compiles it, and then sends the compiled CSS to the user's browser.

Example

To reference a Sass file from within your Template, you reference the .scss file and have it server side compile, by referring to your sass files (in your template code), using the file extension .dotsass, (instead of the normal .scss extension for Sass files).

For example, given the following Sass files:

styling/bootstrap.scss
styling/template.scss

You would use the following notation in your Template code:

/styling/bootstrap.dotsass
/styling/template.dotsass

Referencing Sass files in Themes

Sass files can be uploaded directly to a dotCMS Theme. The notation to access a Sass file from a Theme is the same as when accessing the files from a Template; however when referencing Sass files from a Theme, the $dotTheme.path variable should be used in the pathing references to the file.

Example

Given the following files within your Theme folder:

bootstrap.scss
fonts/font-awesome.scss
styling/theme.scss

You would reference the files within your Theme using the following notation:

${dotTheme.path}/bootstrap.dotsass
${dotTheme.path}/fonts/font-awesome.dotsass
${dotTheme.path}/styling/theme.dotsass

Sample Sass Files

You may download sample Themes using various frameworks from the dotCMS website. Each downloadable Theme includes pre-built Sass files which you can use as examples to modify, or to create your own Sass files for your own dotCMS Theme.

Importing Other Files into Sass Files

You may use the @import command to load the contents of another files into a Sass file.

Import File Names

By convention, included Sass files often begin with an underscore (_). Therfore, when you import a file using the @import command, dotCMS will attempt to find the file using two different file names:

  1. dotCMS will first search for the file using the exact name you've specified in the @import statement.
  2. If the file can not be found, dotCMS will append an underscore (_) to the file name and attempt to find it again.

For example, if you specify a line of @import "styling/mixins", dotCMS will first look for the file “mixins.scss” in the “styling” folder; if a file with that name can't be found, dotCMS will then look for the file “_mixins.scss” in the same “styling” folder. dotCMS will import the first file with a matching name it finds.

Import File Paths

The path to the import file is specified from either the root of the dotCMS site browser tree (for local files), or from the site the file is located on](#ImportRemote) (for remote files).

Local Paths

If the file being imported resides on the same host as the file making the import call, then a relative path can be used, as follows:

@import "/path_to_file/file_name.scss";
Remote Paths

If the file being imported resides on another host on the same dotCMS instance, then the import path must begin with a double slash and the name of the host where the file is located (e.g. //host.domain.com), as follows:

@import "//host_name/path_to_file/file_name.scss";

Caution: Sass files residing on other servers (outside the existing dotCMS instance) may NOT be imported via an http call.

Managing Sass Files

Caching

Any time a Sass file is changed, the cache reloads and recompiles the file, ensuring that the cache stays in sync with file updates whether they are made through editing the file directly in dotCMS or thru a Webdav connection. dotCMS intelligently handles caching of the compiled CSS code so that new code is compiled when necessary, and previously compiled code is not recompiled unless something changes which might cause a change in the compiled CSS. When possible, compiled CSS code is shared among objects which include the same Sass files (and not recompiled in each location where the Sass file is included).

Flushing Sass Code from the Cache

If you wish to flush Sass code from the cache, you need to be aware that the uncompiled contents of Sass files and the compiled code generated from them are cached in different locations:

  • The uncompiled contents of Sass files are cached with all other dotCMS files in the “fileassetmetadata” cache region.
  • The compiled CSS code generated from Sass files are cached to the “csscache” cache region.
    • Any compiled CSS code generated from Sass files which is used on a page is also cached in the “htmlpagecache” region for the specific page (and is subject to the “Cache TTL” property specified for the page).

Because the compiled CSS code may be cached in multiple regions, in order to ensure compiled CSS is flushed completely, you either need to understand the structure of the page and components the Sass file is included in and just flush the appropriate regions for that page, or to flush all of the above referenced cache regions.

To flush each of these regions, navigate to the System –> Maintenance screen, select the Cache tab, select the appropriate cache region (see below), and press the Flush button.

Cache RegionSelection for the “Flush Cache” Command
fileassetmetadataFile
csscacheProcessed CSS Cache
htmlpagecachePage
blockdirectivecacheBlock Directive
blockdirectivehtmlpagecacheBlock Page

Forcing Recompile

(Available only when logged in to the dotCMS backend)

To force the re-compile of a Sass file, you may append the ?recompile=true parameter to the path specification for the Sass file within your Theme or Template:

http://{host}/{path}/styles.dotsass?recompile=true

This option allows you to force a recompile of the Sass file to CSS and verify the recompile in the dotcms.log file.

Debugging

(Available only when logged in to the dotCMS backend)

To debug issues with the Sass compiler, you may examine the un-minified version of the CSS file by appending the ?debug=true parameter to the path specification for the Sass file within your Theme or Template:

http://{host}/{path}/styles.dotsass?debug=true

You can use this debug option to verify that the human readable (non-minified) CSS output matches the expected result.

Sass Compiler Selection

Previous versions of dotCMS used a jruby-based Sass compiler. This compiler had the advantage that it could be shipped with the dotCMS distribution and did not require separate installation of the compiler on your server. Unfortunately however this compiler is no longer actively supported by the developers, and no longer supports current versions of Sass, so it has been deprecated in favor of libsass.

The old jruby-based SASS compiler still ships with dotCMS, but is disabled by default. If you are unable to install libsass on your server, or have a need to use the legacy Sass compiler, you may re-enable it by adding the following property and value to the dotmarketing-config.properties file:

USE_LIBSASS_FOR_SASS_COMPILATION=false

Please note that the old jruby-based Sass compiler is deprecated. This means that it does not support some current Sass features, it will not support any future Sass changes, and it may be removed in a future version of dotCMS.