Astridx
From Joomla! Documentation
Most of the Joomla 4.x default stylesheets are written using SCSS and then compiled to generate the CSS files.
Contents
Where can you find the .scss stylesheets and compiler?
The core .scss files are in different directories. Specifically, these are these filesː
- templates/cassiopeia/scss/template.scss
- administrator/templates/atum/scss/bootstrap.scss
- administrator/templates/atum/scss/font-awesome.scss
- administrator/templates/atum/scss/template.scss
- administrator/templates/atum/scss/template-rtl.scss
- media/plg_installer_webinstaller/scss/client.scss
The CSS generation script, SCSS compiler, and other similar build tools are located in the build/ directory of the Joomlaǃ source located on GitHub. Refer to Git for Coders for more information on using GitHub. The build directory is only available from the Joomlaǃ source, it is not included in an official Joomlaǃ release.
Prerequisites
Compiling your own SCSS files with Joomlaǃ core requires your local machine to have Node.js installed in it. To install Node.js, please go to the Node.js official web site, download the respective setup for your operating system and install it by following the installation wizard. NPM (Node Package Manager) is used to manage and setup the JavaScript testing environment.
Install dependencies (packages)
Open a command line and navigate to the root directory of Joomla 4.x.
Execute command npm install
$ npm install
...
added 1354 packages in 193.687s
$
This will install all the dependencies to the /node_modules directory. If a /node_modules folder does not exist, a folder will be automatically created by npm. It is OK, if you see some warnings, but you should not see an error message.
How to re-generate the CSS style sheets
To re-generate all the CSS files from a Joomlaǃ core distribution, you will need to execute the generation scripts as a CLI application.
All Joomlaǃ core scss files
You can compile all Joomlaǃ core css files with the command node build --compilecss. For exampleː
$ node build --compilecss Prefixing for: last 1 version Without `from` option PostCSS could generate wrong source map and will not find Browserslist config. Set it to CSS file path or to `undefined` to prevent this warning. template.css was updated. Prefixing for: last 1 version template-rtl.css was updated. Prefixing for: last 1 version font-awesome.css was updated. Prefixing for: last 1 version client.css was updated. Prefixing for: last 1 version bootstrap.css was updated. Prefixing for: last 1 version template.css was updated. $
All files in one directory
You can compile all all files in one directory with the command node build --compilecss pathtodirectory. For exampleː node build --compilecss templates/cassiopeia/scss.
$ node build --compilecss templates/cassiopeia/scss Prefixing for: last 1 version Without `from` option PostCSS could generate wrong source map and will not find Browserslist config. Set it to CSS file path or to `undefined` to prevent this warning. template.css was updated.
One special file
You can compile one file with the command node build --compilecss pathtofile. For exampleː node build --compilecss templates/cassiopeia/scss/template.scss.
$ node build --compilecss templates/cassiopeia/scss/template.scss Prefixing for: last 1 version Without `from` option PostCSS could generate wrong source map and will not find Browserslist config. Set it to CSS file path or to `undefined` to prevent this warning. template.css was updated.
Noteː
- The file extension .scss must be lowercase.
- The css file must be created.
Compiling your own SCSS files for your template
To compile scss files for your own template, you will need to take a copy of the JOOMLA4/build/build-modules-js/compilecescss.js script and adjust it to suit your environment.
Alternatively you can use a SCSS Compiler plugin which compiles your .scss files automatically on page reload. In the Joomlaǃ Extension Directory JED you will find a plugin for this purposeː Joomlaǃ Extension Directory
More alternatives and tools you can find on http://sass-lang.com/install
The SCSS compiler used for the Joomlaǃ 4.x core is node-sass. In the Joomlaǃ core you can find it in the directory JOOMLA4/node_modules/node-sass.
Difference CSS, SCSS and Sass
SCSS or Sass simplifies CSS notation and defines variables. This ensures a clearer presentation, less code and a simpler revision through the use of variables.
CSS
With CSS we write code like below in full lengthː
#header {
margin: 0;
border: 1px solid blue;
}
#header p {
font-size: 14px;
color: blue;
}
#header a {
text-decoration: none;
}
Sass
Sass is a CSS preprocessor with syntax improvements. Style sheets in the extended syntax are processed by the preprocessor and converted into regular CSS style sheets.
There are two syntaxes available for Sassː SCSS and Sass.
SCSS
SCSS is used in Joomlaǃ core. SCSS is an extension of the syntax of CSS.
$color: blue;
#header {
margin: 0;
border: 1px solid $color;
p {
color: $colorRed;
font: {
size: 14px;
}
}
a {
text-decoration: none;
}
}
Sass
The older Sass syntax provides a more concise way of writing CSS.
$color: blue
#header
margin: 0
border: 1px solid $color
p
color: $colorRed
font:
size: 14px
a
text-decoration: none
You can find more information in the Sass Documentation.
From existing CSS to SCSS / import CSS files
You may want to add your existing CSS files and classes to your SCSS powered Cassiopeia template or start with what you have. All CSS declarations are compatible with SCSS so you can just rename your .css files to .scss and you can compile and use them. You can then step by step make use of the features SCSS has to offer:
- Language extensions such as variables, nesting, and mixins
- Many useful functions for manipulating colors and other values
- Advanced features like control directives for libraries
- Well-formatted, customizable output
Notice: If you want to customize Cassiopeia template it is a good idea to copy the template and customize it afterwards - so that Joomla! updates do not overwrite your customizations.
Import your .css as .scss files
Now lets assume you want to include your custom files and get them parsed by SCSS compiler - you do NOT need to rewrite your .css to SCSS because plain .css works as well. The only thing you have to do is
- to rename your .css files to .scss and
- prefix it with an _ and
- add an @import statement into above mentioned main templates/cassiopeia/scss/template.scss
I assume you put your custom mystyles.css file renamed to _mystyles.scss into the /templates/cassiopeia/scss folder. Now you open /templates/cassiopeia/scss/template.scss and at the bottom of the file your _mystyles.scss file so that it overrides existing declarations:
// Bootstrap functions
@import "../../../media/vendor/bootstrap/scss/functions";
// Variables
@import "variables";
// Flying Focus
@import "../../../media/vendor/flying-focus-a11y/scss/flying-focus";
// Bootstrap
@import "../../../media/vendor/bootstrap/scss/variables";
@import "../../../media/vendor/bootstrap/scss/bootstrap";
// FontAwesome
@import "../../../media/vendor/font-awesome/scss/font-awesome";
// B/C for Icomoon
@import "../../../media/system/scss/icomoon";
// Alert
@import "../../../media/system/scss/jalert";
// Blocks
@import "blocks/global"; // Leave this first
@import "blocks/alerts";
@import "blocks/banner";
@import "blocks/demo-styling";
@import "blocks/footer";
@import "blocks/form";
@import "blocks/frontend-edit";
@import "blocks/header";
@import "blocks/icons";
@import "blocks/iframe";
@import "blocks/layout";
@import "blocks/modals";
@import "blocks/modifiers";
@import "blocks/utilities";
@import "blocks/css-grid"; // Last to allow fallback
// Vendor overrides
@import "vendor/awesomplete";
@import "vendor/bootstrap/buttons";
@import "vendor/bootstrap/card";
@import "vendor/bootstrap/custom-forms";
@import "vendor/bootstrap/collapse";
@import "vendor/bootstrap/dropdown";
@import "vendor/bootstrap/lists";
@import "vendor/bootstrap/modal";
@import "vendor/bootstrap/nav";
@import "vendor/bootstrap/pagination";
@import "vendor/bootstrap/table";
@import "vendor/chosen";
@import "vendor/dragula";
@import "vendor/minicolors";
@import "vendor/tinymce";
@import "mystyles";
If you now compile your main template.scss file you end up with one main template.css optimized and minified. You also reduced your http requests and the site should load faster.