Customizing Colors

This post will address a relatively superficial, but often requested, feature which has been recently added to the develop version of WeBWorK - customizing theme colors and logos.  This latest change adds a couple of color variations for math4 right out of the box, as well as a built in way for system administrators to customize math4 themselves.

The first thing you will notice if you download the latest version of develop is that there are a couple of new themes available in the Course Config page - math4-green and math4-red.  Selecting either of these new themes will give you this:

You should notice that these variants are basically the same as math4 with different colors.  This is because they are implemented in such a way that they are just additional color css layered on top of math4.  So in theory they will always be up to date with the latest math4.  Of course, if you give a man three colors he is going to want 256.  That is why this update also allows sysadmins to customize math4.

The key to this customization are the files

webwork2/htdocs/themes/math4/math4-overrides.css
webwork2/htdocs/themes/math4/math4-overrides.js

These files are not shipped by default (although they have .dist versions) and are not tracked by git, so they won't be overwritten when you update.  However, if you put either of these files into the math4 theme folder they will be included into all WeBWorK pages after the normal math4 css and javascript.  This means that you can use them to make changes to math4 without potentially breaking your upgrade process. 

Lets go through an example where we will change math4 to use the Western Carolina University colors and logo.  First we copy over the distribution versions of the override files to give us something to start with

cd /opt/webwork/webwork2/htdocs/themes/math4/
cp math4-overrides.css.dist math4-overrides.css
cp math4-overrides.js.dist math4-overrides.js

We start with the coloring.  The math4-overrides.css file automatically simplifies the coloring of math4 so that there are only a handful of colors that are used over and over.   They are:

• Dark Blue: #003388
• Light Blue: #0088CC
• Dark Green: #519951
• Light Green: #88FF88
• Dark Red: #FF9494
• Light Red: #CC7676
• Dark Yellow: #BDB45E
• Light Yellow: #EDE275

Because we are using css (and not less) we have to change these by using a global find replace on the hex value, but that isn't so difficult.  The Dark Blue and Light Blue are the primary theme colors and are used almost everywhere.  The Green, Red, and Yellow colors are mostly used for alerts, such as marking things correct or incorrect.  We will be conservative and just change the main colors.  We would like to use WCU's school colors

• Purple: #492C88
• Gold: #CD7F32

I'm going to replace the Dark Blue by Purple and the Light Blue by Gold.  We could do this using any text editor and a global find/replace but lets get fancy

sed -i 's/003388/492C88/g' math4-overrides.css
sed -i 's/0088CC/CD7F32/g' math4-overrides.css

This by itself gets us much of the way there

We could spend a lot more time tweaking the colors.  For example, something that is missing by default (for ease of initial configuration) are hover colors for the buttons.  Adding a slightly different hover color will make the buttons seem much more dynamic. 

However, we will leave the colors as they are and address another often requested feature: changing the logos.  This is not done via css, rather it is done by javascript.  If we open math4-overrides.js we see the line

/* This changes the MAA Logo on the top to a new image */
//    $('.maa_logo a img').attr('src','new-path-here');

There is a similar line for the WeBWorK logo.  So if we want to put our school logo in place of the MAA logo we could put the appropriate image file (wcu.jpg) into webwork2/htdocs/images and change our js line to

$('.maa_logo a img').attr('src','/webwork2_files/images/wcu.jpg').css('height','40px');

Remember that things in htdocs will be available on the web under the webwork2_files directory.  This gives us the following

And that is it.  If we wanted to we could also replace the WeBWorK logo in much the same way.

So after only a few commands we have been able to give WeBWorK a whole new look.  We could go farther, too; much farther.  The thing to remember is that the override files allow system administrators to execute arbitrary css and (jQuery) javascript code that will be run after the usual math4 code.  The javascript/css combination is extremely powerful and allows you to change pretty much anything,  including html content.  So for example if I wanted to change "Hmwk Sets Editor2"  to "HW Sets Editor" in the Instructor Tools navigation menu I could just add the following to math4-overrides.js

$('#site-links a:contains("Hmwk Sets Editor2")').html('HW Sets Editor');

Of course, you have to come up with the javascript yourself, but the sky really is the limit here.  You can add whole features this way, all without touching core WeBWorK code.  (Although if you do that you might as well just write it into the core code and submit it as a pull request!)  There are a few gotchas to keep in mind, but in general this should provide power administrators with a great deal of flexibility.

Gotchas:

• Remember that unless you delete math4-red and math4-green your instructors will still be able to manually change to those themes.  Any overrides that you put into htdocs/themes/math4/math4-overrides.js or the corresponding css file will not automatically make it into math4-red or math4-green.  You will need to link to the math4-override files in the math4-red/math4-green subdirectories in order for your changes to carry over.  Of course if you copy over math4-overrides.css then math4-red and math4-green won't be red/green anymore. 
• While your modifications in the override files will not be overwritten by an upgrade, and should generally just work, it is possible for WeBWorK updates to change math4 in such a way as to be incompatible with your override files.  If this happens you will have to merge your changes with the new math4-overrides distribution files.  
• By default using this file removes some of the "dynamic" elements of bootstrap, like grading on the buttons, or a slightly different highlight color on the buttons. This is done for ease of configuration.  If you look at  htdocs/js/vendor/bootstrap/css/bootstrap.css you can copy/modify the relevant css code to get fancier buttons working again.  However this all has to be done "manually" and can't be automated with a global find/replace.
• Some of the red/green coloring is done using inline styling via pg.  This means that it can't be overridden using the math4-overrides.css file.  If you really want to alter all of the correct/incorrect coloring you will need to use javascript and math4-overrides.js to do it.