Working with SCSS in the OPAC and staff interface

From Koha Wiki
Jump to navigation Jump to search

The OPAC and staff interface's default templates use Sass files in SCSS format to generate the CSS files used in the themes. Sass is a "CSS extension" (similar to LESS) which allows authors to use "variables, mixins, operations and functions." Koha'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 in the OPAC or staff interface, changes should be made to the .scss files, not the .css files.

Setting up your development environment

Note: If you are running inside koha-testing-docker, you should skip to Compiling Sass files below, as the dependencies are all already installed.

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

As each Koha version might have some different dependencies, you need to run the following command before you start: 

yarn install

Manually installing the tools

If your environment doesn't have yarn, gulp or node dependencies installed, you need to follow this guide. 

 sudo apt-get install nodejs npm [not necessary in kohadevbox]
 sudo npm install -g yarn
 yarn install

If this doesn't work or you're using koha-testing-docker, try the following: 

  wget -q -O- https://deb.nodesource.com/gpgkey/nodesource.gpg.key | sudo apt-key add -

Add "deb http://deb.nodesource.com/node_8.x stretch main" (where stretch matches your Debian distro) to "/etc/apt/sources.list.d/koha-node.list" Run the following: 

  apt-get update
  apt-get install nodejs
  npm install -g yarn
  cd <koha-git>
  yarn install

Next, install required node modules by running the following command in the Koha base directory 

 npm install -E

Compiling Sass files

After you have made changes to any .scss file, compile your changes.

For the staff interface, run 

yarn build

For the OPAC, run 

yarn build --view opac

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

As of 2018-08-09 when Bug 19474 and Bug 20427 were initially pushed to main, Koha's SCSS files differ from their previous CSS counterparts primarily in that they use 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 OPAC or staff interface, simply create the corresponding .scss file in the css/src directory. Each .scss file in the css/src directory is automatically compiled, minified, and saved to the css directory.

Committing Sass files

When committing patches, don't include the compiled .css files into any patches, but only the changed .scss files. The RM or RMaints will add the compiled files when pushing the patch.

Noting that yarn build is needed in your test plan is recommended.

Reviewing changes of the compiled CSS file

git show --word-diff $SHA1 | egrep '(\[-)|(\{\+)' | sed -r 's/^.*(\[\-.*\-\]\{\+.*\+\}).*$/\1/g'

For example :
git show --word-diff aebd3f6a53 | egrep '([\-)|(\{\+)' | sed -r 's/^.*(\[\-.*\-\]\{\+.*\+\}).*$/\1/g'

[-textarea{font-family:NotoSans}.navbar-]{+textarea{font-family:NotoSans,sans-serif}.navbar+}
[-textarea{font-family:NotoSans}.navbar-]{+textarea{font-family:NotoSans,sans-serif}.navbar+}
[-textarea{font-family:NotoSans}.navbar-]{+textarea{font-family:NotoSans,sans-serif}.navbar+}
[-textarea{font-family:NotoSans}.navbar-]{+textarea{font-family:NotoSans,sans-serif}.navbar+}

It shows that there are 4 instances of "textarea{font-family:NotoSans}.navbar" replaced by "textarea{font-family:NotoSans,sans-serif}.navbar"

Going further: beautify the css before making the diff https://scripter.co/git-diff-minified-js-and-css/

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 our SCSS files do not pass all sass-lint tests. New additions should.

See Sass lint rules for information about some notable rules.


Developer handbook

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Working_with_SCSS_in_the_OPAC_and_staff_interface&oldid=33859"