-
Notifications
You must be signed in to change notification settings - Fork 4
Creating assignments
This content is relevant to flexTeaching version 0.2+.
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.
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. This will be ignored. |
category | Yes | String | A category/group name for the menu. If not given, the category will be " " (a string with a single space). Categories will be shown in alphabetical order. |
sortkey | Yes | Integer (default: Inf ) |
The key to use in sorting assignment within the menu. If not given, the sortkey will be set to Inf (so will appear last). |
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 | Yes | String, name of function | The function to compile the html from the markdown. If not given, defaults to flexTeaching:::compileAssignmentHtmlDefault
|
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
|
exam | Yes | Boolean (default: false) | If an assignment is marked as an exam, then it is unavailable in practice mode (unless the correct secret is entered) |
exam_practice | Yes | Boolean (default: false) | If true, the exam can be seen in practice mode if the secret entered is consistent with the one generated from the master seed |
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 to the assignment folder in which index.Rmd resides |
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,
intermediates_dir = dirname(tmpfn),
envir = envir, quiet = TRUE, ...)
return(tmpfn)
}
The main source markdown is contained in a file called index.Rmd
. This should be a plain Rmarkdown file with no YAML header.