How to write a plugin for SimpleQuiz

Why write a plugin for SimpleQuiz?

One common reason would be to manipulate quiz results, e.g. log them to an external system, or database. Another reason would be to highly customize the quiz view, the quiz results or the emails sent to the administrator or user. This feature is available from SimpleQuiz version 1.10 onwards.

Quiz lifecycle explained

When a user visits the Quiz page, SimpleQuiz renders the quiz pre-text, the timer, the questions, and the user details fieldset according to its position. When the user submits the quiz, the front-end model of SimpleQuiz checks the required user fields, evaluates the question answers, and then passes on to the view, which is now in result mode. First, the detailed question results are rendered, and then kept in memory, so that they can be used in both the generated emails and the printed results.

Afterwards, the quiz total score is assigned according to the Quiz type, and the Quiz is characterized as either Completed or Failed. If the Quiz is completed, the onQuizCompleted event is triggered, and consequently the onBeforeFilterCompleteText and onAfterFilterCompleteText events. If the Quiz is failed, the onQuizFailed event is triggered, among with the onBeforeFilterFailText and onAfterFilterFailText events. These events allow for a high customization of the Complete and Fail Texts.

SimpleQuiz Quiz Lifecycle

Events

Here is an exhaustive list of the available events, with their respective parameters. Please note that the Quiz object is passed as a reference on every event, and it contains all the available information. Manipulating the quiz object WILL result in varied results, so please be very careful as to what you do with it.

onBeforeRenderQuiz(&$quiz, &$user_id, &$instance_id, &$uid)
onBeforeRenderQuestion(&$quiz, &$user_id, &$question, &$question_number)
onAfterRenderQuestion(&$quiz, &$user_id, &$question, &$question_number)
onAfterRenderQuiz(&$quiz, &$user_id, &$instance_id, &$uid)
onBeforeCheckFields(&$quiz, &$user_id)
onBeforeEvaluateAnswers(&$quiz, &$user_id, &$results)
onAfterEvaluateAnswers(&$quiz, &$user_id, &$results)
onBeforeRenderDetailedResults(&$quiz, &$user_id)
onAfterRenderDetailedResults(&$quiz, &$user_id, &$detailed_result_html)
onBeforeRenderResultPage(&$quiz, &$user_id)
onQuizCompleted(&$quiz, &$user_id, &$quiz_type, &$score)
onQuizFailed(&$quiz, &$user_id, &$quiz_type, &$score)
onBeforeFilterCompleteText(&$quiz, &$user_id, &$complete_text, &$coptions)
onAfterFilterCompleteText(&$quiz, &$user_id, &$complete_text, &$coptions)
onBeforeFilterFailText(&$quiz, &$user_id, &$fail_text, &$coptions)
onAfterFilterFailText(&$quiz, &$user_id, &$fail_text, &$coptions)
onBeforeSendAdminEmail(&$quiz, &$user_id, &$from_email, &$from_name, &$recipient, &$mail_subject, &$mail_body)
onBeforeSendUserCopyEmail(&$quiz, &$user_id, &$from_email, &$from_name, &$recipient, &$mail_subject, &$mail_body)

Important note: SimpleQuiz does not always requires users to be logged-in to take quizzes. As such, the User ID is not always an actual Joomla User ID. If the user is not logged in, a NEGATIVE random number is stored in the session as the User ID, and SimpleQuiz uses that, instead, as the User ID.

Plugin details

The plugin must be installed in the directory JPATH_ROOT/plugins/simplequiz/[your plugin]. If that directory does not exist, create it and put your plugin within that directory. The .php file class should be something like class plgSimplequizExample extends JPlugin or plgSimplequizExample extends CMSPlugin, depending on your Joomla version. Use CMSPlugin for Joomla 4 and above.

Download an example plugin here.