====== Quiz Plugin ======

---- plugin ----
description: Lets you add quizzes and test a wiki page
author     : Luigi Micco 
email      : l.micco@tiscali.it
type       : syntax
lastupdate : 2010-12-07
compatible : Lemming
depends    : 
conflicts  : 
similar    : multipoll, poll
tags       : quiz, test

downloadurl: https://trello.com/1/cards/5b04744056558c97e7974462/attachments/5b04745c5b314252cef046aa/download/quiz-2010-12-07.zip
bugtracker : 
sourcerepo : 
donationurl: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=KHHGCTLSQPGEJ

screenshot_img: 
----

===== Download and Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually. If you do install manually the directory must be named ''quiz''.

===== Version history =====

  * **2010-12-07** (//current//) 
    * Removed all know bugs at this time (thanks to many users !!)
  * **2010-09-17** 
    * Some little bugs on language files (English and French)
  * **2010-09-14**
    * Rewritten Javascript/Ajax core
    * Rewritten part of code to avoid conflit with other plugins
  * **2010-09-11**  
    * Bug removed on javascript
    * Add French language
  * **2010-08-26** 
    * First public release.
    * Italian and English language

===== Syntax and usage =====

Use this plugin to add a quiz to a wiki page. The syntax looks like this:

  {{quiz>quiz_page&param1&param2&...&paramN}}

where //paramX// can be one or more from follow list and //quiz_page// is the ID of a wiki page ([[#example|like this]]) that contain the quiz:

^ learning       | show correct answers at the end of quiz | optional |
^ showintro      | show quiz intro on every question | optional |
^ rndquest       | shuffle random of question's order | optional |
^ rndchoice      | shuffle random of choice's order on every question | optional |
^ highscores     | show a button to view the 10 best scores | optional |

===== Syntax of quiz page =====
To make a quiz, create a page, with a syntax looks like follow.

You can define a **title** (using Headline Level 1 <nowiki>====== Title ======</nowiki>) and a **intro** for whole quiz

<code>
====== Title of quiz ======
Quiz intro text. Quiz intro text. Quiz intro text. Quiz intro text. Quiz 
intro text. Quiz intro text. Quiz intro text. Quiz intro text. Quiz intro 
text. Quiz intro text
</code>

For every quiz, You can define **one or more questions** (using bullet <nowiki>  *</nowiki>):

<code>
    * Test of question
</code>

For every question, **one or more optional choices** (using bullet <nowiki>  -</nowiki>). If no choices is defined, the question will be a free answer (text) type

<code>
      - choice 1
      - ....
      - choice N
</code>

**one or more correct answers** (using second level bullet and brackets, delimited with | <nowiki>    * [a1|a2|...|aN]</nowiki>). If two or more correct answers is defined, the question will be multi-answers (checkbox) type. If only one is defined, the question will be single answer (radio) type.

<code>
      * [1|2]   
</code>

**a optional score** (using second level bullet and parenthesis <nowiki>    * (N)</nowiki>) 

<code>
      * (5) 
</code>

and **a optional explanation**

<code>
      * explanation 
</code>

For every quiz, you can define **one or more scores explanation** (using Headline Level 2 <nowiki>===== minN-maxN =====</nowiki>), for total score in the range [minN,maxN]. If defined, will be displayed at the end of the test, along with correct answers.

<code>
===== 1-20 =====
Explanation for score in the range [1,10]
</code>

For intro, questions, choices, explanation and scores explanation it's possibile to use wiki syntax.



===== Example =====


<code>
====== Quiz title ======
Quiz intro text. Quiz intro text. Quiz intro text. Quiz intro text. Quiz 
intro text. Quiz intro text. Quiz intro text. Quiz intro text. Quiz intro 
text. Quiz intro text. 

Quiz intro text. Quiz intro text. Quiz intro text. Quiz intro text. Quiz 
intro text. Quiz intro text. Quiz intro text. Quiz intro text. Quiz intro 
text. Quiz intro text. 


  * Question 1 description (multi answers - checkbox)
    - choice 1     <-- choice 1
    - ....
    - choice N     <-- choice N
    * [1|2]        <-- right answers (one or more, | delimited) 
    * (10)         <-- score
    * explanation  <-- optional

  * Question 2 description (single answer - radio)
    - choice 1     <-- choice 1
    - ....
    - choice M     <-- choice M
    * [2]          <-- right answer (from 1 to M)
    * (5)          <-- score
    * explanation  <-- optional

  * Question 3 description (single answer - text)
    * [Pippo]      <-- right answer
    * (20)         <-- score
    * explanation  <-- optional

===== min1-max1 ===== <-- optional
Explanation for score in the range [min1,max1]

===== min2-max2 ===== <-- optional
Explanation for score in the rangen [min2,max2]

....

===== minN-maxN ===== <-- optional
Explanation for score in the range [minN,maxN]

</code>
===== Other =====
The quiz plugin makes use of background [[wp>Ajax_(programming)|AJAX]], so you don't have to reload the whole page each time on every question.

The quiz title is converted to a md5sum. This is used as the filename in data/meta to store the highscores: md5sum.quiz - so all quiz in the whole wiki must be unique. As a result you can move your quiz around and the quiz data is accessible. If you remove the quiz you must remove the quiz data with “rm”.

===== Discussion ======
There's always room for improvement. If you're able to add any contributions to make this plugin  better, please [[l.micco@tiscali.it|let me know]] or discuss your thoughts right here (please use ''<nowiki>===== Level 3 Headlines =====</nowiki>'' to open a new "thread"/issue and ''<nowiki>----</nowiki>'' (four dashes, horizontal rule) to structure it when needed).

==== Disappearing questions ====
When I create quiz in playground (based on provided sample quiz), answers sometimes appears and then rapidly disappears (being replaced with blank "start quiz" or "continue" button, I don't remember exacly) while answering. Tested on IE8/Chrome8, sometimes this bug appears, sometimes not.

==== [SOLVED] Error on line 194 in class_quiz.php ====
Instead of resulttext ("you anwered correctly ... of ... questions") this kind of error message appears. Total score is displayed, though. Error message: "Warning: sprintf() [function.sprintf]: Too few arguments in C:\xampplite\xampplite\htdocs\dokuwiki\lib\plugins\quiz\class_quiz.php on line 194".

Fix by replacing line 13 of lang/en/lang.php:
<code>
  $lang['quiz_resulttext']  = "You answered %d out of %d questions correctly (%d %)";
</code>
with:
<code>
  $lang['quiz_resulttext']  = "You answered %d out of %d questions correctly (%d %%)";
</code>
> fixed with new version  --- [[user>mluigi]] //2010/12/07 09:30//
==== Recursion hang ====
When //quiz// command is linking on the same page where it was called from, Dokuwiki halts. Perhaps you should add internal check to avoid it.

==== [SOLVED] Error on line 200 in class_quiz.php ====

When not defining optional scores explanation ( using Headline Level 2 ===== minN-maxN ===== ), this kind of error message appears. Total score is displayed, though. Error message: "Warning: Invalid argument supplied for foreach() in C:\wamp\www\dokuwiki\lib\plugins\quiz\class_quiz.php on line 200".

Fix by replacing line 200 from class_quiz.php:
<code>
  foreach ($data['scores'] as $scores) {
</code>
with:
<code>
  if ($data['scores'])
    foreach ($data['scores'] as $scores) {
</code>
> fixed with new version  --- [[user>mluigi]] //2010/12/07 09:30//
==== [SOLVED] learning quiz mode not working ====

Using //learning// parameter when adding a quiz to a wiki page does not work (correct answers are not shown at the and of quiz).

Fix by replacing the following lines:
  * getform.php:24 : from <code> $param['quizmode'] = $_POST['quiz_mode'];</code> to <code>$param['learning'] = $_POST['quiz_learning'];</code>
  * class_quiz.php:100 : from <code>$html .= '<input type="hidden" name="quiz_mode" value="' . $this->mode. '">' . "\n";</code> to <code> $html .= '<input type="hidden" name="quiz_learning" value="' . $this->mode. '">' . "\n";</code>
  * class_quiz.php:50 : from <code>$this->mode = $param['quizmode'];</code> to <code>$this->mode = $param['learning'];</code>

> fixed with new version  --- [[user>mluigi]] //2010/12/07 09:30//
==== [SOLVED] HTML code for {{quiz>...}} is not correctly generated ====

If inserting ''%%{{quiz>...}}%%'' in its own dokuwiki section, clicking "edit" for that section will start the quiz.

Fix by replacing lines 114,115 from class_quiz.php:
<code>
  $html .= '</div>';
  $html .= '</div>';
</code>
with:
<code>
  $html .= '</div>';
  $html .= '</form>';
  $html .= '</div>';
</code>
> fixed with new version  --- [[user>mluigi]] //2010/12/07 09:30//

==== How exactly to link the quiz page? ====

I can't figure out how to link a quiz command (quiz> ...) to a quiz wiki page - like stated [[http://www.dokuwiki.org/plugin:quiz?&#syntax_and_usage | here]]

The "quiz_page" reference is a wiki namespace path? How would this command look like if I want to add a quiz from here (this page), to this [[http://www.dokuwiki.org/plugin:quiz:example | example quiz page]]

Somenthing like this?
{{quiz>plugin:quiz:example}}

==== Longer questions and more detail ====

I wanted some way to add more detail to questions and explanations.  Questions can have additional bullet points added by adding a list item called "Detail" and sub-bullets will be added to the question.  They must not extend additional levels.  Second, the explanation is similarly extended by defining sub-bullets on the normal explanation line.  My test page: [[http://www.siliconpr0n.org/wiki/doku.php?id=quiz:metal_gate_cmos|http://www.siliconpr0n.org/wiki/doku.php?id=quiz:metal_gate_cmos]]

Example usage:
  * Pop the question here
    * Detail
      * More details, images etc
      * More details, images etc
      * More details, images etc
    - Item 1
    - Item 2
    * [1]
    * (1)
    * Main explanation
      * More details, images etc
      * More details, images etc
      * More details, images etc

Source diff against quiz-07.12.2010.zip:
  428c428,442
  <               
  ---
  >             # Like explanation except with a special key
  >             } elseif (strtoupper(substr($lines[$k], 0, 12)) == "    * DETAIL") {
  >               $tmp = '';
  >               while($k < $nr - 1) {
  >                     $l = $lines[$k + 1];
  >               
  >                     if (substr($l, 0, 8) == "      * ") { 
  >                             # Keep it as a list, just shift it
  >                             $tmp .= $hRender->render(str_replace("      * ","  * ",$l)) . "\n";
  >                             $k += 1;
  >                             } else {
  >                                     break;
  >                             }
  >               }
  >               $quizz['questions'][$nquest]['question'] .= $tmp;
  436a451
  >               # Doesn't the above subst take care of this?
  440c455,470
  <               $quizz['questions'][$nquest]['explanation'] = $tmp;
  ---
  >                       $exp = $tmp;
  >               
  >               $tmp = '';
  >               # Extended explanation?  Peek to see if there is continuation
  >               while($k < $nr - 1) {
  >                     $l = $lines[$k + 1];
  >               
  >                     if (substr($l, 0, 8) == "      * ") { 
  >                             # Keep it as a list, just shift it
  >                             $tmp .= $hRender->render(str_replace("      * ","  * ",$l)) . "\n";
  >                             $k += 1;
  >                             } else {
  >                                     break;
  >                             }
  >               }
  >                   $quizz['questions'][$nquest]['explanation'] = $exp . $tmp;

 --- [[user>johndmcmaster|JohnDMcMaster]] //2012/05/24 10:08//
===== Displays title even if not given =====

Thanks for a simple quiz plugin! One question, even if I don't set a title for my quiz, the pagename will show up as the title. I wonder if it is possible to "fix" this, as I would like to have only one title per quiz page, and that should be the master page's title. It is important as I use page titles for navigation, although I can work around by using the meta plugin to set a title for the master page. I hope this makes sense. Thanks for clarification in advance! ---Eivind

===== Random question and choice work only once =====
I have tried this plugin and notice that with "rndquest" and "rndchoice" shuffle the order of questions and choice first time and then on every reload of the page it remain the same. Is there any option that on every reload it suffle the questions and choices or may be I am missing something.

===== Any plans for making this work for new releases =====
The plugin is really useful to make Dokuwiki a useful tool for learning. I would appreciate someone can make this work again for new release of Dokuwiki.

===== Malware in Demo link =====

Attempting to view the example page for this plugin takes you to a site that attempts to install malware!
> If this was true, it should be put to the very top of the page, not at the end. But I just tried the Demo link, and it simply went to one of those holding pages when a domain expired, and I didn't experience any malicious attempt to install anything. --- [[user>ach|Anika Henke]] //2014/03/23 11:50//
>> I've just removed the link to the Demo as it was broken since over a year anyway. --- [[user>ach|Anika Henke]] //2014/03/23 12:53//

===== Error  in plugin =====
Not Found

The requested URL /getform.php was not found on this server.

it is not directing to right link .

Please help to resolve the issue