WIRIS quizzes web services Getting started with PHP and Java Document Release: 1.3 2011 march, Maths for More www.wiris.com Summary This document provides client examples for PHP and Java. Contents WIRIS quizzes web services. Getting started with PHP and Java...2 Getting started with PHP...2 Random question example...6 Getting started using Java and Axis2...8 Building a simple client...8 Getting started using JSP...11 Install WIRIS plugin core...14
2010, Maths for More WIRIS quizzes in your assessment system. V1 2 WIRIS quizzes web services. Getting started with PHP and Java The WIRIS quizzes services have two invocation protocols: SOAP and REST. The examples of this appendix explain how to call the WIRIS quizzes Web services. The invocation of the REST service is exemplified with two PHP scripts and a JSP application. The SOAP version is explained using Java and the Axis 2 library. The first PHP example and the Java example compare whether two expressions are equivalent. This is the common scenario when the input of the student has to be tested against a valid response in a quiz. The second PHP script uses a WIRIS CAS to exemplify the generation of random questions. The JSP examples are the most complete and they cover the random question generation, the assertion system and the WIRIS editor integration. Getting started with PHP In the following example, we will make a simple client in PHP for the WIRIS quizzes API web service. The example is written to not use any extension library. This demonstration example can be downloaded from http://www.wiris.com/quizzes/docs/generic It is a zip file labeled PHP examples. It consists in two PHP files. Just take them and copy the file to some place accessible from your PHP interpreter. They will output an HTML file with the result of the test. Now we are interested in the first and simpler one, quizzes-api-client.php. This script uses the service to check whether two MathML strings are the same mathematical value or not. Let s see the code and how it works:
2010, Maths for More WIRIS quizzes in your assessment system. V1 3 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/tr/xhtml1/dtd/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"/> <title>wiris quizzes API PHP test</title> </head> <body> <?php //define the hypotetic correct answer and the student's answer. $mathml1 = '<mrow><mfrac><msqrt><mn>2</mn></msqrt><mn>2</mn></mfrac></mrow>'; $mathml2 = '<mrow><mfrac><mn>1</mn><msqrt><mn>2</mn></msqrt></mfrac></mrow>'; //build the input message $message = getequivsymbolicassertionmessage($mathml1, $mathml2); //call the service $result = callwirisapi($message); //get the interesting return value $value = getreturnvalue($result); //print the result echo '<h1>wiris quizzes API test</h1>'; echo 'mathml1 = '.htmlentities($mathml1).'<br />'; echo 'mathml2 = '.htmlentities($mathml2).'<br />'; echo '<strong>'; echo intval($value) == 1?'Are equivalent':'are not equivalent'; echo '</strong>'; This is the entry point of the example. After defining the HTML headers, we define a pair of MathML strings. Then we call getequivsymbolicassertionmessage in order to build the XML input message. With that input message, we call the service (callwirisapi), and get the result also as an XML string. We use another function to get the interesting value from the result string (getreturnvalue). Finally, we output some html depending on the result.
2010, Maths for More WIRIS quizzes in your assessment system. V1 4 function getequivsymbolicassertionmessage($mathml1, $mathml2){ $assertion_name = 'equivalent_symbolic'; $operation_name = 'getcheckassertions'; $mathml1 = wrapincdata($mathml1); $mathml2 = wrapincdata($mathml2); $xml = '<doprocessquestions>'. '<processquestions>'. '<processquestion>'. '<question>'. '<correctanswers>'. '<correctanswer type="mathml">'. $mathml1. '</correctanswer>'. '</correctanswers>'. '<assertions>'. '<assertion name="'.$assertion_name.'" />'. '</assertions>'. '</question>'. '<userdata>'. '<answers>'. '<answer type="mathml">'. $mathml2. '</answer>'. '</answers>'. '</userdata>'. '<processes>'. '<'.$operation_name.'/>'. '</processes>'. '</processquestion>'. '</processquestions>'. '</doprocessquestions>'; return $xml; This function builds the input message. We set the first MathML string to be the correct answer, the second MathML to be the user s answer and we define an assertion of type equivalent_symbolic. This assertion compares the symbolical (mathematic) equivalence between the correct and the user s answers. Finally, we add the operation getcheckassertions that will output the result of the evaluation of the assertion.
2010, Maths for More WIRIS quizzes in your assessment system. V1 5 function callwirisapi($xml) { $url = 'http://services.wiris.com/quizzes/rest'; $opts = array( 'http' => array( 'method' => 'POST', 'header' => 'Content-type: text/xml; charset=utf-8'."\n". 'Content-Length: '.strlen($xml)."\n", 'content'=> $xml ) ); $context = stream_context_create($opts); $result = file_get_contents($url, false, $context); return $result; This function calls the service via http and the POST method. function wrapincdata($str) { return '<![CDATA['.$str.']]>'; function getreturnvalue($xml){ //in a more general purpose client the xml should be completely parsed, //here we go directly to the result. $pattern = '/<check[^>]*>(\d+)<\/check>/'; $matches = array(); preg_match($pattern, $xml, $matches); return $matches[1];?> </body> </html> This last function uses a regular expression to get the result. It will be the string 0 or 1. In a real scenario, is fully recommended to parse the whole XML message, but here it is enough to do it in this way. Of course this example doesn t cover the full potential of WIRIS quizzes API, and for a real application there will be needed to deal with XML not as a string but as a complex structure. Furthermore, such functions will be enclosed in a class or a file, and never embedded in an HTML. However, the important concepts are here and one can use that to start the development of the first prototype. For a more detailed specification of the service, see the reference http://www.wiris.com/quizzes/docs/generic and the formal specification in the WSDL file http://services.wiris.com/quizzes/soap?wsdl.
2010, Maths for More WIRIS quizzes in your assessment system. V1 6 Random question example So far we have merely test the service. Now we make a complete example of the integration of WIRIS quizzes to make a random question. In order to make random questions, it is necessary to have an algorithm to produce these random elements. The following is the simplest meaningful and complete example of a random question. Consider the other script quizzes-api-demo.php. The source will not be printed here, because of his length, and because it is very close to the previous one. Thus, open it with a text / PHP editor and follow the workflow explained here in the code. Get it in your browser from your web server or from http://www.wiris.com/demo-php/quizzes/quizzes-apidemo.php and it will display: This is a minimal editing page for a random short answer question. In the first field we define the question statement. The variables are referenced with the sharp symbol # and the name this is a choice of the question engine. The second field is where we put the name of the variable holding the correct answer. Finally, we define the algorithm that produces the random items. Note that the program is enclosed in a library box. In order to embed a WIRIS CAS applet in a web page it is necessary to write an applet tag in the HTML. It admits a parameter for the initial session. There must be a pair of JavaScript lines to obtain the applet content. See the source code for more details. Clicking the submit button, the service will be called to get the value of the variables in order to compile the question text.
2010, Maths for More WIRIS quizzes in your assessment system. V1 7 By filling the answer field and clicking the submit button, the service is called again. Now we ask for the equivalence between the user s response and the correct answer. There are a few comments concerning these two calls: The question section in the input message is exactly the same. Indeed, it has been designed to have all the static data of the question, so it will be the same in all calls related to the same question. The randomseed element in the userdata section must be the same in the first and the second call, in order to have the same values when displaying the question and when grading. It should be different between attempts. Finally, we will get the result: Although this is a more complete example than the first, there also remain some features of the service that should be used in a real question engine: There are other and more powerful ways to grade the answer: one alternative way is to use function defined by the author in the WIRIS CAS applet (See the reference document). It is also possible to use other assertions than equivalent_symbolic, and they can be combined (See http://services.wiris.com/assertions.xml for an updated list). So far we have used only plain text, but the interface can be much more powerful adding a WIRIS Editor in the answer field and displaying MathML formulas in the question text using the WIRIS Image Service. When this is done, it is worth to handle the syntax errors of the students when they write formulas. (See the Error section of the reference document).
2010, Maths for More WIRIS quizzes in your assessment system. V1 8 Getting started using Java and Axis2 In this document we will quickly build a simple SOAP client in the Java programming language for the WIRIS quizzes web services. This example gives the same functionality than the first. A compiled version of this example can be found at http://www.wiris.com/quizzes/docs/generic It is a zip file labeled Java Examples. This example requires Java and that the Axis2 library is installed (see below). To run the example, unzip the file and execute in the command line of the system: java -classpath ".;%AXIS2_HOME%/lib/*" com.wiris.services.quizzes.wsdl.client Axis 2 is a helper library that will do all the dirty work of serializing the messages, connecting to the server, etc. Information about Axis 2 can be found at http://axis.apache.org/axis2/java/core/. Building a simple client This section explains how to implement a Java client using the Axis 2 library. The first step is to download (http://apache.rediris.es/axis/axis2/java/core/1.5.2/axis2-1.5.2-bin.zip) and install Axis2. For our purposes it is enough to unzip the file in any folder and define the environment variable AXIS2_HOME. Now, we are going to use the axis2 tool at bin/wsdl2java to build the so called stubs. These are the classes representing all the elements in the protocol: there will be a class for each different element in the specification of the protocol. The source is a WSDL file, located at http://services.wiris.com/quizzes/soap?wsdl. The command is: wsdl2java S src uri http://services.wiris.com/quizzes/soap?wsdl The first option is the folder where the java files have to be created. The second is the URI of the WSDL file. It should create a pair of files. The important one is the WirisQuizzesStub.java. This file contains as nested classes all the mentioned stubs, and also has two methods corresponding to the two operations provided by the service. Now let s write the client. Create a class called Client from where we will use WirisQuizzesStub in order to access the service with a concrete input. Consider the following commented code to understand how it works:
2010, Maths for More WIRIS quizzes in your assessment system. V1 9 package com.wiris.services.quizzes.wsdl; import java.rmi.remoteexception; import org.apache.axis2.axisfault; public class Client { /** * Test the "processquestions" remote method with an * assertion check. **/ public static void main(string[] argv){ Client c = new Client(); c.testserverinfo(); String mathml1 = "<mrow><mfrac><msqrt><mn>2</mn></msqrt><mn>2</mn></mfrac></mrow>"; String mathml2 = "<mrow><mfrac><mn>1</mn><msqrt><mn>2</mn></msqrt></mfrac></mrow>"; c.testequivsymbolic(mathml1,mathml2); This main method calls the two example functions. The first uses the dogetserverinfo operation to get some information about the server. It can be used to test the connectivity with the server. Then, it calls a second function that will test whether two MathML fragments represents the same value. /** * Test the "getserverinformation()" remote method **/ public void testserverinfo(){ try { WirisQuizzesStub wqs = new WirisQuizzesStub(); WirisQuizzesStub.DoGetServerInformationResponse response = wqs.dogetserverinformation(new WirisQuizzesStub.DoGetServerInformation()); System.out.println("Server info: "+response.getservername()+ " "+response.getversion()); catch (AxisFault e) { e.printstacktrace(); catch (RemoteException e) { e.printstacktrace(); Forgetting about the exception handling, this function is very simple. It calls the dogetserverinformation function of the service, with almost empty input. The returning object has two properties: servername and version. Now there is the second function commented below. public void testequivsymbolic(string mathml1, String mathml2) { try { WirisQuizzesStub.DoProcessQuestions dpq = new WirisQuizzesStub.DoProcessQuestions(); WirisQuizzesStub.ProcessQuestions pqs = new WirisQuizzesStub.ProcessQuestions(); dpq.setprocessquestions(pqs); WirisQuizzesStub.ProcessQuestion pq = new WirisQuizzesStub.ProcessQuestion();
2010, Maths for More WIRIS quizzes in your assessment system. V1 10 pqs.addprocessquestion(pq); WirisQuizzesStub.Question q = new WirisQuizzesStub.Question(); pq.setquestion(q); WirisQuizzesStub.CorrectAnswers cas = new WirisQuizzesStub.CorrectAnswers(); q.setcorrectanswers(cas); WirisQuizzesStub.CorrectAnswer ca = new WirisQuizzesStub.CorrectAnswer(); ca.setstring(mathml1); //1 ca.settype(wirisquizzesstub.mathtype.mathml); cas.addcorrectanswer(ca); WirisQuizzesStub.Assertions as = new WirisQuizzesStub.Assertions(); q.setassertions(as); WirisQuizzesStub.Assertion a = new WirisQuizzesStub.Assertion(); a.setname(wirisquizzesstub.assertionname.equivalent_symbolic); //2 as.addassertion(a); WirisQuizzesStub.UserData u = new WirisQuizzesStub.UserData(); pq.setuserdata(u); WirisQuizzesStub.Answers ans = new WirisQuizzesStub.Answers(); u.setanswers(ans); WirisQuizzesStub.Answer an = new WirisQuizzesStub.Answer(); an.setstring(mathml2); //3 an.settype(wirisquizzesstub.mathtype.mathml); ans.addanswer(an); WirisQuizzesStub.Processes ps = new WirisQuizzesStub.Processes(); pq.setprocesses(ps); WirisQuizzesStub.ProcessesChoice pc = new WirisQuizzesStub.ProcessesChoice(); ps.addprocesseschoice(pc); pc.setgetcheckassertions(new WirisQuizzesStub.GetCheckAssertions()); //4 WirisQuizzesStub wqs = new WirisQuizzesStub(); //call process operation WirisQuizzesStub.DoProcessQuestionsResponse response = wqs.doprocessquestions(dpq); //5 WirisQuizzesStub.ProcessQuestionsResult pqsr = response.getprocessquestionsresult(); WirisQuizzesStub.ProcessQuestionResult pqr = pqsr.getprocessquestionresult()[0]; WirisQuizzesStub.GetCheckAssertionsResult gcar = pqr.getprocessquestionresultchoice()[0].getgetcheckassertionsresult(); WirisQuizzesStub.Check c = gcar.getcheck()[0]; //6 System.out.println("The result is: "+c.get_boolean()); catch (AxisFault e) { e.printstacktrace(); catch (RemoteException e) { e.printstacktrace(); We have to build the input message, constructing all the needed objects. The numbered lines are the interesting ones. 1. Set the first MathML string to be the correct answer.
2010, Maths for More WIRIS quizzes in your assessment system. V1 11 2. Define an assertion to be of type equivalent_symbolic. This assertion checks whether the correct answer and the student s answer are mathematically equivalent. 3. Set the second MathML string to be the student s answer. 4. Add the operation getcheckassertions, i.e., evaluate the defined assertions. 5. Call the service. 6. Get the interesting return value. In these examples, we have seen that it is relatively easy to use this service. We only have used a very small part of the features of the service, so this is intended only to be a place where to start the not so trivial work of making a service client behind a question engine. For a more detailed specification of the service, see the reference http://www.wiris.com/quizzes/docs/generic and the formal specification in the WSDL file http://services.wiris.com/quizzes/soap?wsdl. Getting started using JSP This JSP example is packed in a war that can be downloaded from http://www.wiris.com/quizzes/docs/generic and labeled JSP examples. Only the general concepts will be outlined in order to ease the understanding of the source code. To test this example, it is sufficient to copy the war file into your Java application container (Tomcat). Then, go to./index.jsp relatively to this application context, by default http://127.0.0.1:8080/quizzes-api-jsp/index.jsp. For the last example is also needed to have the WIRIS plugin core installed (see below). There is also a live demo at http://services.wiris.com/demo-java/quizzes/index.jsp You will find four links, one for each implemented distinct question types: shortanswer.jsp: This example shows how to build simple short open answer questions generated with an algorithm that contains random variables. It is equivalent to the previous PHP example. The workflow of this question type is the following: 1. Editing question: Displays input fields to: define the involved variables using an algorithm in a WIRIS CAS applet, define the question text with references to the algorithm variables and to set the correct answer variable name. 2. Displaying question: Saves the question definition. Calls WIRIS quizzes service to get the textual value of the variables needed to compose the question statement. Displays the question statement and an input field to enter the response. 3. Grading question: Saves the user s answer. Calls WIRIS quizzes service to evaluate if the user s answer is mathematically equivalent to the correct one. Displays some feedback. multiplechoice.jsp: This example shows how to build a simple multiple choice closed question, generated with an algorithm containing random variables. The workflow is: 1. Editing question: Displays input fields to define the question: a WIRIS CAS applet to define the algorithm with the logic of the question, the question statement with references to variables in the algorithm and four fields for the possible options, one is the correct one and the others are the incorrect ones.
2010, Maths for More WIRIS quizzes in your assessment system. V1 12 2. Displaying question: Saves the question definition. Calls WIRIS quizzes service to get the textual value of the variables needed to compose the question statement and to show all answer options. Displays the question statement and the four options. 3. Grading question: Save the user s choice. Check whether this choice is the correct one. Display some feedback. assertions.jsp: This example shows how to build a short open answer question using the formula editor to enter the response. It also shows how to handle the multiple existing syntax options for the realtime and grading-time syntax checking. Finally, it shows how the assertions system works. The workflow is the following: 1. Editing question: Displays the user interface to define the question statement (static in this case), the general options, and the syntax options. Displays a WIRIS editor applet to enter the correct answer. Real-time syntax checking is done in the applet when editing the correct answer. JavaScript is used to automatically set up the applet grammar for syntax checking when the syntactic options change. Displays a minimal interface to choose the assertions to be applied when grading the question. 2. Displaying question: Saves the question definition. Displays the question statement and a WIRIS editor applet to enter the user s answer. Real-time syntax checking is done. 3. Grading question: Save the user s answer. Calls WIRIS quizzes service to check all the assertions. Grades the answer depending on the value of such assertions. Displays some feedback. fillintheblanks.jsp: This example shows how to build a fill in the blanks question, i.e., a single question with multiple answer fields. It also exemplifies how to use distinct concrete assertions for distinct purposes. Compared to the previous example, it gives a lighter and less powerful- interface to define syntactic options and assertions. The workflow is: 1. Editing question: Displays the user interface to define the question. This user interface consists of four instances of a light version of the previous interface; one for each blank in the question. Note also that we can use syntactic options although we do not use the WIRIS editor. 2. Displaying question: Saves the question definition. Composes the question statement with inserted text input fields. 3. Grading question: Saves the user s answers. Calls the WIRIS quizzes service to apply the assertions on each respective answer. Grades the question based on this and displays some feedback. editorfillintheblanks.jsp: This example is the same as the previous fillintheblanks.jsp but now we use always the WIRIS editor instead of input text elements. Since the logic of the question workflow is identical, we will focus on this distinct feature. This example needs the WIRIS plugin core installed. The approach is different from the other example assertions.jsp where the editor is embedded in the page. Now, every math input element -the correct answer and the user answer fields- are images. When the user clicks such an image, a popup with a WIRIS editor is opened, with the proper content and grammar loaded. The user can edit the content inside the applet and the image will be updated when the popup is closed. This process works as follows: 1. The JSP outputs some HTML code like
2010, Maths for More WIRIS quizzes in your assessment system. V1 13 <span id="formula0" class="formulainput"> <span class="mathml"><math xmlns=...</math></span> <img class="editoricon" src="img/editor.gif" alt="click to edit" title="click to edit" /> <input type="hidden" class="mathml" id="correctanswer0" name="correctanswer0" value="<math xmlns..."/> <input type="hidden" class="context" id="context0" name="context0" value="expression" /> </span> The first element is a span enclosing the MathML code to be rendered. The img element is simply a WIRIS editor icon. The two following hidden input elements are respectively where we will save the MathML and the context the grammar. 2. When the page is loaded, a JavaScript function looks for all these elements and uses AJAX to call the WIRIS plugin core to convert the MathML into URLs of images. Furthermore, it will add the event click to the new image and to the editor icon. 3. When the user clicks over any of the two images, a popup window with a WIRIS editor applet is shown. The MathML and the grammar are loaded into the applet. 4. When the user finishes the edition. The MathML and the context are updated, and the WIRIS plugin core is called again to convert that MathML to an image. Architecture The previous JSP files contain almost only the user interface. Each JSP has a big switch depending on the question stage. The first stage is edit, when the teacher defines the question. The second stage is display, and it is the question preview. The third stage is grade, when the user gets the grade and feedback depending on the responses given in the previous stage. Each of the JSP files is related to a Java Bean. All these classes extend the superclass AbstractQuestion. These bean classes have two purposes: Supply and retrieve data from the user interface. Implement the question-type specific logic. Thus, these java beans are a link between the user interface and the generic class AbstractQuestion. This class implements the connection with the service, including the serialization and interpretation of the XML messages. It also contains several data structures and methods that might be useful for their child classes. In other words, this class works as a library for accessing the WIRIS quizzes service, and it can be a good starting point for developing a Java client library for WIRIS quizzes service. To get into the implementation details, go directly to the source code, included also in the war package next to class files. The AbstractQuestion.java file is full of comments in order to clarify the code.
2010, Maths for More WIRIS quizzes in your assessment system. V1 14 Install WIRIS plugin core Here it will be explained how to install the WIRIS plugin core. In order to get a more extensive point of view of this technology see the documents at http://www.wiris.com/plugins/docs/resources/integrating-wiris-elsewhere. The WIRIS plugin core is a war file suitable to be installed in any Java application container such as Tomcat. 1. Get the WIRIS Java plugin core from http://www.wiris.com/quizzes/docs/generic. 2. Copy the configured pluginwiris_engine.war into your application container deploy folder. 3. Go to http://your.server.com/pluginwiris_engine/app/test and check that all tests are ok. 4. Go to http://your.server.com/quizzes-api-jsp/editorfillintheblanks.jsp and check that the images are displayed. This is sufficient to have all working. However, we can turn on the image cache system and choose the more appropriated Image Service for better performance. This is done by editing two configuration files: 1. Edit the web.xml file inside pluginwiris_engine.war. Set the two parameters cachedirectory and formuladirectory to writable folders. 2. Edit pluginwiris_engine.war\web-inf\pluginwiris\configuration.ini in order to change the WIRIS editor Image Service location to your own server. 3. See http://www.wiris.com/plugins/docs/editors/generic for more details on both configuration files. 4. Go again to the test pages and check that all is ok.