WirisQuizzes integration guide

Where can WirisQuizzes be integrated?

WirisQuizzes 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 WirisQuizzes example:

The server-side technology is used to programmatically call the WirisQuizzes API to evaluate the student answer. With integrations with pure client-side technology (JavaScript), you also need to call the WirisQuizzes 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 WirisQuizzes using its web services.

Comparing the equivalence of two formulas

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

First, download the getting started source code compatible with your technology.

Note

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_Quizzes::getInstance();
$request = $builder->newSimpleGradeRequest($correctAnswer, $studentAnswer);
//Make the remote call.
$service = $builder->getQuizzesService();
$response = $service->execute($request);
//Get the response into QuestionInstance object. This object allows us to interpret the response of the service and see if the student's answer is correct.
$instance = $builder->newQuestionInstance(null);
$instance->update($response);
//Ask for the correctness of the answer
$correct = $instance->areAllAnswersCorrect();
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 = ""; 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 WirisQuizzes API.

Embedding MathType

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.Quizzes.getInstance();
  var uibuilder = builder.getQuizzesComponentBuilder();
  // Build student's answer field.
  answerField = uibuilder.newAnswerField(null, null, null);
  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.

embedding.png

Customizing MathType toolbar

MathType 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 understand the available initialization parameters and the toolbar definition syntax.

Consider the example code:

...
answerField = uibuilder.newAnswerField(null, null, null);
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:

customizing_the_toolbar.png

Comparing two formulas with additional criteria

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 x2+3-2+2x2, and the correct answer should be 1-x2LaTeX 1-x^2 or -x2+1LaTeX -x^2+1 but not x2-2x2+1, which is invalid because it is not simplified.

WirisQuizzes 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 WirisQuizzes 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 compare the correct and the student answers simply.

<?php
require_once 'quizzes/quizzes.php';
$correctAnswer = "-x^2+1";
$studentAnswer = "1-x^2";
$builder  = com_wiris_quizzes_api_Quizzes::getInstance();
// Read question
$question = $builder->newQuestion();
// Create a slot for students to enter their answer
$slot = $question->addNewSlot();
// Define the grading criteria as being equivalent to the correct answer and checking if the student's answer is simplified.
$authorAnswer = $slot->addNewAuthorAnswer($correctAnswer);
$authorAnswer->addNewValidation(com_wiris_quizzes_api_assertion_ValidationName::CHECK_SIMPLIFIED);
// Create the question instance.
$instance = $builder->newQuestionInstance($question);
// Create the question request
$questionRequest = $builder->newEvalRequest($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 response
$correct = $instance->isSlotAnswerCorrect();
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 WirisQuizzes Studio

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

Step 1. Obtaining the question XML

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

To use WirisQuizzes Studio visit https://demo.wiris.com/quizzes/en/quizzes4.html, and you will get:

studio_level3.png

Press the icon icon_.png to open WirisQuizzes studio.

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

studio_correct.png

Select Validation options, click Show all options, scroll down to Simplification and tick the Simplified box.

is_simplified.png

Click the Back button at the top.

Click Test this question at the lower left. Try other possible student answers. You'll see –x² + 1 is a valid response.

studio_preview.png

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

wrong_answer.png

Now, we will get the Question XML. Click Export in the menu at the upper right

export.png

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';
$studentAnswer = "1-x^2";
$builder  = com_wiris_quizzes_api_Quizzes::getInstance();
// Read question
$fileName = dirname(__FILE__) . '/wirisquestion.xml';
$requestStr = file_get_contents($fileName);
$question = $builder->readQuestion($requestStr);
// Get the first slot
$slot = $question->getSlots()[0];
$instance = $builder->newQuestionInstance($question);
// Set the student's answer
$instance->setSlotAnswer($slot, $studentAnswer); 
// Create question request
$questionRequest = $builder->newGradeRequest($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->isSlotAnswerCorrect($slot);
echo $correct;
?>

Validate the student answer with a custom algorithm

You can benefit from the real 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 it would be best if you had a way to verify that a particular polynomial has the required roots. Visit https://demo.wiris.com/quizzes/en/quizzes4.html and click or tap the icon_.png icon. With the new window, click or tap Define random variables and functions, then Edit algorithm with CalcMe, write the following program, and click Save. (The left sidebar isn't necessary for this, but if it's not visible and you want it to be, click the menu button to the left of Untitled calc: menu_button.png.)

variables.png

Click the "gear" icon to open WirisQuizzes Studio, then click Validation options. Select Custom grading function. The function test should already be selected.

test.png

Click the back button, then Export from the menu at the upper right to get the question descriptor and save it into degree2.xml. The program would be analogous to the one in Use the WirisQuizzes Studio / Step 2 above:

<?php 
require_once 'quizzes/quizzes.php';
$studentAnswer = "1-x^2";
$builder  = com_wiris_quizzes_api_Quizzes::getInstance();
// Read question
$fileName = dirname(__FILE__) . '/degree2.xml';
$requestStr = file_get_contents($fileName);
$question = $builder->readQuestion($requestStr);
// ...
?>

Change input symbols: working with physics units

This section is related to physics units, but it also shows how to define the meaning of other symbols using the Input syntax section of WirisQuizzes Studio Input options section.

WirisQuizzes needs to be notified when working with physics units. The underlying reason is the recognition of units. For example, they recognise km as kilometres instead of the multiplication of the two variables k and m.

Open WirisQuizzes Studio as explained previously, click Input optionsand scroll to Input syntax.

quantity.png

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';
    $studentAnswer = "1km";
    
    $builder  = com_wiris_quizzes_api_Quizzes::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 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 mainly 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.Quizzes.getInstance();
  var question = builder.readQuestion('<question>...</question>');
  var slot = question.getSlots()[0];
  // Build student's answer field.
  var uibuilder = builder.getQuizzesComponentBuilder();
  answerField = uibuilder.newAnswerField(question, slot);
  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.

km.png

Integrating WirisQuizzes Studio in your own platform

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

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

studio_level2.png