Working with staff client SCSS

From Koha Wiki

Jump to: navigation, search
Home
Koha > Technical > Development > Coding guides

The staff client's default (prog) template uses Sass files in SCSS format to generate the CSS files used in the theme. Sass is a "CSS extension" (similar to LESS) which allows authors to use "variables, mixins, operations and functions." The staff client's Sass files contain some use of variables and mixins, but their primary difference from standard CSS is the logical grouping of style rules through nested rules.

When making CSS changes to the staff client, changes should be made to the .scss files, not the .css files.

As of 2018-01-30 the only Sass file in the staff client is staff-global.scss

Contents

Setting up your development environment

Processing of Sass files is handled by a yarn build process which in turn runs a gulp script.

  1. Install Node.js and the Node Package Manager ("npm").
  2. Use npm to install yarn
sudo apt-get install nodejs npm [not necessary in kohadevbox]
sudo npm install -g yarn
yarn install
yarn build

Compiling Sass files

After you have made changes to staff-global.scss, compile your changes by running yarn build again.

The yarn build process automatically compiles SCSS to CSS, adds automatic vendor prefixing, and minifies the CSS.

There is also a yarn css command available which might be used by developers who are making changes to Sass. This command does two things differently:

  1. Adds .css.map files which aid CSS debugging using in-browser inspector tools.
  2. Compiles staff-global.css without minification. It can be useful to see unminified CSS during development, especially to see how SCSS compiles.

Autoprefixing

The build process includes a tool called autoprefixer, used to "parse CSS and add vendor prefixes to CSS rules using values from Can I Use." autoprefixer is run without any explicit options. The default configuration adds automatic vendor prefixes in order to provide coverage for:

  • Browsers with greater than 1% global usage
  • The last 2 versions of browsers
  • Firefox ESR.

This tool eliminates the necessity of adding vendor prefixes to SCSS code.

Guidelines for editing Sass files

staff-global.scss differs from the old staff-global.css primarily in that it uses nested syntax. There are two other Sass-specific features to note:

  • Some variables are defined near the top of the file. These variables can be used in place of the strings which define them.
  • Some mixins are defined.

When adding style rules to Sass files please look for existing rules in which your additions might be logically nested. Remember that nesting adds specificity to your CSS, which may not be necessary for the style you want to achieve. The minimum required specificity is recommended.

Adding Sass files

To add a new CSS file to the staff client, simply create the corresponding .scss file in the css/src directory. Each .scss file in the staff client's css/src directory is automatically compiled, minified, and saved to the css directory.

Using .sass-lint.yml

.sass-lint.yml is a set of rules for writing consistent SCSS. It is a configuration file for linting SCSS with sass-lint. Various code editors can be set up to do inline SCSS linting, or it can be done on the command line. Currently staff-global.scss does not pass all sass-lint tests. New additions should.

See Sass lint rules for information about some notable rules.


Developer handbook

Personal tools