WIRIS quizzes 2.

Integration guide
Document Release: 1.2
2016 may, Maths for More
www.wiris.com
Contact: [email protected]

Summary. This guide explains a set of scenarios solved with WIRIS quizzes 2. It starts
explaining how to call WIRIS quizzes services to evaluate a student answer and, then,
how to integrate WIRIS editor in a quizzes system context.

Contents

Where can be integrated WIRIS quizzes? ........................................................................................... 2

Comparing the equivalence of two formulas...................................................................................... 3
Embedding WIRIS editor ..................................................................................................................... 4
Customizing WIRIS editor toolbar ....................................................................................................... 5
Comparing two formulas with additional criteria ............................................................................... 6
Step 1. Obtaining the question XML ............................................................................................... 6
Step 2. Using the question descriptor in your program .................................................................. 8
Validate the student answer with a custom algorithm....................................................................... 9
Change input symbols: working with physics units .......................................................................... 11
Allowing physical units in WIRIS editor ......................................................................................... 12
Integrating WIRIS quizzes studio in your own platform.................................................................... 13

Maths for More 2016

WIRIS quizzes integration guide

Page 2 of 13

Where can be integrated WIRIS quizzes?

WIRIS quizzes mainly targets Web applications. There are currently five integrations that you can
download as part of the respective Getting started example:
1)
2)
3)
4)
5)

PHP integration
.NET integration
Java integration
JavaScript integration
ActionScript 3/Flash integration

The PHP, .NET and Java integrations require that you programmatically call the WIRIS quizzes API
in order to evaluate the answer of a student. This invocation is done from the server-side.
For the JavaScript and ActionScript 3/Flash integrations, you also need to programmatically call
the WIRIS quizzes API. But, instead, the invocation is done from the browser. This option is less
secure because the correct answer is also sent to the client browser.
Its worth to note that the JavaScript and ActionScript 3/Flash integrations also need some serverside scripts used to connect your server with WIRIS quizzes server. Such scripts are part of the
integration (Getting started examples) that we already provide for you.
In any case, the ultimate evaluation of the student answer is performed by WIRIS quizzes using its
Web services:

Your server
Browser

WIRIS quizzes
integration

WIRIS quizzes
Web-services

Maths for More 2016

WIRIS quizzes integration guide

Page 3 of 13

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.
First download the getting started source code from www.wiris.com/quizzes/download/generic
compatible with your technology.
Lets note that all this examples will connect 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();
$request = $builder->newEvalRequest($correctAnswer,
$studentAnswer, null, null);
//Make the remote call.
$service = $builder->getQuizzesService();
$response = $service->execute($request);
//Get the response into this useful object.
$instance = $builder->newQuestionInstance();
$instance->update($response);
//Ask for the correctness of the 0th response.
$correct = $instance->isAnswerCorrect(0);
echo $correct;
?>

This example depends on the quizzes/quizzes.php and related files that can be found in the getting
started source code.
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 WIRIS editor, see next section of this
documentation.
Further discussions about the API can be found WIRIS quizzes API.

Maths for More 2016

WIRIS quizzes integration guide

Page 4 of 13

Embedding WIRIS editor

Students will input the answers using either a simple text box or a full formula editor. This section
explains how to embed a formula editor. This same procedure can be repeated many times if you
need more than one formula editor.
Edit a file called editor.html and write
<!DOCTYPE html>
<html>
<head>
<script src=
"http://<your-domain>/quizzes/service.php?service=resource&amp;name=quizzes.js"
></script>
<script>
function displayEditor() {
// Get WIRIS quizzes 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 WIRIS editor. -->
<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 example for your technology.
With this code you will see the following page where the toolbar contains the significant symbols
for a quizzes scenario and the syntax checking is enabled.

Maths for More 2016

WIRIS quizzes integration guide

Page 5 of 13

Customizing WIRIS editor toolbar

The default WIRIS editor will be fine for many scenarios but you will, eventually, want to configure
the toolbar icons or any other aspect. You can check the documentation in Embed WIRIS editor to
get an idea of the available initialization parameters.
To configure WIRIS editor, you will need to specify the initialization parameters as follows:
...
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>',
});
...

Example of customized toolbar:

Maths for More 2016

WIRIS quizzes integration guide

Page 6 of 13

Comparing two formulas with additional criteria

When comparing the correct answer with the student answer, for example, it is possible to
request further requirements like the the student answer should be simplified.
Following the example, the student is asked to compute ( 2 + 3) (2 + 2 2 ) and the correct
answer should be 1 2 or 2 + 1 instead of 2 2 2 + 1, which is invalid because it is not
simplified.
WIRIS quizzes allows using many additional criteria. For this purpose we will use WIRIS quizzes
studio to define the question that will be sent to the evaluation server at www.wiris.net.

Step 1. Obtaining the question XML

