Skip to content

Creating assignments

Jump to bottom
Richard Morey edited this page Jul 21, 2021 · 16 revisions

Creating assignments

This content is relevant to flexTeaching version 0.2.

Assignment structure

Each assignment is a located in its own subfolder of the inst/assignments/ folder of the package. If the folder is named beginning with an underscore, it is not used. This enables disabling whole assignments simply by renaming the folders.

In addition, there is an inst/assignments/_common folder that contains content common to all assignments. This is useful for utility functions, etc.

There are two necessary files in the folder for every assignment: _assignment.yml, which contains the settings for the assignment, and index.Rmd, which contains the source Rmarkdown to be compiled and displayed.

Also necessary is some R source file that defines the function to run to compile the html from the Rmarkdown. This will often be a boilerplate function defined in inst/assignments/_common/R. Customizing this function is possible, but not necessary.

Assignment settings

The settings for each assignment are contained in a file called _assignment.yml.

Setting Optional? Content Description
title No String A title for the assignment to use in the menu
shortname No String A shortname to use for linking directly to the assignment
author Yes String Author of the assignment
date Yes String Date the assignment was last edited/created
version Yes String Version of the assignment
note Yes String An optional note describing the assignment, etc
category Yes String A category/group name for the menu
sortkey Yes String The key to use in sorting assignment within the menu
hide_before Yes String parsable by base::strptime Hide the assignment before this date. It will not appear in the menu, but it will still be accessible (unless restricted). The default date format is "%Y-%m-%d %H:%M:%S %z" but is configurable in the package options
restrict_before Yes String parsable by base::strptime Restrict (make inaccessible) the assignment before this date. It will still appear in the menu (unless hidden). The default date format is "%Y-%m-%d %H:%M:%S %z" but is configurable in the package options
seed-salt Yes String Salt to use for creating the assignment seed from the master seed
data-salt Yes String Additional salt to use when compiling the assignment
source Yes Array of file names R files to source() into the environment
init Yes String, name of function The function to run before compiling the assignment (typically producing data sets, results, etc). This function should return a list object.
html-gen No String, name of function The function to compile the html from the markdown
buttons Yes String, name of list A list of lists, each element of which contains details of buttons to create for the assignment
on-load Yes String (probably multiline) javascript code to run when the assignment loads. This string will be interpolated with glue::glue

The html-gen function

The function referenced by the html-gen settings must take two arguments, path and envir, and return a file name containing the HTML code result.

Argument Content Description
path String The full path, including file name, of the Rmd file to be rendered
envir Environment An environment in which to render the document. The environment will contain an object called .flexteach_solutions, which will be a logical value indicating whether solutions are to be rendered, and .flexteach_info, which is the return value of the init function (a list object).

The function should return the full path to a file containing the HTML content (without <head> content).

Here is one example, using :

compile_assignment_html <- function(path, envir = new.env(), ...){
  tmpfn = tempfile(fileext = ".html")
  input = file.path(path, "index.Rmd")
  output_format = rmarkdown::html_fragment(pandoc_args = c("--metadata", "title= " ) )
  rmarkdown::render(input = input, output_format = output_format, output_file = tmpfn, 
                    envir = envir, quiet = TRUE, ...)
  return(tmpfn)
}

Assignment markdown

The main source markdown is contained in a file called index.Rmd. This should be a plain Rmarkdown file with no YAML header.

Clone this wiki locally