Difference between revisions of "Customizing WeBWorK"
Alex Jordan (talk | contribs) |
|||
(24 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
− | {{Template:UnderConstruction}} |
||
− | == 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 == |
||
[[File:Course_configuration.png|200px|thumb|right|Course Configuration page]] |
[[File:Course_configuration.png|200px|thumb|right|Course Configuration page]] |
||
− | [[File:Course_configuration_ur.png|200px|thumb|right|Using the ur theme]] |
||
− | [[File:Ur theme calc problem.png|200px|thumb|right|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 |
+ | To change to one of the provided themes, log into a WeBWorK course as a professor and navigate to the "Course Configuration" page. In the "General" tab, you may choose a "Theme". Currently, the options are: <tt>math4</tt>, <tt>math4-red</tt>, <tt>math4-green</tt>, and <tt>math4-yellow</tt>. |
− | |||
− | The <tt>math</tt>, <tt>math2</tt>, and <tt>moodle</tt> themes all look fairly similar. The <tt>ur</tt> and <tt>union</tt> 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. |
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 <code>$defaultTheme</code> variable in <tt>global.conf</tt>. In new installations of WeBWorK, that variable is set as |
||
+ | == Setting the Default Theme == |
||
− | $defaultTheme = "math"; |
||
+ | |||
− | + | If you have administrator privileges, you can set the default theme for the entire site. To do this, change the value of the <code>$defaultTheme</code> variable in <tt>localOverrides.conf</tt>. In current installations of WeBWorK, that variable is set as <tt>$defaultTheme = "math4";</tt>. |
|
+ | And changing it to "math4-red", "math4-green", "math4-yellow" 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>localOverrides.conf</tt>, 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 [http://webworkgoehle.blogspot.com/2014/07/customizing-colors.html Geoff Goehle's blog post] on previous methods for customizing 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. |
||
− | == Creating and installing your own theme == |
||
+ | # Change directory to <tt>/opt/webwork/webwork2/htdocs/themes</tt>. |
||
+ | # Copy one of <tt>math4-green</tt>, <tt>math4-red</tt>, or <tt>math4-yellow</tt>. Note: It is recommended that you do not copy <tt>math4</tt>, although you may do so for more advanced theming (you are on your own on this). |
||
+ | # 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. See https://getbootstrap.com/docs/5.1/utilities/colors/#map for other color variables that may be customized. |
||
+ | # For more advanced theming, in addition to setting bootstrap sass variables in <tt>_theme-colors.scss</tt>, you may also override bootstrap defaults in the file <tt>_theme-overrides.scss</tt>. See the <tt>_theme-overrides.scss</tt> in the <tt>math4-yellow</tt> theme for one example of this. Also see the general documentation at https://getbootstrap.com/docs/5.1. |
||
+ | # 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 <tt>math4-overrides.css.dist</tt> or <tt>math4-overrides.js.dist</tt> files renamed without <tt>.dist</tt>, and add to those files. |
||
+ | # Change the theme in the <em>Course Configuration</em> section of the course in WeBWorK. |
||
− | 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: |
||
+ | ---- |
||
− | * 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 |
||
+ | Here's an example of how to build a purple theme. |
||
− | cp -r math my_theme |
||
+ | # <tt>cd /opt/webwork/webwork2/htdocs/themes</tt> |
||
− | Insde 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 |
||
+ | # <tt>cp -r math4-green math4-purple</tt> |
||
− | |||
+ | # <tt>cd math4-purple</tt> |
||
− | <nowiki><link rel="stylesheet" type="text/css" href="<!--#url type="webwork" name="htdocs"-->/css/math.css"/></nowiki> |
||
+ | # 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 change to the webwork/htdocs directory and run the command <tt>npm run generate-assets</tt>. |
||
+ | # Restart <tt>apache2</tt> with <tt>sudo systemctl restart apache2</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 contains the <tt>math4-purple</tt> theme. Select it and click <em>Save</em> at the end of the page. |
||
+ | # After the page reloads, the previously selected theme is still shown, but navigating anywhere else will now change the theme. |
||
− | so that the <tt>href</tt> attribute reads |
||
+ | == Adding a banner image == |
||
− | <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. |
||
+ | 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>. If you want to use in the default theme (say <tt>math4</tt>), add this file to <tt>htdocs/themes/math4/images</tt>. If you want it in a custom theme add it to the <tt>images</tt> directory of your custom theme. |
||
− | Now change directories to <tt>/webwork2/htdocs/css</tt> and do |
||
+ | In the configuration file <tt>localOverrides.conf</tt>, uncomment or add the following lines: |
||
− | cp math.css my_theme.css |
||
+ | <pre> |
||
+ | $institutionLogo = 'my-banner.png'; |
||
+ | $institutionURL = 'https://www.my-university.edu'; |
||
+ | $institutionName = 'The University Name'; |
||
+ | </pre> |
||
− | 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 |
||
+ | The banner logo will then have a link to the above URL. |
||
− | <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. |
||
== See also == |
== See also == |
||
*[[WeBWorK logos]] |
*[[WeBWorK logos]] |
||
+ | *[[Hardcopy Themes]] |
||
== External Links == |
== External Links == |
||
* [http://www.w3schools.com/ Web development tutorials from w3schools.com] |
* [http://www.w3schools.com/ Web development tutorials from w3schools.com] |
||
+ | * [http://sixrevisions.com/web_design/colors-in-web-design-an-exploration/ Colors in Web Design: An Exploration] |
||
[[Category:Installation]] |
[[Category:Installation]] |
Latest revision as of 03:09, 18 August 2023
Contents
Changing to a different provided theme
To change to one of the provided themes, log into a WeBWorK course as a professor and navigate to the "Course Configuration" page. In the "General" tab, you may choose a "Theme". Currently, the options are: math4, math4-red, math4-green, and math4-yellow.
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. 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", "math4-green", "math4-yellow" 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 previous methods for customizing 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.
- Change directory to /opt/webwork/webwork2/htdocs/themes.
- 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).
- 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.
- 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.
- 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.
- Change the theme in the Course Configuration section of the course in WeBWorK.
Here's an example of how to build a purple theme.
- cd /opt/webwork/webwork2/htdocs/themes
- cp -r math4-green math4-purple
- cd math4-purple
- Use your favorite editor (vim, nano) to open _theme-colors.scss.
- Change the values of the colors stored in the variables $primary and $info. For example, $primary: #994cf4; and $info: #38036b;.
- In your shell change to the webwork/htdocs directory and run the command npm run generate-assets.
- Restart apache2 with sudo systemctl restart apache2.
- Return to WeBWorK and the Course Configuration page for your course.
- 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.
- After the page reloads, the previously selected theme is still shown, 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.