The Contao demo represents a complete website for the purpose of demonstrating the Contao possibilities. You can view the demo on contao.org and test it including backend access or you can install the Contao demo and extend it according to your needs.
The following information is not a complete tutorial regarding a local Contao installation, CSS or SASS/SCSS usage. Only some of the options that you could use for customization are listed here. These should serve as suggestions and are independent of the numerous other options in Contao.
You can easily install the Contao demo via the Contao Manager during a new installation. It is also possible to install via the console. Information on this can be found on the corresponding GitHub page. You can then follow the complete implementation of the Contao demo website in the Contao backend.
The Contao demo uses .scss files for the design. The app.scss is used directly in the respective Contao theme
settings and then compiled and provided as a final .css file via Contao.
What you should consider here, is described in more detail in this article “Sass/Less Integration”.
With the knowledge of the above Contao options (via “scssphp/scssphp”) you can edit the .scss files
directly in the Contao backend. For example, if you want to adjust the color values of the demo, you can make and save
changes via the Contao file manager in the file “contaodemo/theme/src/scss/variables/_colors.scss”. Further
SASS variables can be found in the files “_sizes.scss”, “_fonts.scss” and “_animation.scss”.
However, in order for the changes to these (SASS partial) files to be applied, you must then touch
and save “app.scss” once (see also: “Sass/Less Integration”).
The “scssphp/scssphp” library used by Contao may not support current “Dart Sass” features such as “@use”, “@forward” or other “Dart Sass” modules.
This may also apply to existing SASS extensions, e.g. for the “Visual Studio Code” editor etc.
In this case, in conjunction with a local Contao installation and a pure “Dart Sass” installation (see below),
it is therefore more optimal to compile the .scss files locally according to the requirements and then only reference
the final .css file (i.e. app.css) in Contao.
You can find the procedure for installing “Dart Sass” here. There are numerous instructions and tutorials available, so we will not go into them in detail here.
In conjunction with “Node.js”, it is a good idea to create the “package.json” outside the Contao directories.
This way, you could also serve other Contao installations later on and only have to adjust the respective paths of the
SCSS and CSS directories relative to “package.json”. There is also the helpful option of defining the
“SASS instructions” once via “nodescripts”
and starting them conveniently.
If you use the generated “app.css” of the demo in the Contao theme settings, the references to the respective .scss
sections are missing in the browser dev tools. Therefore, “source maps” are required, which you can create
automatically via SASS and use during local development. If the respective “source map” (.map) is available next to
the “app.css”, the browser dev tools then point directly to the corresponding entries in the .scss files.
This is helpful for the next step. With the SASS flag “–watch”, the creation
of a .css file is automatically triggered as soon as you save changes to the .scss files (including SASS partials),
even via the browser dev tools (with workspace shares). Once activated, you can now directly track, change and save the
effects of your .scss customizations in the browser dev tools.
For the example of the color adjustments, we only want to highlight the SASS variables to be changed for the sake of
clarity. To do this, we create a new SASS partial file “_custom.scss” in the “scss” directory. In this file, we only
copy the variables from “variables/_colors.scss” that we actually want to change or overwrite.
We change the color values in “_custom.scss” and include them as the first entry in “app.scss” using
“@import”. The new color specifications are now included but not yet taken into account!
In the “variables/_colors.scss” we still have to use the SASS flag “!default”.
This means that the existing values of the SASS variables are only used if there is not already a definition. However,
this is given by our specifications from “_custom.scss” and therefore these color specifications are now taken into
account.
The three files could now look like this in excerpts:
// global colors
$c-primary--50: hsla(30, 100%, 97%, 1) !default;
$c-primary--500: hsla(30, 100%, 48%, 1) !default;
$c-primary--600: hsla(30, 100%, 42%, 1) !default;
$c-primary--700: hsla(30, 100%, 30%, 1) !default;
$c-secondary--700: hsla(207, 44%, 26%, 1) !default;
$c-secondary--800: hsla(207, 44%, 21%, 1) !default;
$c-secondary--900: hsla(207, 44%, 14%, 1) !default;
// background gradients
$gradient--1: radial-gradient(50% 50% at 50% 50%, hsla(207, 44%, 26%, 1) 0%, hsla(207, 44%, 21%, 1) 100%) !default;
...
// ### custom color variables
$c-primary--50: hsla(30, 100%, 97%, 1);
$c-primary--500: hsla(212, 100%, 48%, 1);
$c-primary--600: hsla(212, 100%, 42%, 1);
$c-primary--700: hsla(212, 100%, 30%, 1);
$c-secondary--700: hsla(242, 100%, 25%, 1);
$c-secondary--800: hsla(242, 100%, 21%, 1);
$c-secondary--900: hsla(242, 100%, 14%, 1);
$gradient--1: radial-gradient(50% 50% at 50% 50%, $c-primary--700 0%, $c-secondary--900 100%);
// ### custom variables
@import 'custom';
// ### general variables
...
You could easily use the above implementation directly in Contao. As mentioned, however, “Dart Sass” offers numerous
other possibilities. Instead of explicitly defining the color specifications in “_custom.scss” via “CSS hsla()”, you
could also use SASS modules for color conversion.
Furthermore, the use of “@use” and “@forward” instead of “@import” would be useful, especially for larger projects. Among other things, “namespaces” were introduced here, which enable clear and secure referencing.
If you would like to use these and future “Dart Sass” features, you can do so via a local workflow.
Of course, you are not restricted, regardless of Contao versions. For example, you could also use established CSS variables ("custom properties") or other combinations in your workflow.