---
title: "Generate Questions for MyLearn"
output:
  rmarkdown::html_vignette:
    toc: true
  md_document:
    variant: gfm
    toc: true
    toc_depth: 3
  pdf_document:
    toc: true
    toc_depth: 3
    number_sections: true
  html_document:
    toc: true
    toc_depth: 3
    number_sections: true
    keep_md: true
vignette: >
  %\VignetteIndexEntry{Generate Questions for MyLearn}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
author: Darjus Hosszejni, WU Vienna
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

<!-- badges: start -->
[![R CMD check](https://github.com/hdarjus/exams.mylearn/workflows/R-CMD-check/badge.svg)](https://github.com/hdarjus/exams.mylearn/actions)
<!-- badges: end -->

# Intro

Randomized multiple-select and single-select question generation for the MyLearn teaching platform used by universities.
Question templates in the form of the [R/exams](http://www.r-exams.org/) package are transformed into MyLearn's XML format.
Note that the feedback has to stay simple, see the Issues section.
The imported questions can be organized into exams in the Learning Activities.

Dependencies:

* `libxml2`: found on popular Linux distros and in Rtools by default
* `pandoc`: gets installed by `R` during installation
* `R`: a recent version
* on Windows: Rtools
* popular `R` packages: installed automatically

The question import functionality might have to be turned on by your MyLearn support team.

# Installation

```{r, echo=TRUE, eval=FALSE}
install.packages("exams.mylearn")
```

# Demo

One creates an `R/exams` compatible exercise file similar to `example_question.Rmd`, decides for a name prefix and for the number of generated exams.

```{r, echo=TRUE, eval=FALSE}
library("exams.mylearn")
n <- 10L  # number of variants of the exercise
name <- "learn_exercise"  # prefix of the generated file names
exercise_file <- example_paths()["R_table"]
output <- exams2mylearn(filename = exercise_file,
                        n = n, dir = ".",
                        outfile = "question_table.zip")
```

The output .zip filepath is saved in `output`.
One can upload that .zip file to Learn directly (after the Learn development team has activated that feature for the given course).

# Recommended Workflow

## Writing the Question Templates

The question templates are the .Rmd files.
Find how-to's in the files returned by `example_paths()`.
Best starting point is `example_paths()["mixture"]`, that contains solutions to most features you might need in an exam question.

The recommended way of debugging the questions is via
```{r, echo=TRUE, eval=FALSE}
filename <- "potential-exercise.Rmd"
exams::exams2html(filename, n = 1L,
                  converter = "pandoc-mathjax",
                  verbose = TRUE)
```
The generated HTML file opened in the browser closely resembles the looks of the exercise on MyLearn.

## Generating the Exercises

Set the current working directory to where the exercise templates are, then run the following.
```{r, echo=TRUE, eval=FALSE}
filenames <- list.files(pattern = ".*.Rmd$")
n <- 25L
for (filename in filenames) {
  exams2mylearn(filename, n = n,
                outfile = "exam-exercises.zip",
                dir = ".", dontask = TRUE)
}
```

### Tip

If you're uploading improved exercises over and over again, I recommend executing the following `for` loop instead:
```{r, echo=TRUE, eval=FALSE}
filenames <- list.files(pattern = ".*.Rmd$")
n <- 500L
for (filename in filenames) {
  exams2mylearn(filename, n = n,
                outfile = "exam-exercises.zip",
                dir = ".", dontask = TRUE,
                distort.shortname = TRUE,
                verbose = TRUE)
}
```

This way the shortname will be unique every time and you will have more feedback on where the generation process is.

### Special Characters on Windows

The .Rmd file is assumed to have UTF-8 encoding.
That is important in case the .Rmd file contains special (e.g. German) characters.

In RStudio, one can choose the encoding for file reading under _File_ > _Reopen with Encoding_, and for file writing under _File_ > _Save with Encoding_.
It is recommended to do both with UTF-8.

## Uploading to MyLearn

In the course find _Administrate_, then under _"Old" learning materials_ click on _organize_.
Then under _XML-file_ choose the .zip file created in the previous step.
Finally, click on _Import learning materials_.

### First Upload

At the first upload a newly opened window shows a row for each exercise in the .zip file.
Those containing plots show a warning, that is normal.
By clicking on _Ansicht_, the uploaded exercise appears.

There is no way out from here, go back to the home page.

### Re-uploading with the Same Shortname

In this case a smaller list of the re-uploaded exercises is shown.
Choose all of them and click on _Submit_.
This overwrites the old versions.

## Importing Exercises

Yes, uploading and importing are different steps.
In the menu of the course's _Learning activities_, click on _Import_ > _Import of existing learning materials_.
A table of uploaded exercises appears.

Use the filters to filter out your exercises.
The most useful filters are _Already imported_ set to _No_ and the text input where you can use the unique shortnames.

Select all exercises with one click, then _Selected items_ > _Import_.
This brings you to the imported exercises.
Select all and then _Selected items_ > _Add to clipboard_.

## Organizing a Random Question on MyLearn

Create a new _Poolfolder_ in the _Learning activities_ and open it.
Click on _Clipboard_ > _Insert content here_ and then _ok_.
Release all questions in the poolfolder otherwise the random question won't work.

Now create a _Proxy_ outside of the poolfolder and associate it with the poolfolder you created.
This was the last step, congratulations!

The poolfolder contains the pool of questions that the random question will choose from.
It samples with replacement from the pool each time someone opens the question.
Poolfolders and their content are always hidden from students.

At this point I recommend that you delete the exercises in the imported view.
For that: in the menu of the course's _Learning activities_, click on _Import_ > _Import of existing learning materials_.
Delete all exercises.

# Issues

1. MyLearn handles only single select and multiple select questions.
2. "Answerlist" in the Solution block doesn't work on MyLearn.

# Maintainance

Should you find bugs or request features, please use the [Issue tracker on Github](https://github.com/hdarjus/exams.mylearn/issues).