-
MathType
-
Wiris Quizzes
-
Learning Lemur
-
CalcMe
-
MathPlayer
-
Store FAQ
-
VPAT for the electronic documentation
-
MathFlow
-
BF FAQ
WirisQuizzes integration guide
Reading time: 7minWirisQuizzes 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's answer. While it's possible to fully integrate WirisQuizzes using client-side technology, 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's 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+1 is equivalent to 1+x.
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&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.
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="×"/>'+
'<item ref="-"/>'+
'<item ref="÷"/>'+
'</tab></toolbar>',
});
...
That code results in this toolbar:
Comparing two formulas with additional criteria
When comparing the correct answer with the student's answer, it is possible to request further requirements like the "the student's answer should be simplified". Following the example, the student is asked to compute x2+3-2+2x2, and the correct answer should be 1-x2 or -x2+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's 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. Firstly, you need to obtain the question XML.
The question description XML is a .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:
Press the icon 
to open WirisQuizzes Studio. Type the correct answer 1-2x²+x² to ensure the question works correctly.
Select Validation options, click Show all options, scroll down to Simplification and tick the Simplified box.
Click the Back button at the top of WirisQuizzes Studio, and click Test this question at the lower left. Try other possible student answers. You'll see -x2+1 is a valid response.
And 1-2x²+x² is wrong because it is not simplified.
Now, we will get the Question XML. Click Export in the menu at the upper right
.png)
And a file named "wirisquestion.xml" will be downloaded into your default Downloads folder, with the Question XML definition in it. Finally, you just need to use 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.png)
icon. With the new window, click or tap Random variables, write the following program, and click Save.
Click the corresponding icon to open WirisQuizzes Studio, then click Validation options. Select Custom grading function. The function test should already be selected.
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 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.
.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&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.
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 Bundle 2 and Bundle 3 examples in the Getting Started package for your technology.
