---
title: 'How to start with `checkdown`'
author: "George Moroz"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{How to start with checkdown}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
editor_options:
chunk_output_type: console
---
## Installation
Get the stable version from CRAN:
```{r, eval=FALSE}
install.packages("checkdown")
```
… or get the development version from GitHub:
```{r, eval=FALSE}
install.packages("remotes")
remotes::install_github("agricolamz/checkdown")
```
## 1. Demo
The main goal of this package to create checking fields and boxes in `rmarkdown` or `quarto`. It can be used in class when teacher share materials and tasks (as an `.html` page or an `.html` slides), so student can solve some problems and check their work. It is really important since some students are too shy to ask a question, so you can create tasks that will check on the fly the understanding of the class material and give some hints to those students that get stuck. In contrast to the [`learnr`](https://rstudio.github.io/learnr/index.html) package the `checkdown` package works serverlessly without `shiny` and could be stored as a simple `.html` page (e. g. on Github Pages). In contrast to the [`exams`](https://www.r-exams.org/) output the `checkdown` package creates interactive auto-grading tasks. The interactive version of the [`exams`](https://www.r-exams.org/) output is bind to Blackboard Learn, that is really nice, but looks like an overkill for the simple task that `checkdown` solves.
Load the library:
```{r}
library(checkdown)
```
### 1.1 Ask question with the `check_question()` function
Imagine that we want to create a checkbox with the answer 4. All you need is to create a following chunk in your `rmarkdown` document:
```{r}
check_question(answer = 4)
```
It is possible to change wrong and right answer's messages using `wrong` and `right` arguments of the `check_question()` function. Let's create some more questions.
Solve 3+3:
```{r}
check_question(answer = 6, right = "correct", wrong = "not correct")
```
Type *la-la*:
```{r}
check_question(answer = "la-la")
```
It is possible to use `placeholder` argument in order to show what kind of answer you expect:
```{r}
check_question(answer = "la-la", placeholder = "ta-ta-ta")
```
Number of answers is not limited:
```{r}
check_question(answer = 1:5)
```
It is also possible to create a list of answers for students to choose:
```{r}
check_question("banana", options = c("apple", "banana", "bread"), type = "select")
check_question("banana", options = c("apple", "banana", "bread"), type = "radio")
check_question(c("banana", "apple"), options = c("apple", "banana", "bread"), type = "checkbox")
```
If the list of possible answers is small, it is possible to align them in one line using `alignment` argument:
```{r}
check_question("banana", options = c("apple", "banana", "bread"), type = "radio", alignment = "horizontal")
```
You can shuffle answers using the `random_answer_order` argument:
```{r}
check_question("banana", options = c("apple", "banana", "bread"), type = "radio", random_answer_order = TRUE)
```
If you don't want to give the possibility of automatically check your question, just put `NULL` in the `answer` argument:
```{r}
check_question(NULL, options = c("apple", "banana", "bread"), type = "radio")
```
There is also an experimental type of question `in_order`, wheere students need to drag and drop words in the correct order:
```{r}
check_question(answer = c("What", "do", "you", "think?"), type = "in_order")
```
In this type you need to provide correct order to the `answer` argument and options will be shuffled automatically.
In case answers are long, it is possible to use vertical `alignment`:
```{r}
check_question(c("heat the water",
"place a tea bag into the cup",
"pour the hot water over the tea bag",
"steep the tea bag into cup",
"remove the tea bag"),
type = "in_order", alignment = "vertical")
```
You can put the question itself within the `check_question()` function using the `title` argument.
```{r}
check_question(answer = 42, title = "Put a number from 1 to 100")
```
It is possible to put some markdown markup whithin the `title` argument. Since this argument wraps the form contents with \code{fieldset} tags, you can redefine it appearance with CSS.
There is an additional function `insert_score()` that make it possible to add a counter of the correct answers on the page (thanks to [Julieblas](https://github.com/Julieblas) for an idea). It make sense to use this function inline like here:
#### Results: `r insert_score()` out of 13
The previous line was generated with the following code:
```{markdown}
#### Results: `r insert_score()` out of 13
```
This function can be located anywhere on your page (before the questions, after the questions, even in the middle), however right now it doesn't work, if there are multiple instances of this function call per page.
### 1.2 Give some hints with the `check_hint()` function
Sometimes you know in advance what kind of mistakes will your students do. Some students are shy and don't like asking questions, so hints could partially solve this problem. Again all you need is to create a following chunk with the chunck atribute `results='asis'` in your `rmarkdown` document:
```{r}
check_hint("You can use the rmarkdown package")
```
Of course it is possible to change the message of the part that should be clicked, just use the `hint_title` argument:
```{r}
check_hint("You can use the rmarkdown package inside checkdown",
hint_title = "🔎 CLICK HERE")
```
By default you need to click on the hint in order to make it appear, but this behaviour can be changed with the `type` argument:
```{r}
check_hint("You can use the rmarkdown package inside checkdown",
hint_title = "🔎 Put mouse over here",
type = "onmouseover")
check_hint("You can use the rmarkdown package inside checkdown",
hint_title = "🔎 Double click here",
type = "ondblclick")
```
It is possible to use Markdown inside messages:
```{r}
check_hint("- You can use `markdown` **inside** the [`chcekdown` package](https://agricolamz.github.io/checkdown/)",
hint_title = "Click he`R`e")
check_question(answer = 4,
wrong = "a**R**e you su**R**e?",
right = "### `R`ight")
```
There is also a function for multiple hints:
```{r}
check_hints(hint_text = c("look into the hint 2", "look into the hint 1"),
hint_title = c("hint 1", "hint 2"),
list_title = "list of hints")
```
It is worth mentioning that `\n` will be removed from `hint_text` and `hint_title` arguments, so in case you want to have a new line use html tag `
`.
```{r}
check_hint(hint_text = "this
is
a
multiline
sentence")
```
## 2. Inserting images
Sometimes it is nice to use images as a question. It also could be useful to insert images in hints. In order to do it you need to use `insert_images()` function, and enumerate the correct answer.
```{r, eval=FALSE}
check_question(answer = 3,
type = "radio",
options = insert_images(c("windows.png",
"mac.png",
"linux.png"),
image_width = 30))
```
Arguments `image_width` and `image_height` also except vector of values in case you need different size for different pictures.
In case you want to use pictures within hints, it is better to use markdown markup for it:
```{r, eval=FALSE}
check_hint("Here is a map:
{width=10%}")
```
## 3. Some important notes
- It is possible to avoid code in the output `.html`. Just use the chunk argument `echo=FALSE`.
- It is possible to reduce values for `type` and `alignment` arguments to the first letter (e. g. `type = "s"` instead of `type = "select"`).
- For now the package `checkdown` works only with html output and will not print anything for other outputs.
- Be careful with number precision: printing could be different on different computers so if you ask your students to calculate `log(3/4)`, it is possible that they will see only 6 or 7 numbers after the comma. So it make sense explicitly specify precision using `round()` function. In that case it make sense to use the `placeholder` argument signaling to students information about number of symbols after the comma).
```{r}
log(3/4)
check_question(answer = round(log(3/4), 5), placeholder = "0.12345")
```