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

Server Side Compiling of Sass & Less Files

Dotcms is one of the first content management systems to offer server side editing/compiling of Sass and Less files “on the fly.” Modern front end development is best authored in a CSS pre-processor such as Sass or Less. CSS pre-processors extend the CSS language, allowing for additional features, variables, mixins and functions, and allows CSS to be more maintainable, themable and extendible.


Important:

Due to issues with some third party libraries on Windows and Solaris operating systems, the Sass precompiler may not perform properly when you run your dotCMS server on these operating systems.

Note:

  • The user's operating system does not affect the behavior of the Sass compiler (since the Sass compiler operates on the dotCMS server, not in the user's browser).
  • The Less precompiler works without any issues on all operating systems supported by dotCMS.

Why Sass and Less?

Both Sass and Less CSS pre-processors are actively developed, provide excellent compatibility with multiple browsers and CSS versions, and have extensive documentation and well established communities. For more information, please see the following:

Advantages of Uploading Sass and Less Files to dotCMS

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

  • Sass and Less 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.
  • A revertable change/user history is kept on every Sass and Less file.
  • The cache automatically refreshes each time a file is changed.

How to Reference Sass and Less files in a dotCMS Template

When properly referenced in your Template code, Sass and Less files are compiled server side “on the fly” and are cached. Sass and Less 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 and Less files are not regognized by some older browsers, dotCMS uses a special notation to access Sass and Less files which “disguises” your Sass and Less 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 or Less file, compiles it, and then sends the compiled CSS to the user's browser.

The following examples demonstrate how to reference your Sass and Less files within a dotCMS Template using this notation.

Sass

To reference a Sass file from within your Template, you must prefix the path to the Sass file with /DOTSASS, and reference the file as if it had a .css extension (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:

/DOTSASS/styling/bootstrap.css
/DOTSASS/styling/template.css

Less

To reference a Less file from within your Template, you must prefix the path to the Less file with /DOTLESS, and reference the file as if it had a .css extension (instead of the normal .less extension for Less files).

For example, given the following Less files:

bootstrap.less
template.less

You would use the following notation in your Template code:

/DOTLESS/styling/bootstrap.css
/DOTLESS/styling/template.css

How to Reference Sass and Less files in dotCMS Themes

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

Example

Sass

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:

/DOTSASS${dotTheme.path}/bootstrap.css
/DOTSASS${dotTheme.path}/fonts/font-awesome.css
/DOTSASS${dotTheme.path}/styling/theme.css
Less

Given the following files within your Theme folder:

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

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

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

Sample Sass and Less Files

The dotCMS starter site includes the Quest and Intranet Themes, both of which include pre-build Less files. In addition, you may download sample Themes using various frameworks from the dotCMS website. Each downloadable Theme includes pre-built Sass or Less files which you can use as examples to modify, or to create your own Sass or Less files for your own dotCMS Theme.

Caching of Sass and Less Files

All Sass and Less files are cached to the “csscache” cache region. This cache region can be manually flushed from the Cache tab on the System –> Maintenance screen by selecting the “Processed CSS Cache” and pressing the Flush button.

Any time a Sass or Less file is change, the cache reloads 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.

Importing Other Files into Sass and Less Files

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

Local Files

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.less";

Remote Files

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.less";

Caution: Sass and Less files residing on other servers, outside the existing instance, may NOT be imported via http call.

Debugging

(Available only when logged in to the dotCMS backend)

To debug issues with the Sass and Less 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 or Less file within your Theme or Template:

Sass

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

Less

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

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

Forcing Recompile of a Sass or Less File

(Available only when logged in to the dotCMS backend)

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

Sass

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

Less

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

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