• Adding Internationalization Support
• Problem to Problem Navigation
• Using a Tutoring Service
• Tutor Configuration
• Embedding a BRD File
• Dynamically Creating CTAT Components
• CORS Headers

We provide a means for authors and LMS developers to add support for alternative languages. Currently we provide a means for users to override the static text each tutor uses. In order to override these static strings all an author has to do is include a JavaScript file or JavaScript block as such:

var CTATLanguagePack =
{
        "HORIZONTAL" : "LR", // Accepted values are: LR, RL
        "VERTICAL" : "TB",      // Accepted values are TB, BT
        "LOADING" : "Please wait while the tutor is being loaded",
        "NEXTPROBLEM" : "Retrieving the Next Problem...",
        "CONGRATULATIONS_YOU_ARE_DONE": "Congratulations, you are done with this problem.",
        "SURE_YOU_ARE_DONE": "Are you sure you are done?",
        "TUTORDISCONNECTED" : "The tutor has disconnected. Please refresh the page.",
        "OUTOFORDER" : "You need to do other steps first, before doing the step you just worked on. You might request a hint for more help.",
        "DONE" : "Done",
        "HINT" : "Hint",
        "NEXT" : "Next",
        "PREVIOUS" : "Previous",
        "HIGHLIGHTEDSTEP" : "Instead of the step you are working on, please work on the highlighted step.",
        "NOTDONE" : "I'm sorry, but you are not done yet. Please continue working.",
        "AUTHORPLEASECLOSE" : "Authoring Tools disconnected. Please close this page.",
        "ERROR_502" : "Error contacting the server, please refresh the page and try again (HTTP status 502: gateway response).",
        "ERROR_CONN_TS" : "Connection refused by tutoring service, please check your server or contact an administrator.",
        "ERROR_CONN_LS" : "Connection refused by the logging server, please check your connection or contact an administrator.",
        "AWAITING_OTHER_COLLABORATORS": "Waiting for other team members..."
};

Please make sure this is added before the link tag that loads the ctat.min.js library. For example, this would be a proper way to include such a language pack file:

<script src="https://cdn.ctat.cs.cmu.edu/releases/latest/jquery.min.js"></script>
<script src="http://yourwebsite.com/german.language.js"></script>
<script src="https://cdn.ctat.cs.cmu.edu/releases/latest/ctat.min.js"></script>

Our API allows you to assign what we call a 'done processor'. It's a function that gets called when the problem is finished. We consider a problem finished when the student has clicked and traversed the done step successfully. Of course this can be quite subtle since the graph or the cognitive model might operate in suppressed feedback mode. In those cases please consult our documentation on graph behavior. For most cases however the meaning of 'done' and complete is pretty straightforward.

Assign a done processing function like this:

function myDoneFunction (aSummary)
{ 
   // Inspect the problem summary 'aSummary' xml in case
   // you need to get more information about how well the student
   // did

     document.location.href = "nextPage.html";
}

CTATCommShell.commShell.assignDoneProcessor ("myDoneFunction");

Normally the tutor will be configured by the ctatloader.js file to work directly with the API of the LMS it runs in. In those cases you do not have to worry about how to go to the next problem or how to finish a sequence of problems. Use the code above only for those cases where you want to have full control as to what the tutor does when the student finished.

Your function will be called with a String argument called aSummary, which contains a block of XML the LMS or any other system needs to know the full state of the student within the context of the problem he or she just finished. It might also contain information of previously finished problems.

Example Problem Summary

