openwashdata Course Quizzes

This directory contains interactive learnr quizzes for the openwashdata course and a landing page to access them.

Live Demo: https://hjj91u-nicolo-massari.shinyapps.io/openwashdata-quiz-hub/

Structure

• app.R - Quiz landing page that automatically displays all configured quizzes
• build.R - Deployment script with helper functions for automated deployment
• config.R - Shared configuration file defining all available quizzes
• modules/ - Directory containing all quiz files
  • md-01-quiz.Rmd - Module 1 quiz on Quarto basics (learnr tutorial)
  • _github_username.Rmd - Reusable component for GitHub username input with CSV data
  • _submission.Rmd - Reusable component for quiz submission
  • github_usernames.csv - Student GitHub username database
  • Additional quiz files can be added as md-XX-quiz.Rmd

Required Packages

Make sure these packages are installed:

All required packages are defined in DESCRIPTION and automatically installed during deployment. For local development:

# Install from DESCRIPTION file
devtools::install_github("ds4owd-dev/quiz")

ShinyApps.io Authentication

Before deploying, you need to authenticate with shinyapps.io:

1. Get your account credentials from https://www.shinyapps.io/admin/#/tokens
2. Set up authentication in R:

rsconnect::setAccountInfo(
  name = 'your-account-name',
  token = 'YOUR-TOKEN-HERE',
  secret = 'YOUR-SECRET-HERE'
)

Replace your-account-name, YOUR-TOKEN-HERE, and YOUR-SECRET-HERE with your actual credentials.

Google Form Integration

The quizzes now include automatic submission to Google Forms for tracking student progress:

Features

• GitHub username collection: Students enter their GitHub username at the start
• Learnrhash generation: Quiz responses are encoded using learnrhash
• Automatic submission: Results are submitted to Google Form via POST request
• Modular components: Reusable username and submission components

Configuring Google Form Integration

To connect quizzes to your own Google Form, update the configuration in modules/_submission.Rmd.

0. Google Form Structure

Your Google Form should have exactly 3 questions:

1. Tutorial/Module ID (text field)
2. GitHub username (text field)
3. Learnrhash (long text field for quiz results)

1. Find Entry IDs

To get the entry IDs for your form fields:

1. Open your Google Form (the live form, not edit mode)
2. Open browser inspector (F12 or right-click → Inspect)
3. Search for "entry" in the HTML (Ctrl+F)
4. Copy the entry IDs - they appear as entry.1234567890

The entry IDs will be in the order your questions are set up in the form.

2. Update form_url and Entry IDs

Update the variables at the top of modules/_submission.Rmd:

# Google Form setup
form_url <- "https://docs.google.com/forms/d/e/YOUR-FORM-ID/formResponse"

# Entry ID mappings
tutorial_id_entry_id <- "entry.YOUR-MODULE-ID"         # For module name
github_username_entry_id <- "entry.YOUR-USERNAME-ID"   # For GitHub username
learnrhash_entry_id <- "entry.YOUR-LEARNRHASH-ID"      # For quiz results

Example Current Setup

• Form URL: https://docs.google.com/forms/d/e/1FAIpQLScnw9R8wMU5SfFqNVXGeEkiIygLTB_Dc6jWBmbwEeHuekBDzg/formResponse
• Entry IDs:
  • entry.1169139257 - Module name (1st question)
  • entry.61564704 - GitHub username (2nd question)
  • entry.1315905314 - Learnrhash (3rd question)

Deployment Process

Automated Deployment (CI/CD)

Quizzes are automatically deployed to shinyapps.io via GitHub Actions when changes are pushed to the main or dev branches.

Setting Up Automated Deployment

1. Get shinyapps.io credentials:

   • Go to shinyapps.io → Account → Tokens
   • Click "Add Token" to generate new credentials
   • Copy the name, token, and secret values

2. Configure GitHub Secrets:

   • Go to your GitHub repository → Settings → Secrets and variables → Actions
   • Add these repository secrets:
     • SHINYAPPS_ACCOUNT: Your shinyapps.io account name
     • SHINYAPPS_TOKEN: The token from shinyapps.io
     • SHINYAPPS_SECRET: The secret from shinyapps.io

3. Add new quizzes to automated deployment:

   • Edit config.R and add your new quiz:

   quiz_names <- c(
     "md-01-quiz",
     "md-02-quiz"  # Add new quiz here
   )

How the CI/CD Workflow Works

The GitHub Action (.github/workflows/deploy-quiz.yml):

• Triggers: On pushes to main/dev branches or manual workflow dispatch
• Environment: Sets up R 4.3.2 with required packages from DESCRIPTION
• Authentication: Uses repository secrets to authenticate with shinyapps.io
• Deployment: Executes build.R to deploy all applications defined there
• Logging: Uploads deployment logs if any failures occur

Manual Deployment

For manual deployment, simply run the build script which handles everything automatically:

# Deploy all quizzes and landing page
source("build.R")

The deployment system features:

• Automatic file bundling: CSV files and dependencies are automatically included
• Streamlined process: One script deploys everything configured in config.R

Adding New Quizzes

The system now uses automatic configuration - adding a new quiz is simple:

1. Create the Quiz File

Create modules/md-02-quiz.Rmd with the standardized YAML header:

---
title: "Module 2: Your Title"
output: learnr::tutorial
runtime: shiny_prerendered
description: "Your quiz description"
tutorial:
  id: "module2-your-id"
---

Add your quiz content following the existing pattern, including:

• GitHub username collection: {r github-username, child='_github_username.Rmd'}
• Quiz submission: {r submission-section, child='_submission.Rmd'}

2. Update Configuration

Edit config.R to include your new quiz:

quiz_names <- c(
  "md-01-quiz",
  "md-02-quiz"  # Add new quiz here
)

3. Deploy

Run the build script to deploy everything:

source("build.R")

This will:

• Automatically deploy the new quiz
• Update the landing page to show the new quiz

Local Testing

Test Individual Quizzes

# Test a quiz locally
rmarkdown::run("modules/md-01-quiz.Rmd")

Test Landing Page

# Test the landing page locally
shiny::runApp()

Student Access

Students access the system through:

1. Landing page: Main hub showing all available quizzes
2. Individual quizzes: Full learnr tutorials with interactive exercises, hints, and automatic grading

Each quiz runs independently and provides the complete learnr experience including progress tracking within that session.