Embed question filter
=====================

This filter allows questions from the question bank to be embedded
anywhere that users can input HTML. This can be used in various ways.
For example, it can be a way to make learning materials more interactive.


Setup
=====

The admin will need to

1. Go to Site administration -> Plugins -> Filters -> Manage filters
  and Enable the Embed questions filter.

2. Go to Site administration -> Plugins -> Filters -> Embed questions,
  and review the default options for embedded questions. No needs to
  be changed, but you may have different preferences for your site.

3. The Atto editor need to be configured to show the new button. Go to
   Site administration > Plugins > Text editors > Atto HTML editor > Atto toolbar settings
   and in the Toolbar config field, find the line that starts 'insert =',
   and add 'embedquestion' to the list.


Before you can embed a question
===============================

Questions can only be embedded from course question banks, and they
can only be embedded if they have an 'idnumber' set, and are in
a cateogry with an 'idnumber'.

Since Moodle 3.6 an idnumber field has been added to the questions and
categories forms, so when creating embeddable categories and questions:
1. Embeddable categories need to have idnumbers
2. Embeddable questions also need idnumbers and be in an embeddable category
In what follows we will assume you have done this, so you have
a category called 'Embeddable questions' with idnumber 'embeddable'
that contains a question called 'Test question1' with idnumber 'test1'
in the course with id 2.


How to embed a question
=======================

Go to anywhere where you can input HTML. For example, start adding a Page
to a course, or start writing a forum post.

1. In the editor toolbar, click the insert question button.

2. Select a question category (e.g. 'Embeddable questions').

3. Select a question (e.g. 'Test question1').

4. All the other options can be left as default, or changed as you wish.
   Note that it is only possible to select question behaviours that
   allow the user to interact with the question without the equivalent
   of the whole quiz attempt being submitted.

5. Click the Embed question button. A cryptic code will be inserted into the editor.

When you save the page, you will see that the cryptic code has been replaced by
the question, embedded in the middle of the page.

You will notice that the cryptic code ends with a 40-character hex string.
This (along with the requirement for questions and categories to have
idnumbers) is how we prevent unauthorised users from being able to guess
the embed code for a question that they should not be allowed to see.

As is normal for editor plugins (e.g. equation or image buttons work
the same way) if the input point or selection is in the middle of an
embed code when you click the button, you will edit the existing code,
otherwise, you will insert a new one.


How to embed a random question from a category
==============================================

To embed a random question, the procedure is the same as 'How to embed a question'
apart from step(3). In step (3) instead of selecting a question name you select
'Choose an embeddable question from this category randomly' (This string indicates
that you can choose a question randomly from the current category. Bear in mind,
that this string appears at the bottom of the list of question names when there is
at least 2 questions in that category).


How to embed a question without using Atto
==========================================

Normally you would use the Atto editor plugin for this as above, but
there is a stand-alone script that can help with testing. Only users
with the capability moodle/question:useall (to embed any question) or
moodle/question:usemine (to embed questions they created) can generate
the necessary embed codes using the helper script.

1. The only way to get to this script is to type the URL
   .../filter/embedquestion/testhelper.php?courseid=NNN
   in your Moodle site. (E.g. NNN = 2 for the example above.)

2. This shows exactly the same form that is shown inside the editor popup.

3. When you click the button, you will see a preview of the embedded questions,
   which can be used to check it is working the way you want. If not you can
   change the options and regenerate.

4. Once you are happy, copy the '{Q{...}Q}' bit from where it says
   'Code to embed the question:'. This can be pasted into any HTML editor
   in the same Moodle course, for example into a page resource or a forum post.


Interacting with an embedded question
=====================================

When a user encounters an embedded question, the question will
just appear inline in the page.

Technically the question is embedded in an iframe, but this
should be invisible to users. The iframe should be automatically
sized to just fit the question. Also, if embedded question is in
a region of the page that has a background colour, the contents
of the iframe should have the same background colour.

The question should work exactly as it would in a quiz
attempt, if the quiz was set up with the same
options that were used when embedding the question.

After the question has finished, there will be a Start again
button to restart the question. If the question has variants,
and the variant number is not being fixed, then a different
variant will be chosen when the question is restarted.


Miscellaneous points
====================

* Question attempts are stored in the database, but not
  permanently. There is a scheduled task 'Clean up old
  embedded question attempts' which runs once-per-hour
  (by default) to do the necessary clean-up. Attempts are
  removed after 24 hours.

* If you leave a page and come back, the question will
  start again from the beginning.

* Hence, this plugin stores no personally identifiable information,
  and implements the Moodle privacy API to document this.

* Guests are never allowed to interact with embedded questions.

* All interactions with a question (Start, View, Submit) are logged.

* If there are images in the question text, feedback, etc.,
  they will show up just fine.

* If you want to embed questions on site-wide page, they
  need to go in the 'Front page' area of the question bank.

* A a course is backed-up and restored (e.g. roll-forwards)
  the embedded questions should work in the new course.