<ProblemSummary ProblemName="birthday" CompletionStatus="complete" Correct="22" UniqueCorrect="22" UniqueCorrectUnassisted="22" Hints="0" UniqueHints="0" HintsOnly="0" Errors="0" UniqueErrors="0" ErrorsOnly="0" UniqueSteps="22" TimeElapsed="77450">
  <Skills>
    <Skill name="Choose_operation" category="Decimal-Addition-and-Subtraction" description="Choose operation" label="Choose operation" opportunityCount="1" pGuess="0.2" pKnown="0.68" pLearn="0.2" pSlip="0.1" />
    <Skill name="Enter_addends" category="Decimal-Addition-and-Subtraction" description="Enter addends" label="Enter addends" opportunityCount="9" pGuess="0.2" pKnown="0.9999995" pLearn="0.2" pSlip="0.1" />
    <Skill name="Enter_decimal_point" category="Decimal-Addition-and-Subtraction" description="Enter decimal point" label="Enter decimal point" opportunityCount="3" pGuess="0.2" pKnown="0.9856923" pLearn="0.2" pSlip="0.1" />
    <Skill name="Sub_column_with_borrow" category="Decimal-Addition-and-Subtraction" description="Sub column with borrow" label="Sub column with borrow" opportunityCount="4" pGuess="0.2" pKnown="0.99742776" pLearn="0.2" pSlip="0.1" />
    <Skill name="Sub_column_with_no_borrow" category="Decimal-Addition-and-Subtraction" description="Sub column with no borrow" label="Sub column with no borrow" opportunityCount="4" pGuess="0.2" pKnown="0.99742776" pLearn="0.2" pSlip="0.1" />
  </Skills>
</ProblemSummary>

The meaning of the ProblemSummary attributes and skill elements are described in more detail here. The Skills list has the same format as in the flashvars, but contains values updated after the student interaction with the tutor.

The problem_state parameter is an XML structure containing a number of message elements which describe the current state of the tutor. The LMS doesn't need to know or interpret the structure in any way, it only needs to store it in some place, so it can send it back to the tutor on request.

You can split a tutor's functionality into 1) the user interface the student interacts with, and 2) the software that generates the customized instruction and feedback. We call that second piece of functionality the tutoring engine. The tutoring engine is available in JavaScript (for example-tracing tutors only) and in Java (for example-tracing and cognitive tutors).

By default, deployed HTML interfaces use the JavaScript tutoring engine. For some projects, however, you might choose to use the Java version, especially if you want to use a cognitive model written in Jess. HTML tutors can use the Java tutoring engine by connecting to the Java Tutoring Service. If you deploy your tutor to TutorShop, the TutorShop server runs a tutoring service that tutors can connect to.

If you want to run your own tutoring service, you will need:

• A web accessible place to store your .html and BRD files.
• The Tutoring Service executable installed with CTAT.

The Tutoring Service listens for incoming connection requests on HTTP port 12022 by default.

Note

The Tutoring Service also listens on port 12043 for HTTPS, port 20080 for websocket, port 20443 for secure websocket, and port 1502 for TCP connection requests.

For HTML tutors you will want to configure them to use HTTP as shown in the example below.

• Set the communication type as "http".
• Set the host name of the machine running the Tutoring Service. You can use "http://localhost" only if your tutors and Tutoring Service are on the same machine.
• Set the default HTTP port (12022) in your tutor configuration.

<html>
<head>
<link rel="stylesheet" href="https://cdn.ctat.cs.cmu.edu/releases/latest/CTAT.css"/>

<style>
html,body { width: 100%; height: 100%; margin: 0px; padding: 0px; }
</style>

<script src="https://cdn.ctat.cs.cmu.edu/releases/latest/jquery.min.js"></script>
<script src="https://cdn.ctat.cs.cmu.edu/releases/latest/ctat.min.js"></script>
<script src="https://cdn.ctat.cs.cmu.edu/releases/latest/ctatloader.js"></script>

<script>

 var myVars = 
 {
   question_file: "ctat-manual-tutor-creation-example-01.brd",
   tutoring_service_communication: "http",
   remoteSocketURL: 'http://localhost',
   remoteSocketPort: '12022'
 };	

 function ctatOnload ()
 {
   initTutor(myVars);
 }

</script>
</head>
<body>
   ...
</body>
</html>

To start the Tutoring Service:

• On Windows, double-click the TutoringService.exe file in the CTAT installation directory.
• On Macs, double-click the TutoringService.command file in the CTAT installation directory.

