Adding quizzes

To make labs more interactive, you can add activities to your instructions. There are different types of activities that can test the knowledge and capabilities of the user.

Quizzes are a way to test what knowledge a user has retained from the instructions. The user will attempt to answer questions correctly on one or several topics.

Quizzes can consist of multiple questions, which can be of a variety of question types e.g. multiple choice, numeric answer, etc.

Defining questions

Lets start by defining some questions that can later be included into a quiz. Question resources consist mostly of the same fields, but depending on their type there can be minor differences. Depending on the question type, they will have a different field type as answer, and they can contain additional settings.

In the root directory of your lab, create a file to contain all your quizzes quizzes.hcl, and add a single_choice_question resource named "capital_france" to it.

resource "single_choice_question" "capital_france" {
}

The single_choice_question resource presents a question to the user, with multiple possible answers. The user can then pick a single answer from the possible answers. The question to ask the user is specified with the question field e.g. "What is the capital of France?", and the answer is specified as a string value e.g. "Paris". To add additional possible incorrect answers that the user can choose from, you can specify the distractors field, which is a list of string values e.g. ["Lyon", "Nantes", "London", "Berlin"].

resource "single_choice_question" "capital_france" {
  question = "What is the capital of France?"
	answer = "Paris"
	distractors = ["Lyon", "Nantes", "London", "Berlin"]
}

If you want to give the user hints when they submit an incorrect answer, you can do this on any type of question by providing a list of hints. These hints will be shown to the user in the order that they are specified within the list.

resource "single_choice_question" "capital_france" {
  question = "What is the capital of France?"
	answer = "Paris"
	distractors = ["Lyon", "Nantes", "London", "Berlin"]

	hints = [
		"The correct answer is Paris .",
		"No, really, it's Paris ..",
		"Just pick Paris already ..."
	]
}

Add an additional question resource to the config, this time a multiple_choice_question named "cities_france", which asks the question "Which of these cities are in France?".

resource "multiple_choice_question" "cities_france" {
	question = "Which of these cities are in France?"
}

Because it is a multiple choice question, the user is able to submit multiple answers and the correct answer will also consist of multiple values. This means that the answer field for the multiple_choice_question resource is a list of strings instead of a single string value specified for the single_choice_question. Multiple choice questions can also show additional possible incorrect answers to the end user, using the distractors field.

resource "multiple_choice_question" "cities_france" {
	question = "Which of these cities are in France?"
	answer = ["Paris", "Lyon", "Nantes"]
	distractors = ["London", "Berlin"]
}

To give the user hints when they submit the wrong answer, add some hints.

resource "multiple_choice_question" "cities_france" {
	question = "Which of these cities are in France?"
	answer = ["Paris", "Lyon", "Nantes"]
	distractors = ["London", "Berlin"]

	hints = [
		"One of these cities is in the UK",
		"Another city is in Germany"
	]
}

Add a quiz resource

To tie all the questions together, we need to use them in a quiz resource. This resource specifies which questions to ask and configures controls such as the number of attempts possible, and whether or not to show hints.

Add a quiz resource named "france" to the quizzes.hcl file.

resource "quiz" "france" {
}

To add questions to the quiz you need to specify the questions field, which holds a list of references to the questions themselves. Add the questions you created previously (resource.single_choice_question.capital_france and resource.multiple_choice_question.cities_france) to the quiz you just created.

resource "quiz" "france" {
	questions = [
			resource.single_choice_question.capital_france,
			resource.multiple_choice_question.cities_france,
		]
}

In order to show the hints that you specified on each of the question resources to the end user, you need to enable the showing of hints on the quiz by setting show_hints to true.

resource "quiz" "france" {
	questions = [
		resource.single_choice_question.capital_france,
		resource.multiple_choice_question.cities_france,
	]

	show_hints = true
}

Embed the quiz on a page

You have now configured different types of questions and used them in a quiz. But to show the quiz to the end user, you need to embed it in the instructions.

Lets start by creating a new page markdown file instructions/quiz.md and add some content to it e.g.

# Quizzes

To test a user's knowledge, you can add quizzes to the content.
Quizzes can contain multiple questions of different ypes.
All questions in a quiz need to be answered correctly in order for the user to be able to proceed.

In order to embed the quiz on the page, you need to add the instruqt-quiz component into the markdown content. The only parameter the instruqt-quiz component needs is an id that maps a unique id within the page e.g. "france" to a quiz resource reference e.g. resource.quiz.france. This makes it possible to create modules containing a library of questions and quizzes that can be reused within instructions without hardcoding the references in the markdown content.

# Quizzes

To test a user's knowledge, you can add quizzes to the content.
Quizzes can contain multiple questions of different ypes.
All questions in a quiz need to be answered correctly in order for the user to be able to proceed.

<instruqt-quiz id="france"></instruqt-quiz>

Now that you have the markdown file with the embedded quiz component, you need to create a page resource to use the markdown. Add a page resource named "quiz" to pages.hcl, and set the file field to point at the newly created markdown file.

resource "page" "quiz" {
  file = "instructions/quiz.md"
}

In order to complete the mapping of the quiz resource to the instruqt-quiz component. You do this by specifying the activities map, which sets the chosen id to a reference of the resource.

For instance if you had a quiz resource.quiz.my_quiz and specified the following component <instruqt-quiz id="something"></instruqt-quiz>, the necessary mapping in the activities map would be something = resource.quiz.my_quiz.

In the activities map, you can map as many activities (quizzes and tasks) as you want to use within the page.

resource "page" "quiz" {
  file = "instructions/quiz.md"

  activities = {
    "france" = resource.quiz.france
  }
}

The questions are validated separately, but the user can only proceed when all of them are correct.

Adding the page to the outline

In order for the page to show up within the instructions, you need to add it to the outline. Lets add the "quiz" page to the "introduction" chapter and reference your newly created page resource.

resource "lab" "main" {
  ...
  content {
    ...
    chapter "introduction" {
      ...
      page "quiz" {
        reference = resource.page.quiz
      }
    }
  }
}

Preview your changes

Like in the previous section, you can validate your changes using instruqt lab validate, and then git add, git commit, and git push the changes to GitHub. You can then go to the "Labs" section, verify the latest commit on GitHub matches the status of your lab, and start the lab.

Your lab should now have an additional page in the "introduction" chapter. The second page should display the quiz component and show the questions you have defined.

Try interacting with the quiz to see how it behaves when you submit the wrong answer, a partially wrong answer, and when you complete it.

Once you are done exploring your lab, click the "Stop" button at the top right of the Lab UI to shut down your lab environment and go back to the "Labs" list.