Difference between revisions of "Customizing WeBWorK"

From WeBWorK_wiki
Jump to navigation Jump to search
(→‎Introduction: - add link to blog post with modern approach and not on contents being out of date)
(Update theming to 2.17+)
Line 1: Line 1:
 
== Warning - page out of date ==
 
 
'''Most of this page is out of date.''' See [http://webworkgoehle.blogspot.com/2014/07/customizing-colors.html Geoff Goehle's blog post] on more recent methods to customize themes.
 
 
== Introduction ==
 
 
----
 
 
The basic look and feel of the WeBWorK user interface is highly customizable, and can be easily changed by users. Currently, WeBWorK ships with four themes (or skins) to choose from: ur, math, math2 and moodle; however, users with with knowledge of CSS and basic HTML may define their own themes for use in their courses.
 
   
 
== Changing to a different provided theme ==
 
== Changing to a different provided theme ==
Line 25: Line 15:
 
And changing it to "math2", "ur", "moodle" or "union" 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 <code>$defaultTheme</code> is changed in <tt>global.conf</tt>, individual instructors can still override that setting as described above.
 
And changing it to "math2", "ur", "moodle" or "union" 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 <code>$defaultTheme</code> is changed in <tt>global.conf</tt>, individual instructors can still override that setting as described above.
   
== Creating and installing your own theme ==
 
  +
== Customizing the theme up to version 2.16 ==
   
Currently, to define a new theme in WeBWorK you must create three files which define that theme and put those files in the proper locations in the <tt>webwork2</tt> directory hierarchy. To create a new theme called <tt>my_theme</tt>, you must do the following:
 
  +
'''For theming WeBWorK up to version 2.16''' see [http://webworkgoehle.blogspot.com/2014/07/customizing-colors.html Geoff Goehle's blog post] on more recent methods to customize themes.
* create a new directory <tt>webwork2/conf/templates/my_theme</tt>
 
* in that directory, create files <tt>system.template</tt> and <tt>gateway.template</tt>.
 
* create a new file called <tt>my_theme.css</tt> in the <tt>webwork2/htdocs/css</tt> directory
 
   
To get started, it is probably best to simply copy the <tt>math</tt> theme under the new name and change it incrementally. To do so, change directories to <tt>/webwork2/conf/templates</tt> and do
 
  +
== Customizing the theme for 2.17 and beyond ==
cp -r math my_theme
 
Inside the <tt>my_theme</tt> directory are the files <tt>system.template</tt> and <tt>gateway.template</tt>. Edit '''both''' of those files to change the line
 
 
<nowiki><link rel="stylesheet" type="text/css" href="<!--#url type="webwork" name="htdocs"-->/css/math.css"/></nowiki>
 
   
so that the <tt>href</tt> attribute reads
 
  +
The current theming is quite different from before and is mainly based on only changing colors. Also, you need access to the server and the ability to copy/edit files on the server to create new themes.
<nowiki>href="<!--#url type="webwork" name="htdocs"-->/css/my_theme.css"</nowiki>
 
   
Note the portion of those lines which says <nowiki><!--#url type="webwork" name="htdocs"--></nowiki>. This special comment style is used by WeBWorK's template system to provide dynamic content. Be sure not to alter ''that'' portion of the <tt>href</tt> attribute's value.
 
  +
# Change directory to <tt>WEBWORK_HOME/htdocs/themes</tt>.
  +
# Copy either the <tt>math4</tt> directory or one of the color directories.
  +
# Modify the <tt>_theme_colors.scss</tt> file, especially defining the <tt>$primary</tt> and <tt>$info</tt> variables. Note: these files are written in SCSS, which provides basic styling like CSS files, but with much more power.
  +
# Change the theme in the <em>Course Configuration</em> section of the course in WeBWorK.
   
To put the new CSS file into use, change directories to <tt>/webwork2/htdocs/css</tt> and do
 
cp math.css my_theme.css
 
   
At this point, you will have installed a new theme called <tt>my_theme</tt> into WeBWorK. To apply it to a single course, it can be selected and applied from the "Course Configuration" page along with the four provided themes. To apply it to every course on the server, simply set
 
<code>$defaultTheme = "my_theme"</code>
 
   
in <tt>global.conf</tt>. Now you can go about changing the look and feel of your WeBWorK courses by appropriately modifying the <tt>my_theme.css</tt> stylesheet and the templates under the <tt>/webwork2/conf/templates/my_template</tt> directory.
 
  +
----
  +
  +
Here's an example to build a purple theme.
  +
# <tt>cd $WEBWORK_HOME/htdocs/theme</tt>
  +
# <tt>cp -r math4 math4-purple</tt>
  +
# <tt>cd math4-purple</tt>
  +
# Use your favorite editor (vim, nano) to open <tt>_theme-colors.scss</tt>.
  +
# Change the values of the colors stored in the variables <tt>$primary</tt> and <tt>$info</tt>. For example, <tt>$primary: #994cf4</tt> and <tt>$info: #38036b;</tt>.
  +
# In your shell run the command <tt>npm run generate-css</tt>.
  +
# Return to WeBWorK and the Course Configuration page for your course.
  +
# Under the <em>General</em> table, the select popup for the <em>Theme</em> should now contain the <tt>math4-purple</tt> theme. Select it and click <em>Save</em> at the end of the page.
  +
# 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 <tt>my-banner.png</tt>
  +
  +
   
 
== See also ==
 
== See also ==

Revision as of 08:24, 19 January 2022

Changing to a different provided theme

Course Configuration page
Using the ur theme
Problem view with union theme

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." On that page you will be able to select one of the four installed themes: math, math2, ur, moodle, and union.

The math, math2, and moodle themes all look fairly similar. The ur and union themes are different from those and from each other.

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.

Changing the theme in this manner only changes the theme for the course you are logged into. If you would like to set a new default theme for all courses created on your WeBWorK server, then change the value of the $defaultTheme variable in global.conf. In new installations of WeBWorK, that variable is set as

$defaultTheme = "math";

And changing it to "math2", "ur", "moodle" or "union" 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 global.conf, individual instructors can still override that setting as described above.

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 and is mainly based on only changing colors. 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 WEBWORK_HOME/htdocs/themes.
  2. Copy either the math4 directory or one of the color directories.
  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.
  4. Change the theme in the Course Configuration section of the course in WeBWorK.



Here's an example to build a purple theme.

  1. cd $WEBWORK_HOME/htdocs/theme
  2. cp -r math4 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 run the command npm run generate-css.
  7. Return to WeBWorK and the Course Configuration page for your course.
  8. Under the General table, the select popup for the Theme should now contain the math4-purple theme. Select it and click Save at the end of the page.
  9. 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


See also

External Links