Using the {webexercises} package to add mini-interactive exercises to bookdown

Using the {webexercises} package by Lisa Debruine can help you add interactive exercises to your bookdown book, including True/False, multiple choice, short fill in the blank, and hide/unhide for hints or solutions. This can be very helpful for quick feedback to check understanding. Custom CSS is used for the styling and buttons, and Custom JavaScript for testing correctness and using CSS styles.

Peter Higgins true
07-14-2021

Putting Web Exercises into a Bookdown book

There is a large benefit to providing rapid, frequent interactive feedback during teaching, to test and challenge whether students truly understood the most recent chunk of the material. This is familiar in medicine to folks who used Dubin’s book to learn EKG interpretation. https://www.amazon.com/Rapid-Interpretation-EKGs-Sixth-Dubin/dp/0912912065/ref=sr_1_3?dchild=1&keywords=dubin+ekg+interpretation&qid=1634337078&sr=8-3.

The {webexercises} package, by Prof. Lisa Debruine and her PsyTeachR team at the University of Glasgow, allows insertion of small web exercises into a bookdown book.

Setup

You want to set up an “include” folder in the root directory of your bookdown book. Go to the root directory (open your bookdown project, use the directory with the your_book_name.Rproj file), and click on New Folder at the top left of the Files tab. Name the new folder “include”.

Use File/New File/CSS to create a new, empty CSS file. Save this in the ‘include’ folder as webex.css. Leave this file open.

Use File/New File/Javascript to create a new, empty Javascript file. Save this in the ‘include’ folder as webex.js. Leave this file open.

You need the latest webex.css and webex.js files from the PsyTeachR project. These can be found at: https://github.com/PsyTeachR/webex/tree/master/inst/reports/default. Use a web browser to go to this github repository, then open the webex.css file.

Copy the contents of the webex.css file in the github repository, then paste this into your webex.css file in RStudio. Now save this file. You can now close this file.

Now copy the contents of the webex.js file in the github repository, then paste this into your webex.js file in RStudio. Now save this file. You can now close this file.

output.yml - reference the css

Now go back to the root directory of your bookdown project. Find and open the output.yml file.

This likely looks something like:

bookdown::gitbook:
  default: TRUE
  smart: FALSE
  css: style.css

You will need to edit the css line. It should end up looking like this:

bookdown::gitbook:
  default: TRUE
  smart: FALSE
  css: [include/webex.css, style.css]

This will use the webex.css instructions, then your local style.css instructions. Be sure to use the brackets and comma.

output.yml - reference the javascript

Now you need to add the reference to the javascript file. Edit your _outlook.yml file to look like this:

bookdown::gitbook:
  default: TRUE
  smart: FALSE
  includes:
      after_body: include/webex.js
  css: [include/webex.css, style.css]

Be careful with the tabs and colons, or the javascript won’t be found.

Coding some mini-exercises

There are four types of available exercises

  1. True/False (torf)
  2. Multiple choice question (mcq)
  3. Fill in the blank (fitb)
  4. Hide and unhide (hide/unhide) for hints and solutions, or more explanation.

These are created with inline R code, which requires backticks at beginning and end, and needs to start with r, like

2^3 is `r fitb('8')`

You can do this with TRUE/FALSE

True or False

Code England always wins the World Cup. This statement is `r torf(answer = FALSE)`

Output England always wins the World Cup. This statement is

Multiple choice

Code Which actor played Luke Skywalker in the movie Star Wars? `r webexercises::mcq(c('Alec Guinness', answer = 'Mark Hamill', 'Harrison Ford'))`

Output Which actor played Luke Skywalker in the movie Star Wars?

Fill in the blank

Code 2^3 is `r fitb('8')`

Output 2^3 is

Hide and Unhide

This is helpful for hints, solutions, or detailed explanations that not everyone will want to/need to read.

You create a Button with a text label on it, then text and/or a code chunk in a box that will be revealed when the button is clicked.

This starts with one line

`r hide('text on the button')`

Then a blank line. Then your solution or hint text, and/or a code chunk. Then a blank line.

Followed by a line

`r unhide()`

Fencing these off

You can create horizontal lines with 5 asterisks

put interactive exercises and buttons here between the horizontal lines

Rendering

This will not work in chapter Preview - the whole yaml needs to be processed. So render the book with

bookdown::render_book('index.Rmd')

Then view the resulting _book/index.html file in your browser to see these webexercises HTML widgets in action.

Tweaking the css format

You can fiddle with:

Named CSS colors can be found here https://www.w3schools.com/cssref/css_colors.asp or use #rgbhex like #F0FFFF, or rgba (a is alpha), like rgba(0,0,0,0.1) is a light gray.

Citation

For attribution, please cite this work as

Higgins (2021, July 14). Medical R: Using the {webexercises} package to add mini-interactive exercises to bookdown. Retrieved from https://higgi13425.github.io/medical_r/posts/2021-07-14-using-webex-to-add-mini-interactive-exercises-to-bookdown/

BibTeX citation

@misc{higgins2021using,
  author = {Higgins, Peter},
  title = {Medical R: Using the {webexercises} package to add mini-interactive exercises to bookdown},
  url = {https://higgi13425.github.io/medical_r/posts/2021-07-14-using-webex-to-add-mini-interactive-exercises-to-bookdown/},
  year = {2021}
}