exams2forms: R/exams Interface for Forms in R/Markdown or Quarto Documents

In exams2forms: Embedding 'exams' Exercises as Forms in 'rmarkdown' or 'quarto' Documents

R/exams Interface for Forms in R/Markdown or Quarto Documents

Description

The exams2forms interface can be used within R/Markdown or Quarto documents to dynamically insert individual questions or entire quizzes based on R/exams exercise templates.

Usage

exams2forms(file,
  write = TRUE, check = TRUE, box = TRUE, solution = TRUE, nchar = c(20, 40),
  schoice_display = "buttons", mchoice_display = "buttons",
  cloze_schoice_display = "dropdown", cloze_mchoice_display = mchoice_display,
  usecase = TRUE, usespace = TRUE, auto = FALSE,
  show_filename = !isFALSE(auto), show_tolerance = !isFALSE(auto),
  n = 1L, nsamp = NULL, dir = ".", edir = NULL, tdir = NULL, sdir = NULL, verbose = FALSE,
  quiet = TRUE, resolution = 100, width = 4, height = 4, svg = FALSE,
  converter = "pandoc-mathjax", base64 = NULL, obfuscate = TRUE, ...)

Arguments

file	character. A specification of (a list of) exercise files.
write	logical. Should writeLines be called on the resulting Markdown/HTML text?
check	logical. Should a check for showing the answer be added to the exercise?
box	logical. Should a box be added around the check environment?
solution	logical or character. Should the solution environment of the R/exams exercises (if any) be displayed or not? Optionally, solution can also be a character with the title for the corresponding solution box.
nchar	numeric. Number of characters for numeric or string fields (forms_num, forms_string). If a vector of length 2 is provided it is used as the minimum and maximum number of characters, respectively.
schoice_display, mchoice_display, cloze_schoice_display, cloze_mchoice_display	character. Should the interaction for single-choice or multiple-choice forms be displayed with buttons (radio buttons or checkboxes, respectively) or with drop-down menus? The default is to use buttons for single-choice and multiple-choice items and for multiple-choice interactions within cloze items. Only for single-choice interactions within cloze items, the default is to use drop-down menus.
usespace	logical. Defaults to TRUE, only used for string questions. If FALSE spaces are ignored when evaluating correct answers.
usecase	logical. Defaults to TRUE, only used for string questions. If FALSE answers are evaluated ignoring uppercase/lowercase.
auto	logical or named list/vector. If set to TRUE, the form fields are prefilled, the check button is clicked, the solution button (if any) is clicked, and the order of the exercises (if n > 1) is not shuffled. The options can also be controlled separately if auto is a named list/vector with (a subset of the) names prefill, check, solution, noshuffle.
show_filename	logical. Should the tolerance for numeric fields be shown before the field? Enabled by default only if the form is auto-filled/clicked.
show_tolerance	logical. Should the filename be displayed in the form? Enabled by default only if the form is auto-filled/clicked.
n	integer. The number of copies to be taken from file.
nsamp	integer. The number(s) of exercise files sampled from each list element of file. Sampling without replacement is used if possible. (Only if some element of nsamp is larger than the length of the corresponding element in file, sampling with replacement is used.)
dir	character. Standard argument for exams interfaces and hence included in the argument - but actually not used because exams2forms does not write output files.
edir	character specifying the path of the directory (along with its sub-directories) in which the files in file are stored.
tdir	character specifying a temporary directory, by default this is chosen via tempfile. Note that this is cleaned up (i.e., existing files are deleted) and only certain temporary files are preserved.
sdir	character specifying a directory for storing supplements, by default this is chosen via tempfile.
verbose	logical. Should information on progress of exam generation be reported?
quiet	logical. Should output be suppressed when calling xweave?
resolution, width, height	numeric. Options for rendering PNG (or SVG) graphics passed to xweave.
svg	logical. Should graphics be rendered in SVG or PNG (default)?
converter	passed on to make_exercise_transform_html (if markup = "html").
base64	logical. Should supplementary files be embedded using Base 64 coding? Passed on to make_exercise_transform_pandoc. The default is to enable Base 64 when an HTML-type document is produced.
...	currently not used.
obfuscate	logical. Should the correct answer be obfuscated when embedded in the HTML source code? If FALSE, it is included as plain text.

Details

exams2forms provides an interface for including exercises from R/exams (https://www.R-exams.org/) in R/Markdown or Quarto documents. This is done by rendering the exercises (either in .Rnw or .Rmd format) into Markdown which can then be included in .Rmd or .qmd documents. For a short introduction see https://www.R-exams.org/tutorials/exams2forms/.

The function exams2webquiz can set up a suitable .Rmd file and directly render it. This is intended mostly for quick interactive testing when authoring R/exams exercises.

The idea and original code for inserting interactions into R/Markdown documents along with CSS and Javascript is adapted from the webexercises package, authored by Dale Barr and Lisa DeBruine.

Value

A list of exercises, each of which is a character vector with the Markdown code of the individual exercises.

See Also

exams2webquiz, xexams, xweave

Examples

## example R/exams exercises: string, num, schoice, mchoice
exams2forms("function.Rmd")
exams2forms("deriv.Rmd")
exams2forms("swisscapital.Rmd")
exams2forms("switzerland.Rmd")

## usually exams2forms() is used within R/Markdown or Quarto tutorials,
## two example files are shipped within the package.
## - questions.Rmd: all questions set up indvidually
## - quiz.Rmd: an entire quiz set up in one go
lr <- system.file("forms", package = "exams2forms")
dir(lr)

## quiz.Rmd is rather short and straightforward
rmd <- file.path(lr, "quiz.Rmd")
writeLines(readLines(rmd))

## Not run: 
## either .Rmd file can be loaded in RStudio and rendered from there or
## using the command line, e.g.,
rmarkdown::render(rmd)

## End(Not run)

exams2forms documentation built on May 9, 2025, 3 a.m.