You will 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 that 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/demo/generic/en/level3.php and
you will get:

And press the icon

to open WIRIS quizzes studio.

Type the Correct answer 1 2 with the sole purpose to check the question works fine.

Maths for More 2016

WIRIS quizzes integration guide

Page 7 of 13

Move to Validation tab and check is simplified.

Move to Preview and play with possible students answers. You will realize that 2 + 1 is a valid
response

and 1 2 2 + 2 is wrong because it is not simplified.

Maths for More 2016

WIRIS quizzes integration guide

Page 8 of 13

Now, we will get the Question XML in order to use it in our program. Type Shift+Ctrl+Q and the
following dialog will appear:

You can copy the Question XML and save it into a file named simplified.xml.

Step 2. Using the question descriptor in your program

Create a file named example2.php with the following content
<?php
require_once 'quizzes/quizzes.php';
$correctAnswer = "x+1";
$studentAnswer = "1+x";
$builder

= com_wiris_quizzes_api_QuizzesBuilder::getInstance();

// Read question
$fileName = dirname(__FILE__) . '/simplified.xml';
$requestStr = file_get_contents($fileName);
$question = $builder->readQuestion($requestStr);
// Create question request
$questionRequest = $builder->newEvalRequest($correctAnswer,
$studentAnswer,$question,null);
// Send the xml request data
$service = $builder->getQuizzesService();
// Call the web service
$response = $service->execute($questionRequest);
// Get the response into this useful object.
$instance = $builder->newQuestionInstance();

Maths for More 2016

WIRIS quizzes integration guide

Page 9 of 13

$instance->update($response);
// Ask for the correctness of the 0th response.
$correct = $instance->isAnswerCorrect(0);
echo $correct;
?>

Validate the student answer with a custom algorithm

You can benefit from the whole power of WIRIS cas for validate answers. For example, you could
request to 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/tests/generic/level3.php and press the
new window press the variable tab and write the following program:

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

icon. With the

Maths for More 2016

WIRIS quizzes integration guide

Press Shift+Ctrl+Q to get the question descriptor and save it into degree2.xml
The program would be
<?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);
// Create question request
$questionRequest = $builder->newEvalRequest($correctAnswer,
$studentAnswer,$question,null);
// Send the xml request data
$service = $builder->getQuizzesService();
// Call the web service
$response = $service->execute($questionRequest);
// Get the response into this useful object.
$instance = $builder->newQuestionInstance();
$instance->update($response);
// Ask for the correctness of the 0th response.
$correct = $instance->isAnswerCorrect(0);
echo $correct;
?>

Note that the $correctAnswer is not the proper correct answer but the list of roots.

Page 10 of 13

Maths for More 2016

WIRIS quizzes integration guide

Page 11 of 13

Change input symbols: working with physics units

This section is related to physics units but is also interesting for understanding how to enable or
disable some symbols using the following WIRIS quizzes studio sections from Validation tab

and

WIRIS quizzes needs to be notified when working with physics units. The underlying reason is that
it needs recognize km as kilometer instead of the multiplication of the two variables k and m.
Open WIRIS quizzes studio as explained previously and select Quantity.

Press Ctrl+Shift+Q and get the question XML and save it to quantity.xml
<?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);
// Create question request
$questionRequest = $builder->newEvalRequest($correctAnswer,
$studentAnswer,$question,null);
// Send the xml request data
$service = $builder->getQuizzesService();
// Call the web service
$response = $service->execute($questionRequest);
// Get the response into this useful object.

Maths for More 2016

WIRIS quizzes integration guide

Page 12 of 13

$instance = $builder->newQuestionInstance();
$instance->update($response);
// Ask for the correctness of the 0th response.
$correct = $instance->isAnswerCorrect(0);
echo $correct;
?>

Allowing physical units in WIRIS editor

If you want to use WIRIS editor with physical units you will need to enable them.
Create the file editor2.html and write the following
<!DOCTYPE html>
<html>
<head>
<script src=
"http://<your-domain>/quizzes/service.php?service=resource&amp;name=quizzes.js"
></script>
<script>
function displayEditor() {
// Get WIRIS quizzes 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 a WIRIS editor. -->
<div style="width:500px;height:200px" id="studentAnswer"><span></span></div>
<br>
<input type="button" value="Get MathML"
onclick="alert(answerField.getValue())"/>
</body>
</html>

Note that some lines, in blue, are shortened with three dots (). The value passed to readQuestion
is the question XML:

Maths for More 2016

WIRIS quizzes integration guide

Page 13 of 13

Now, WIRIS editor recognizes the units and displays them in blue.

Integrating WIRIS quizzes studio in your own platform

WIRIS quizzes studio is designed to be easily integrated in any web platform. You can follow the
getting started demos called level 2 and level 3.
Another benefit on a depth integration of WIRIS quizzes studio is that you have the option to
generate random questions.