Wiris Quizzes integration guide

Wiris Quizzes mainly targets web applications, but can also be integrated into mobile or desktop apps. There are currently some example integrations you can download as part of the respective "Getting started with Wiris Quizzes" example:

In Ruby, only a subset of the Wiris Quizzes features is available. We will discuss the Android offline integration separately. The server-side technology is used to programmatically call the Wiris Quizzes API to evaluate the student answer. With integrations with pure client-side technology (JavaScript and Flash), you also need to call the Wiris Quizzes API programmatically, but the invocation is done from the browser. This pure client-side option is less secure because the correct answer is also sent to the client browser. In any case, the ultimate evaluation of the student answer is performed by Wiris Quizzes using its web services.

This section explains how to compare the equivalence of two formulas given by plain text or MathML. We will check that x plus 1 is equivalent to 1 plus x.

First, download the getting started source code from www.wiris.com/quizzes/download/generic compatible with your technology.

Note this example connects to www.wiris.net to perform the actual computations.

The source code to compare $correctAnswer and $studentAnswer is as follows:

<?php  
require_once 'quizzes/quizzes.php';
$correctAnswer = "x+1";
$studentAnswer = "1+x";
//build a request for the service.
$builder = com_wiris_quizzes_api_QuizzesBuilder::getInstance();
$question = $builder->newQuestion();
$instance = $builder->newQuestionInstance($question);
$request = $builder->newEvalRequest($correctAnswer, $studentAnswer, $question, $instance);
//Make the remote call.
$service = $builder->getQuizzesService();
$response = $service->execute($request);
//Get the response into instance object.
$instance->update($response);
//Ask for the correctness of the 0th response.
$correct = $instance->isAnswerCorrect(0);
echo $correct;
?> 

This example depends on quizzes/quizzes.php and related files that can be found in the Getting Started for PHP package. Any or both $correctAnswer and $studentAnswer could contain MathML. For example, $correctAnswer = "<math><mi>x</mi><mo>+</mo><mn>1</mn></math>"; The importance of MathML is that it can be edited with MathType (see next section of this documentation). A complete reference of the API can be found at Wiris Quizzes API.

Students will input the answers using either a simple text box or the MathType equation editor. This section explains how to embed MathType.

<!DOCTYPE html>
<html>
  <head>
    <script src=
      "http://<your-domain>/quizzes/service.php?service=resource&amp;name=quizzes.js"
    ></script>
<script>
function displayEditor() {
  // Get [WQ] User Interface Builder.
  var builder = com.wiris.quizzes.api.QuizzesBuilder.getInstance();
  var uibuilder = builder.getQuizzesUIBuilder();
  // Build student's answer field.
  answerField = uibuilder.newAnswerField(null, null, 0);
  var answerContainer = document.getElementById("studentAnswer");
  answerContainer.replaceChild(answerField.getElement(),
                               answerContainer.firstChild);
}
window.onload=displayEditor;
    </script>
  </head>
  <body>
<!-- This input will be replaced by a MathType instance. -->
    <div style="width:500px;height:200px" id="studentAnswer"><span></span></div>
    <br>
    <input type="button" value="Get MathML"   
           onclick="alert(answerField.getValue())"/>
  </body>
</html>

The <your-domain>/quizzes/service.php URL part should point to the quizzes folder that you will find in the Getting Started package for your technology.

With this code, you will see the following MathType editing area where the toolbar contains the significant symbols for a quizzes scenario and the syntax checking is enabled.

Customizing MathType toolbar

MathType's default toolbar will be fine for many scenarios, but you will eventually want to configure the toolbar icons and other parameters. Refer to the documentation to get an idea of the available initialization parameters and the toolbar definition syntax.

Consider the example code:

...
answerField = uibuilder.newAnswerField(null, null, 0);
answerField.setEditorInitialParams({
  'toolbar':'<toolbar><tab rows="1" ref="general" empty="true">'+ 
            '<item ref="fraction"/>'+ 
            '<item ref="squareRoot"/>'+ 
            '<item ref="nRoot"/>'+ 
            '<item ref="+"/>'+ 
            '<item ref="&#215;"/>'+ 
            '<item ref="-"/>'+ 
            '<item ref="&#247;"/>'+ 
            '</tab></toolbar>', 
  });
...

That code results in this toolbar:

Custom toolbar in Wiris Quizzes

When comparing the correct answer with the student answer, it is possible to request further requirements like the "the student answer should be simplified".

Following the example, the student is asked to compute open parentheses x squared plus 3 close parentheses minus open parentheses 2 plus 2 x squared close parentheses and the correct answer should be 1 minus x squared or negative x squared plus 1 but not x squared minus 2 x squared plus 1, which is invalid because it is not simplified.

Wiris Quizzes allows using many additional criteria. For this purpose two options are possible. Either directly use the API to programmatically set the evaluation criteria or use Wiris Quizzes Studio to define it.

Option 1. Use the API

The following code creates a question object with the simplification criteria and compares the student answer with the correct one. The highlighted line is the only change from the code to simply compare the correct and the student answers.

<?php
require_once 'quizzes/quizzes.php';
$correctAnswer = "-x^2+1";
$studentAnswer = "1-x^2";
$builder  = com_wiris_quizzes_api_QuizzesBuilder::getInstance();
// Read question
$question = $builder->newQuestion();
$question->addAssertion("check_simplified", 0, 0, null);
$instance = $builder->newQuestionInstance($question);
// Create question request
$questionRequest = $builder->newEvalRequest($correctAnswer,$studentAnswer,$question,$instance);
// Send the xml request data
$service  = $builder->getQuizzesService();
// Call the web service
$response = $service->execute($questionRequest);
// Get the response into the instance object.
$instance->update($response);
// Ask for the correctness of the 0th response.
$correct = $instance->isAnswerCorrect(0);
echo $correct;
?>

You can find the complete list of assertions and their parameters at https://www.wiris.net/demo/quizzes/assertions.xml.

Option 2. Use the Wiris Quizzes Studio

This option allows the author to use Wiris Quizzes Studio to create the definition of the question, save the question definition as an XML file, and import this file into the Wiris Quizzes API.

Step 1. Obtaining the question XML

You can get the description of the question via Wiris Quizzes Studio. The question description XML is an .xml file that describes how the student answer will be evaluated. The most common scenario will be to compare the students answer with the correct one. Note the correct answer is not necessarily part of the question description which means that a single question description can be used by many different correct responses.

To use Wiris Quizzes Studio, visit http://www.wiris.com/quizzes/docs/generic/run/php/level3.php and you will get:

Getting the question XML from Wiris Quizzes Studio

Press the icon Wiris Quizzes icon to open Wiris Quizzes studio.

Type the Correct answer 1 – 2x² + x² to ensure the question works OK.

Move to the Validation tab and select "is simplified".

In the Preview tab, try other possible student answers. You'll see –x² + 1 is a valid response

and 1 - 2x² + x² is wrong because it is not simplified.

Now, we will get the Question XML. Click the Export button at the left bar and a file named "wirisquestion.xml" will be downloaded into your default Downloads folder, with the Question XML definition in it.

Step 2. Using the question definition in your program

The following code loads the question definition from "wirisquestion.xml" and evaluates the student answer:

<?php 
require_once 'quizzes/quizzes.php';
$correctAnswer = "-x^2+1";
$studentAnswer = "1-x^2";
$builder  = com_wiris_quizzes_api_QuizzesBuilder::getInstance();
// Read question
$fileName = dirname(__FILE__) . '/wirisquestion.xml';
$requestStr = file_get_contents($fileName);
$question = $builder->readQuestion($requestStr);
$instance = $builder->newQuestionInstance($question);
// Create question request
$questionRequest = $builder->newEvalRequest($correctAnswer,$studentAnswer,$question,$instance);
// Send the xml request data
$service  = $builder->getQuizzesService();
// Call the web service
$response = $service->execute($questionRequest);
// Get the response into the instance object.
$instance->update($response);
// Ask for the correctness of the 0th response.
$correct = $instance->isAnswerCorrect(0);
echo $correct;
?>

