Skip to main content

WirisQuizzes Generic Integration

WirisQuizzes generic integration allows organizations to use the enhanced features provided by WirisQuizzes in their own environment and customize and adapt the WirisQuizzes software to their own tech environment.

WirisQuizzes generic are the technological components of WirisQuizzes that target the developer or integrator of the learning application, and there is an implementation for the following technologies:

  • PHP

  • Java

  • JavaScript

Demo with WirisQuizzes

Since the generic integration implies development work from the client’s side, it’s complicated to provide a demo environment that simulates their workspace.  However, to showcase the potential of the WirisQuizzes software the Sales Demo WirisQuizzes is a good example of how to use the different bundles of integration since this demo itself was made using a “generic integration”.

Another possibility can be to showcase a demo instance if the client in this case is an LMS or ed-tech platform. On the other hand, if the client is already familiar with WirisQuizzes’ features and would like to test WirisQuizzes on their staging environment then the following integration packages can be shared according to the technology used by the client.

button_download-generic-integration-package.png

WirisQuizzes in your assessment system

WirisQuizzes is a set of components that work together to enhance computer-based assessment in mathematics and science. It offers new unique possibilities and fills the gap between the current question systems and the specific needs of the mathematical and scientific community.

WirisQuizzes is powered by some WIRIS technologies which are easily integrable into any assessment system with a minimal development investment.

circles.png

Enhanced features

  • Equation creation and editing at authoring time and equation visualization at presentation time by MathType. 2D and 3D graphics.

  • Simplified MathType equation editor as an input field for open student answers. Answers are entered in the usual mathematical notation. Localization. Handwriting.

  • Real-time syntax validation of student answers.

  • Answer grading with a wide range of mathematical equivalences and criteria: precision and tolerance, simplification, expansion, rationalization, equation solving, sets, text.

  • WirisQuizzes Studio authoring interface for defining the grading criteria.

  • Random question parameters generated via an algorithm and custom grading functions using the CalcMe calculator.

Integration bundles

To start with WirisQuizzes generic, you will first need to choose how deep your integration is going to be. You can integrate only the features that you need. For example, the following scenarios with increased complexity are possible:

levels_integrations.png

Bundle 1: Smart Math Comparison

For short question types, use the validation web service to validate the correct answer with the students answer. The validation criteria will always be the mathematical equality (for example, x+2x+2 is equal to 2+x2+x). You might or might not allow your student to input the answers using the MathType (which always includes the input syntax check).

Bundle 2: WirisQuizzes Studio

Choose between a set of features to include on top of the intelligent math comparison. For short answer question types, you can integrate our wealthy assertion builder, WirisQuizzes Studio, to allow your authors to choose the correct grading criteria. For example, 24 would be a wrong answer if the author requested a simplified response. Besides, you can also include:

  • Graphical Answer

  • Auxiliary Text Input

  • Auxiliary CalcMe

  • Grading Function

  • Random Variables

Bundle 3: All features included

Bundle 3 includes Bundle 2 with all its extra features activated (random variables, graphical answer, auxiliary text field, auxiliary CalcMe and grading function). You can add this feature to any question type (multiple-choice, true/false, matching, essay, etc.) in addition to the open-answer question type.

To summarize, the features included in each bundle are described in the table below:

Features

Bundle 1 - Smart Math Comparison

Bundle 2 - WirisQuizzes Studio

Bundle 3 - All features

Smart Math Comparison

tic_green.png
tic_green.png
tic_green.png

WirisQuizzes Studio

cross.png
tic_green.png
tic_green.png

Graphical Answer

cross.png

Optional

tic_green.png

Auxiliary Text Input

cross.png

Optional

tic_green.png

Auxiliary CalcMe

cross.png

Optional

tic_green.png

Grading Function

cross.png

Optional

tic_green.png

Random Variables

cross.png

Optional

tic_green.png

Architecture

The assessment system is the part of your platform where WirisQuizzes is to be integrated. To help integrate our tools into the assessment system, we offer the WirisQuizzes API, a library in different technologies (Java, PHP, .NET, JavaScript, Flash) to facilitate the usage of the services. You will need to develop the WirisQuizzes integration between your assessment system and the WirisQuizzes API. The underlying WirisQuizzes server components are software as a service (SaaS). Optionally, you can install these server components on your server. They are separated into the WirisQuizzes web service and the Mathematical engine.

integration.png

The following figure summarizes the architecture of WirisQuizzes

structure.png

Integration contact of WirisQuizzes and your assessment system

The following points are the integration contact of WirisQuizzes and your platform. They are divided between client-side (HTML + JavaScript) and server-side (Java, .Net, PHP, Flash, JavaScript + web service calls), and they are cumulative on ongoing bundles:

Bundle 1: Open answer with default equivalence criteria

On the client-side,

  • Authoring: replace your plaintext input for the correct answer with a MathType editor.

  • Delivery: replace your plaintext input for the student answer with a MathType editor with syntax checking.

On the server-side,

  • Delivery: Use the API to our validation web service to grade the student answer.

delivery.png

Bundle 2: Open answer with different equivalence criteria

On the client-side,

  • Authoring: Replace your correct answer input field with the WirisQuizzes Studio.

  • Delivery: As in Bundle 1. Additionally, you may display some automatic feedback.

On the server-side,

  • Authoring: Save the question options.

  • Delivery: Use the API to call the validation web service to grade the student answer.

delivery2.png

Bundle 3. Random questions

On the client-side,

  • Authoring: As in Bundle 2

  • Delivery: As in Bundle 2

On the server-side,

  • Authoring: Save the question options.

  • Delivery: Use the API to call the web service to generate the random parameters and to render the question statement with equations and graphs. Use the API to call the web service to grade the student answer. Use the API to call the web service to generate the feedback equations and graphs.

random_q.png

WirisQuizzes integration guide

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'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+1x+1 is equivalent to 1+x1+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&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'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-x21-x^2 or -x2+1-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'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:

studio_level3.png

Press the icon icon_.png to open WirisQuizzes Studio. Type the correct answer 1-2x2+x21-2x^2+x^2 to ensure the question works correctly.

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 of WirisQuizzes Studio, and click Test this question at the lower left. Try other possible student answers. You'll see -x2+1x^2-1 is a valid response.

studio_preview.png

And 1-2x2+x21-2x^2+x^2 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. 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 icon_.png icon. With the new window, click or tap Random variables, write the following program, and click Save.

variables.png

Click the corresponding 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 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 Bundle 2 and Bundle 3 examples in the Getting Started package for your technology.

studio_level2.png

WirisQuizzes Reference

API Integration Library

This is the class reference of the WirisQuizzes generic integration library. These classes are available for PHP, Java, .NET, ActionScript, and JavaScript, although the documentation is Javadoc. The generic integration library is included in the getting started examples download packages.

Full API reference

Assertions reference

The WirisQuizzes assertions reference explains the different assertions available and their meaning in detail. Assertions are used in the evaluation process of the student answer. Each assertion returns true or false, and many assertions are combined to get the final student grading. In WirisQuizzes Studio, assertions can be selected individually under the Validation options section.

Assertions reference

In this section: