learnitdown - R Markdown and Bookdown Additions for Learning Material
Philippe Grosjean (phgrosjean@sciviews.org)
2022-05-10
Source:vignettes/learnitdown.Rmd
learnitdown.RmdMake better learning inline material with learnitdown
R Markdown, and especially bookdown with the gitbook format are extensively used by the R community for textbook documentation. The {learnitdown} package aims to transform bookdown/gitbook into an interactive learning environment with a rich set of functions like H5P content, differed Shiny and learnr app starting, course-specific areas, etc.
Include H5P content
H5P content is rich interactive content for e-learning. It is written in HTML5 (HTML + CSS + Javascript). The H5P content is displayed in an iframe inside your document, and it sends xAPI events (a standard to pass “experience API” event to LRS -Learning Record Store-). The parent page is responsible of handling these events. Here, the parent is our R Markdown or bookdown pages. With {learnitdown}, you can make it work by incorporating your {bookdown} material within a Wordpress site that also manages the H5P exercises.
h5p(1, "https://www.example.com", width = 780, height = 500)Differ Shiny/learnr app loading
When a page with Shiny apps or learnr tutorials is loaded, the applications are automatically started. While it may seen nice, it slows down page loading and it uses unnecessary resources on the Shiny server if the application is not used. In {learnitdown}, a mechanism is provided to display only a screenshot image of the application, and to load the actual Shiny application only if the image is clicked (and then, the image is replaced by the Shiny application). This trick is done by coupling an image and a Shiny app and with a little bit of CSS and Javascript on the client-side. All this is hidden in a function that you call in an R Markdown document in an isolated R inline expression (expression on its own line, surrounded by blank lines above and below it).
Selectively show details
A long, monotonously linear textual development, a.k.a., textbook has proven useful for software documentation. Organization in chapters and sections with an easily available table of content is enough to find and read the sections of interest in the document. In a learning context, the same document appears boringly long. More diversification and interactivity brings live to the learning material.
An easy way to break with the linear monotony of a textbook is to show or hide details in the text. Four complimentary mechanisms are provided: details, tabs, contextual sections, and show/hide code. We will demonstrate them here.
Details
If you want to hide details, but allow the reader to reveal them at will in your page, you can use the <details>...</details> tag. Everything that is enclosed inside these tags will be hidden by default, with a “Details” marked inviting to open the details section. Using <summary>...</summary> at the very beginning of the <details> section allows for custom text in collapsed mode. Here is an example:
For more details, unfold me…
Here are the details, possibly with multiple paragraphs and other formattings:
- A list item 1
- Item 2
Also an equation:
\[E = m \times c^2\]Tabs
With a little bit of CSS, it is possible to transform titles into tabs or ‘pills’ that display or portion of the page. Since it uses bootstrap CSS, it is not available in bookdown’s gitbook format, except if the corresponding code is injected oi your document. TODO: example + injection of that code in bookdown.