Customizing WeBWorK

From WeBWorK_wiki
Revision as of 14:52, 25 July 2022 by Berndsing (talk | contribs) (→‎Customizing the theme for 2.17 and beyond: Missing s at the end of themes in step 1 of the example; in my own try of the example, I also had to restart apache2 for the new theme to work properly - so I added that step.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Changing to a different provided theme

Course Configuration page

To change to one of the provided themes, log into a WeBWorK course as a professor and navigate to the "Course Configuration" page under "Instructor Tools." Currently, the options are: math4, math4-red and math4-green.

After you select a new theme, you must click "Save Changes" for the change to be applied, and then refresh your browser to see the result.

Setting the Default Theme

If you have administrator privileges, you can set the default theme for the entire site, which will cascade to individual courses as well. To do this, change the value of the $defaultTheme variable in localOverrides.conf. In current installations of WeBWorK, that variable is set as $defaultTheme = "math4"; And changing it to "math4-red" or "math4-green" would apply the corresponding theme to every current course on your server and to all courses created in the future. Of course, even if the $defaultTheme is changed in localOverrides.conf, individual instructors can still override that setting as described above. If you create a new theme (see below), you can set the default to the new theme as well.

Customizing the theme up to version 2.16

For theming WeBWorK up to version 2.16 see Geoff Goehle's blog post on more recent methods to customize themes.

Customizing the theme for 2.17 and beyond

The current theming is quite different from before. Also, you need access to the server and the ability to copy/edit files on the server to create new themes.

  1. Change directory to /opt/webwork/webwork2/htdocs/themes.
  2. Copy one of math4-green, math4-red, or math4-yellow. Note: It is recommended that you do not copy math4, although you may do so for more advanced theming (you are on your own on this).
  3. Modify the _theme-colors.scss file, especially defining the $primary and $info variables. Note: these files are written in SCSS, which provides basic styling like CSS files, but with much more power. See https://getbootstrap.com/docs/5.1/utilities/colors/#map for other color variables that may be customized.
  4. For more advanced theming, in addition to setting bootstrap sass variables in _theme-colors.scss, you may also override bootstrap defaults in the file _theme-overrides.scss. See the _theme-overrides.scss in the math4-yellow theme for one example of this. Also see the general documentation at https://getbootstrap.com/docs/5.1.
  5. If all you want to do is modify the appearance of a few elements, you may instead work with one of the existing themes and copy the math4-overrides.css.dist or math4-overrides.js.dist files renamed without .dist, and add to those files. Note that the math4-colors.css file is not used anymore.
  6. Change the theme in the Course Configuration section of the course in WeBWorK.

Here's an example of how to build a purple theme.

  1. cd /opt/webwork/webwork2/htdocs/themes
  2. cp -r math4-green math4-purple
  3. cd math4-purple
  4. Use your favorite editor (vim, nano) to open _theme-colors.scss.
  5. Change the values of the colors stored in the variables $primary and $info. For example, $primary: #994cf4; and $info: #38036b;.
  6. In your shell from somewhere in the webwork/htdocs directory run the command npm run generate-assets.
  7. Restart apache2 with sudo apache2ctl graceful.
  8. Return to WeBWorK and the Course Configuration page for your course.
  9. Under the General table, the select popup for the Theme should now contains the math4-purple theme. Select it and click Save at the end of the page.
  10. After the page reloads, the only theme is still present, but navigating anywhere else will now change the theme.

Adding a banner image

Starting in version 2.16, there is an easy way to add a banner image to your theme. It will be placed in the top bar by following these steps. Let's say that you have an image (jpg, png or svg) that is wide and short. Let's say it's called my-banner.png. If you want to use in the default theme (say math4), add this file to htdocs/themes/math4/images. If you want it in a custom theme add it to the images directory of your custom theme.

In the configuration file localOverrides.conf, uncomment or add the following lines:

$institutionLogo = 'my-banner.png';
$institutionURL  = 'https://www.my-university.edu';
$institutionName = 'The University Name';

The banner logo will then have a link to the above URL.

See also

External Links