If you need to use a port other than the default, you can create a batch file that starts the Tutoring Service with the appropriate command line arguments. For example, the following command starts a Tutoring Service (on Windows) with HTTP port 8081:

java -cp ".;..;lib\ctat.jar" -DDebugCodes=tsltsp,tsltstp  edu.cmu.pact.TutoringService.LauncherServer -t 1499 -h 8081

The Tutoring Service can work with both Flash and HTML tutors, which is why you see two port specifications in the command-line arguments. For HTML tutors you want to configure the -h port and set that in your tutor configuration.

<script>

 var myVars = 
 {
   question_file: "ctat-manual-tutor-creation-example-01.brd",
   tutoring_service_communication: "http",
   remoteSocketURL: 'http://localhost',
   remoteSocketPort: '8081'
 };	

 function ctatOnload ()
 {
   initTutor(myVars);
 }

</script>

In some of the tutor examples and HTML fragments, you've seen how you can set parameters that determine how a tutor starts up and how it should behave. The relevant part in your .html file would look something like this:

<script>
 var myVars = 
 {
    question_file: "ctat-manual-tutor-creation-example-01.brd",
    tutoring_service_communication: "javascript"
 };	

 function ctatOnload ()
 {
   initTutor(myVars);
 }
</script>

You can configure a tutor to run in standalone mode (in a web server like Apache, for example) by providing values for predefined configuration parameters. In the example above we use two of them to tell the tutor where the brd file is located and how the tutor should communicate with the example tracer code. There are many available configuration parameters you can use to test and run your tutor in your own web server. Please be advised though that, when you run via an LMS (such as TutorShop, Moodle, EdX, Blackboard, etc.), the LMS will overwrite the parameters as it sees fit. Note that, in the following table, only those parameters marked with 🔸 will not be overwritten by the LMS. All other parameters will be overwritten.

The following configurable parameters are available:

If necessary you can now include a BRD file directly into an html tutor page.

• Encode your BRD file using this page, which will return an encoded string.
• Prepend the following string to the encoded BRD you created in the previous step: <data:file/brd;base64>
• Configure the question_file parameter with the complete string you just created, like so:

var myVars =
{
   question_file: "data:file/brd;base64,PD94bWwgdmVyc2lvb ...",
   tutoring_service_communication: "javascript"
};

The current assumption is that all of the CTAT components needed for your interface are already in the DOM when initTutor() is called. If you would like to generate components dynamically, for example, based on some other external specifications, then controlling when initTutor() is called will likely be important. Typically, initTutor() is called on the ready event, but it can be called at other times when delivered through different Learning Management Systems. If you dynamically generate components, then you might need to overload initTutor() to make sure everything is called in the correct order. To do this, simply define your own initTutor(configuration) in the global environment and make sure to call CTATTutor.initTutor(configuration) when you have finished generating all of your CTAT components. For example:

<script>
function initTutor(configuration) {
  $.get('my_interface_information.xml').done(function(data) {
      // process 'data' which causes some new CTAT Components to be generated...
      CTATTutor.initTutor(configuration);
  });
}
</script>

At some point you might want to enable CORS headers in your Apache installation. This ensures that your tutors can load assets from your webserver no matter where you deployment. For more information on how to enable this feature, please see the official CORS documentation for Apache and other servers.

From Wikipedia:

Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources (e.g. fonts) on a web page to be requested from another domain outside the domain from which the resource originated.

A web page may freely embed images, stylesheets, scripts, iframes, videos and some plugin content (such as Adobe Flash) from any other domain. However embedded web fonts and AJAX (XMLHttpRequest) requests have traditionally been limited to accessing the same domain as the parent web page (as per the same-origin security policy). "Cross-domain" AJAX requests are forbidden by default because of their ability to perform advanced requests (POST, PUT, DELETE and other types of HTTP requests, along with specifying custom HTTP headers) that introduce many cross-site scripting security issues.

CORS defines a way in which a browser and server can interact to safely determine whether or not to allow the cross-origin request. It allows for more freedom and functionality than purely same-origin requests, but is more secure than simply allowing all cross-origin requests. It is a recommended standard of the W3C.