You can benefit from the whole power of CalcMe for validating answers. For example, you could ask the student to input a polynomial that has a given list of roots. Thus you need a way to verify that a certain polynomial has the required roots. Visit http://www.wiris.com/quizzes/docs/generic/run/php/level3.php and click or tap the Wiris Quizzes icon. With the new window click or tap the Variables tab, then Edit algorithm with CalcMe and write the following program:

Go back to the Validation tab and set Grading function with value test.

Click Export to get the question descriptor and save it into degree2.xml. The program would be analogous than the one in Use the Wiris Quizzes Studio / Step 2 above:

<?php 
require_once 'quizzes/quizzes.php';
$correctAnswer = "{-1,1}";
$studentAnswer = "1-x^2";
$builder  = com_wiris_quizzes_api_QuizzesBuilder::getInstance();
// Read question
$fileName = dirname(__FILE__) . '/degree2.xml';
$requestStr = file_get_contents($fileName);
$question = $builder->readQuestion($requestStr);
// ...
?>
Note $correctAnswer is not the proper correct answer but the list of roots. We use that trick as the $correctAnswer is always the second optional parameter of the grading function.

This section is related to physics units, but it also shows how to define the meaning of other symbols using the Allowed input section of Wiris Quizzes Studio Validation tab.

Wiris Quizzes needs to be notified when working with physics units. The underlying reason is recognition of units. For example, recognizing km as kilometer instead of the multiplication of the two variables k and m.

Open Wiris Quizzes Studio as explained previously and select the Quantity radio button.

Click Export to get the question XML file and save it to quantity.xml. As in other examples, load the XML into a Question object:

<?php 
    require_once 'quizzes/quizzes.php';
    $correctAnswer = "1000m";
    $studentAnswer = "1km";
 
    $builder  = com_wiris_quizzes_api_QuizzesBuilder::getInstance();
 
    // Read question
    $fileName = dirname(__FILE__) . '/quantity.xml';
            $requestStr = file_get_contents($fileName);
    $question = $builder->readQuestion($requestStr);
    // …
?>

Allowing physical units in MathType

If you want to use MathType with physical units you will need to let it know about the particular question configuration. More generally, the reserved words of MathType, the real-time syntax checking and even the handwriting recognize engine will adapt to the syntax particularly defined for each question.

Consider the following HTML/JavaScript code for the question delivery to the student. The only difference is that we provide the question object, now in JavaScript, to the answer field builder method.

<!DOCTYPE html>
<html>
  <head>
    <script src=
      "http://<your-domain>/quizzes/service.php?service=resource&amp;name=quizzes.js"
    ></script>
<script>
function displayEditor() {
  // Get [WQ] User Interface Builder.
  var builder = com.wiris.quizzes.api.QuizzesBuilder.getInstance();
  var question = builder.readQuestion('<question>...</question>');
  var uibuilder = builder.getQuizzesUIBuilder();
  // Build student's answer field.
  answerField = uibuilder.newAnswerField(question, null, 0);
  var answerContainer = document.getElementById("studentAnswer");
  answerContainer.replaceChild(answerField.getElement(), answerContainer.firstChild);
}
window.onload=displayEditor;
    </script>
  </head>
  <body>
<!-- This input will be replaced by MathType instance. -->
    <div style="width:500px;height:200px" id="studentAnswer"><span></span></div>
    <br>
    <input type="button" value="Get MathML"   
           onclick="alert(answerField.getValue())"/>
  </body>
</html>

The value passed to readQuestion is the question XML. Now MathType recognizes the units and displays them in blue.

You can integrate the authoring interface Wiris Quizzes Studio in your own platform. Thus, the authors can define a question's mathematical properties, which is saved as XML in your platform and used whenever it is needed.

The way the Wiris Quizzes Studio is integrated into the question authoring page is analogous to the way MathType is integrated with the question delivery. We just replace the correct answer input field by an AuthoringField provided by the Wiris Quizzes UI API. See the Level 2 and Level 3 examples in the Getting Started package for your technology.

There is also an integration for Android apps that do not need an internet connection to work. This is achieved by providing a native Android library with the mathematical engine and configuring the Wiris Quizzes API to use this native library instead of the online web services. Contact our support team for more information on this technology.