LAMS offers multiple skins or themes, made using sets of CSS files. In LAMS a theme is a skin and the words will be used interchangably. The CSS files are created using the SASS preprocessor.
SASS is an extension to CSS that allows variables to be defined, mixins, extra functions, etc. The files are .scss files and the SASS precompiler converts the to .css files.
Creating and Using Themes
Selecting A Theme
When LAMS in installed the default theme is "defaultHTML". This is based on the standard Bootstrap 3 colours.
The available themes are:
To change the default theme for a server, log in as sysadmin and go to Sys Admin, Edit Configuration Settings. Change the entry for "Default theme" to the value in the name column in the table above. It must match exactly. This is the theme that will be used for the Login page. All new users will get this theme but existing users will not be changed.
A user can change their theme using the Edit Profile option. They will get a drop down from which to choose their theme. Their setting will take affect when they log in, it does not affect the Login Page.
Creating A Theme
There are 10 files needed to create a new theme - one file to update the database with the new skin definition, one that contains all the colour settings to be customised and eight .scss files that create the appropriate .css files. If you haven't already installed SASS on your computer, install SASS now!
Create the theme definition. Copy the lams_common dbupdates file patch20170720.sql and update it with the new theme name and description. Run this SQL to create the entry in the table. This step only needs to be done once. Make the theme name a single word, all lowercase and with no punctuation. Make it something easy that a system adminstrator can type into the configuration field!
Now copy lams_central/conf/scss/lams_variables_purple.scss to _lams_variables<themename>.scss. Find the
$brand-primary: #85237d; entry in the lams_variables<themename>.scss file and change the colour to your new main colour.
In eclipse, turn off the automatic build at this point - if you leave it on it will keep compiling and compiling while you are doing the following copying/renaming.
In lams_central/web/css/ copy all the purple_blah.scss files to <themename>_blah.sccs files. Alter the lams_central/.gitignore file to ignore all the <themename>_blah.css files. Careful here - you copy and rename the SCCS files and ignore the CSS files.
In lams_monitoring/web/css/ copy the purple_monitorLesson.scss file to <themename>_monitorLesson.sccs file. No need to change the .gitignore for this project as it is already set up with a wildcard to ignore .css files.
Now turn back on the automatic build and it should built the set of <themename>_blah.css in lams_central and <themename>_monitorLesson.css in lams_monitoring. If it does not, you can force the CSS file generation using sass.compile target in the lams_central and lams_monitoring projects. Deploy the new .CSS files and run the server. Log in as a user and switch to the new theme. Fingers crossed you should see your new colours.
Now the fun starts. Go through the values in lams_variables<themename>.scss and tweak all the variables to give you the colours you want. You cannot change the grey border shades but pretty well all the coloured sections can be changed. When you change the variable file run sass.compile to trigger the regeneration of the .css files and then redeploy the files. The automatic build picks up changes in the web directory but not the conf directory. Keep doing this over and over until you are happy.
If the variables not enough to control all the colours you want, you will have to read on to learn more about how the themes have been implemented.
How Themes Work
We have two files _lams_variables.scss and _lams_variables_purple.scss, which define the appropriate colours for the skins.
Now I need to create a defaultHTML_authoring.css and purple_authoring.css file using the same css logic but different colours, etc using the variable values.
So create _authoring_base.scss and put all the usual scss/css stuff in that file. It has an underscore at the beginning of the name so that the SASS preprocessor will not try to process it directly, only when it is included from another file.
Make two placeholder files defaultHTML_authoring.scss and purple_authoring.scss. But the placeholder files have very little in them - the purple one is:
It imports the appropriate variable file and then pulls in the authoring definitions, and out pops the purple_authoring.css file with all the appropriate authoring purpley css settings.
The defaultHTML_learner and purple_learner files are more complicated but they follow the same logic and they include _inlineeditor.css which gives the CK Editor the appropriate colours.
Now to include the css file in a jsp needs the <lams:css/> tag. <lams:css/> alone will give /css/<themename>_learner.css, the main css file in LAMS. <lams:css suffix="main"/> will give you /css/<themename>_main.css, which is a css file from lams_central. <lams:css suffix="main"/> will give you /css/<themename>_main.css, which is a css file from lams_central. <lams:css webapp="monitoring" suffix="monitorLesson"/> will give you /monitoring/css/<themename>_monitorLesson.css.
Developing SASS/CSS Files
We have switched to using SASS after LAMS 3.0 was mostly completed, so the CSS files were not developed with SASS in mind. As as start we will be defining common colours, line styles, etc and using this where possible in the LAMS stylesheets to increase consistency. As time goes on we will add in mixins, etc as we find them useful.
We will put the .scss files in the same directory as the .css files, so that when you go to update the .css file you will see the .scss file and remember to update the .scss file hopefully!
Firstly, install SASS. After that you can use the sass.compile action already in the LAMS build files. The configuration details are in the various LAMS configuration files - common.properties, unix.properties, windows.properties.
If you are updating an existing sccs/css file then go to the css directory, update the scss file and the css will be automatically updated.
If you are added a new sccs/css combination with an existing css file, copy the blah.css file to blah.scss (in the same folder) and add the import statement
@import "_lams_variables.scss"; at the top of the file. This will include the LAMS variables and the Bootstrap variables in one go. To make it useful, it's a manual process of looking for colours, fonts, etc that overlap with already defined values and updating to use the variables.
If you are creating a new css file, create a blah.scss file (in the css folder) with the import statement at the top and start making entries!
If the automatic compile isn't working, you can trigger it using the sass.compile.auto Ant task.
The automatic compile will trigger console output displaying any errors. Once the precompile has been done, you can do a synchronise-war to copy the updated .css file to Wildfly.
The automatic compile is triggered by the .scss file being updated. If you change one of the shared files (_bootstrap_variables or _lams_variables) it will not trigger the automatic pre-compile. Either modify the .scss files you are working on or do a sass.compile (see Ant) to trigger an update on your current files.
The precompiling is a two step process - it calls SASS to do the precompile and stores the resulting .css file in the build directory. It then copies the .css file back to the web directory. As the css directory varies from project to project, the directory can be set in the build.properties file overriding the value in common.properties. See tool_lams_daco for an example.
There are three new ant tasks you may need to use
- _sass.build.clean: cleans the intermediary .css and .map files
- sass.compile.auto: precompiles any modified .scss files. So if the .css file is deleted by accident you will need to modify the .sccs file to trigger the .css file to be recreated.
- sass.compile: precompiles all the .scss files in the css directory. This is used by the build-war task which triggers the precompile to update all the .css files but does not copy to .scss files to the .war file.
Why do it as a two step process using the build directory? If you comment out the line
<arg value="--sourcemap=none"/> in build-base.xml then it will create .map files in build directory if you need to look at them, but they do not create clutter in the css directory.
The build includes a step to minify the css files. To turn this off, set css.minify in common.properties to false.
Have a look at _bootstrap-variables and _lams_variables in lams_build/conf/scss for all entries. Some commonly used ones are listed below. Try to use these entries. The _bootstrap-variables file contains many variables that we aren't using - the file defaults to all of them commented out and it has been left that way so we can see what we are likely to be using. If there is an entry in _bootstrap-variables that you want to reuse, uncomment it and add the ";" on the end of the line.
The grey/black/white shades are safe to use in tools as they are currently the same across all skins. So the value that is created using the default skin is find for other skins. The variable changes to primary, warning, info, etc are only picked if you have the scss files set up for skins (ie a base file and separate .scss files for each skin). Where possible outside of lams_central and lams_monitoring use a value from defaultLearner.css, not the SCSS variable.
Rather than define things by their use (e.g. $course-border) or by their colour ($border-blue) we are using the colour notations of primary, success, info, danger and warning as used by Bootstrap. We don't want to tie it directly to the use as these styles should be used across both the core and tools in LAMS. Using the Bootstrap categories we will hopefully avoid situations like $border-blue meaning green in a new colour scheme.
There is also a $font-size-large. If you need this, uncomment it in the _lams_bootstrap file (and add the ';' at the end of the line).
- Why do some .sccs files have _ names? The _ at the front of the name tells the precompiler to skip the file. Use it on a partial .sccs file ie one that is imported and not used on its own.
- sass.compile.auto is not trying to compile my .sccs file. The ant task will only precompile if the source file has changed. Try adding a space and saving the .sccs file and see if sass.compile picks it up.
- The build can't find the SASS executable. The executable is defined in unix.properties/windows.properties. Tweak this entry if necessary and make sure that SASS is on your path if needed (test it in a command line shell).
- I uncommented a line from _bootstrap_variables.scss and now it has a compilation error. Check that you put a ";" on the end of line - the _bootstrap_variables file doesn't have ";" entries but the compiler needs them. It may be due to the file coming from an compass installation.
Automating the SASS to CSS build.
Automatically building is based on Automatically Compling SASS / Compass in Eclipse / Zend Studio.
Right click on the project and select Properties, Builders. Create a new Builder named "SASS <project name>". Eclipse requires all the builders we create to have a unique name.
- Main tab: set the build file to "
- Refresh tab: turn on refresh and set to "The project containing the selected resource"
- Target tab: set Auto Build to sass.compile.auto and Clean to _sass.build.clean.
- Build tab: Turn on "Allocate Console", turn on "Specify Working Set.." and set it to the web directory.
If you don't specify the working set it will try to precompile the scss files whenever a Java file is updated.
The .sass-cache files are to be ignored - leave them as they speed up the precompile but do not check them in. The directory should be added to the projects .gitignore so they should not appear when checking in.
Reimporting _bootstrap-variables File.
This will not need to be done very often - only if there is a new version of Bootstrap 3 and there are changes we want to use. Bootstrap 4 will require more than a simple .sccs file update.
- Install Compass (gem install compass)
- Install Bootstrap for Compass without Rails and follow the instructions to create a new projects.
- Find the _bootstrap-variables.sccs file in the new project and compare it to the existing one. Our _bootstrap-variables file only has the ones we use uncommented (and ";" added at the end of the line). You will need to uncomment/; the matching lines in the new file and any new entries that are needed.