Skip to content

Home

Jump to bottom
Scott Herbst edited this page May 31, 2016 · 72 revisions

How a Tutor Works

To get started with tutoring and tutor authoring you need a little bit of information on how we actually run a tutor and what a tutor is.

From Wikipedia: An intelligent tutoring system (ITS) is a computer system that aims to provide immediate and customized instruction or feedback to learners, usually without intervention from a human teacher.

Following the definition above you can split a tutor's functionality into the user interface the student interacts with and the software that generates the customized instruction and feedback. We call that last part the tutoring engine.

The Macro-view of Tutor Development and Deployment

A tutor is built by creating an HTML page that contains the tutor interface, then using our CTAT Behavior Recorder to demonstrate and record the best possible way to solve a problem using your interface. The output of this process is an HTML file (with additional css, js, etc if required) and a BRD file (Behavior Recorder Diagram). To run the tutor for a student you would either import the BRD and HTML file to a Learning Management System (See the section on LMSs below) or simply configure the html with the name of your BRD file and run it directly from a web server.

Once you have a finished and configured HTML file you need to decide how you will run the tutoring engine. There are two options. You could run your html file in a browser and have it connect to a Tutoring Service. A Tutoring Service is a Java application that contains the Java version of our tutoring engine. It runs on a remote server and can be configured by giving the proper parameter values in your HTML file. For more information on how to do that, see the section: Using a Tutoring Service. There is also Option 2, which is the default. In that configuration the tutoring engine is built into our Javascript library and will run in the browser. For most users this is the most ideal option, but beware that for very large BRD files it might put a lot of strain on the browser. If you wish to setup a system that uses a tutoring service then please follow the instructions in the [#ts related section] below.

CTAT Tutor Overview

#Overall Tutor Building Workflow

  • Download and install CTAT and start CTATforFlash.

  • Make a new HTML project with the wizard. It produces an HTML interface with the characteristics you want, and a behavior graph to manage tutor behavior

  • At which point, if you want to modify the interface, open the HTML file directly in a text editor and make the changes there

  • You can modify tutor behavior with the Demonstrate function of the Behavior Recorder

The best way to create a new HTML5 tutor is to use our wizard. This will create a folder with all the files you need and a basic tutor that has everything properly configured. You can access the wizard from within the Behavior Recorder like such:

Image of Yaktocat

#What you need to get started

All you should need to build HTML5 tutors with CTAT are the installed authoring tools, a good text editor and this documentation. For those who want to run experiments on their local machine it is wise to install a version of the Apache webserver. Most users however end up uploading their tutors to a Learner Management System (LMS) such as Tutorshop, EdX, Coursera, etc.

We recommend a good text editor, such as:

Throughout our set of examples we provide links to our Javascript libraries and CSS file. However if you like you can download the latest version here and include them manually:

#Manually Creating an HTML Tutor

We are assuming you would like to create an intelligent tutor using only HTML, meaning an HTML page with some associated CSS styles and some JavaScript. The documentation in this page will help you create such a tutor and show you how you can deploy the tutor on a variety of Learner Management Systems (LMSs). Before we begin let's take a look at the two main ways you might want to think about your tutor in HTML.

Full Page vs. Fixed-Size Tutors

You might want to consider which tutor you would like to create beforehand. One is not better than the other but we've noticed that certain layouts are better for certain designs. For example, if you intend to deploy on mobile platforms then we would suggestion you use a tutor that scales with the page. These tend to be more basic tutors where it is quite obvious how the content will be scaled and positioned by something like Bootstrap. For more complicated tutors where you want more control over the visual layout and navigation flow we would suggest you use a fixed layout tutor as seen in option 2.

It is our experience from running many studies in classrooms that a good rule of thumb is to make a fixed tutor no bigger than 920 pixels wide by 720 pixels high.

In general a tutor is a div with id "container" with any number of child divs configured as CTAT components by our Javascript library. To tell the library that a div is really a tutorable component you would do something like this:

<div id="done-button" class="CTATDoneButton"></div>

The id gives the component a unique name, which you will be using in the behavior recorder and which forms what we call the selection part of the SAI (More on SAIs in a different section). All you need besides a unique id is a class, which does two things. It assigns appropriate CSS styles to the div and it identifies the div as a CTAT component. At startup our library will traverse the document and customize any div that has one of our reserved CTAT class names assigned to it.

Let's look at a very basic fixed size tutor and see what is involved in writing such a tutor. Here is the most basic tutor you could build:

<html>
<head>

<link rel="stylesheet" type="text/css" href="http://ctat.pact.cs.cmu.edu/html5releases/latest/CTAT.css">

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

<script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="http://ctat.pact.cs.cmu.edu/html5releases/latest/ctat.min.js"></script>
<script src="http://ctat.pact.cs.cmu.edu/html5releases/latest/ctatloader.js"></script>

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

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

<div id="container" style="margin: 0px; padding: 0px; text-align:center; border: 1px solid black;">
	<div id="done-button" class="CTATDoneButton" style="position: absolute; top:0; left: 0; right: 0; bottom: 0; margin: auto;"></div>
</div>

</body>
</html>

(You can get the BRD file used in this example here: ctat-manual-tutor-creation-example-01.brd. Simply place it in the same directory as you've created the html file)

If you save the above HTML in a file and open that file in a browser, you should see the following page with a single centered Done button. This is what could be thought of as the most minimal tutor that could be built. Please note that we use some CSS to have the Done button centered in the interface. You might want to use a different way of laying out your components.

Image of Interface with Done Button

Remember that so far we have been building a tutor using a fixed absolute layout. This might not be the best way to design your tutor but it works well for tutors that were designed from a rigid layout as provided by paper and pencil test results. Below is a more complete example of a fixed position tutor with a Done button, Hint button and Hint window:

<html>
<head>

<link rel="stylesheet" type="text/css" href="http://ctat.pact.cs.cmu.edu/html5releases/latest/CTAT.css">

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

<script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="http://ctat.pact.cs.cmu.edu/html5releases/latest/ctat.min.js"></script>
<script src="http://ctat.pact.cs.cmu.edu/html5releases/latest/ctatloader.js"></script>

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

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

<div id="container" style="margin: 0px; padding: 0px; text-align:center; border: 1px solid black;">
	<div id="done-button" class="CTATDoneButton" style="position: absolute; top:300; left: 425;"></div>
	<div id="hint-button" class="CTATHintButton" style="position: absolute; top:380; left: 425;"></div>
	<div id="HintWindow" class="CTATHintWindow" style="position: absolute; top:300; left: 5; width: 400px; height: 145px;"></div>	
</div>

</body>
</html>

(You can get the BRD file used in this example here: ctat-manual-tutor-creation-example-01.brd. Simply place it in the same directory as you've created the html file)

If you cut and paste the above tutor HTML into an .html file and open that file with your favorite browser you should see the tutor shown below: Image of an interface with a Hint Window and Done Button

You can also mix and match fixed sized tutors with dynamic tutors, documented further down in a separate section. All of our components honor any CSS width and height parameters set in HTML. For example you can create a fixed sized tutor, but within the tutor area you can keep things scalable to fit the tutor size. Take a look at the code below, which demonstrates how you can setup a control panel in the bottom of your tutor using a table:

<html>
<head>

<link rel="stylesheet" type="text/css" href="http://ctat.pact.cs.cmu.edu/html5releases/latest/CTAT.css">

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

<script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="http://ctat.pact.cs.cmu.edu/html5releases/latest/ctat.min.js"></script>
<script src="http://ctat.pact.cs.cmu.edu/html5releases/latest/ctatloader.js"></script>

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

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

<div id="container" style="display: table; width:550; height:450px; border: 1px solid black; border-spacing: 2px;">
	<div style="display: table-row; height:100%;">
	Main Component Area
	</div>
	<div style="display: table-row; height: 125px;">
	  <div style="display: table-cell; border: 0px solid black; vertical-align: middle;">
		<div id="HintWindow" class="CTATHintWindow" style="width: 100%; height: 100%"></div>	
	  </div>
	  <div style="display: table-cell; width: 60px;">
		<div style="border: 0px solid black; margin-bottom: 2px;">
			<div id="hint-button" class="CTATHintButton"></div>
		</div>
		<div style="border: 0px solid black;">
			<div id="done-button" class="CTATDoneButton"></div>	
		</div>
	  </div>
	</div> 
</div>

</body>
</html>

(You can get the BRD file used in this example here: ctat-manual-tutor-creation-example-01.brd. Simply place it in the same directory as you've created the html file)

As you can see from the screenshot below you end up with an optimal layout giving you the maximum area in the top center to place any problem specific components.

Image of Yaktocat

#Manually Creating a Fraction Tutor Step by Step

This is how to create a basic CTAT Tutor using HTML.

  1. Start a .html document. If you are not sure how to do this, check out this tutorial.

  2. Include the following:

    • required external libraries (jQuery): <script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>

    • A link to our CSS file: <link rel="stylesheet" href="http://ctat.pact.cs.cmu.edu/html5releases/latest/CTAT.css"/>

    • A link to our JS library: (ctat.min.js is the result of 'grunt ctat' and includes everything) <script src="http://ctat.pact.cs.cmu.edu/html5releases/latest/ctat.min.js"></script>

    • For a stand alone html tutor, follow the Javascript example below. This is the minimum you need to get a tutor started. You can either use the JQuery usage shown here or place the initTutor call in an onLoad.

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

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

    • Somewhere in the <body>, there will need to be a container <div> like this:

      <div id="container" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; z-index: 400;">
</div>

      The CTAT code will automatically add a canvas inside the container div for drawing purposes. If the author so desires this canvas can be specified manually and will be used by the tutor as long as the id is set to "main-canvas"

      <div id="container" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; z-index: 400;">
  <canvas id="main-canvas" width="800" height="700">Your browser does not support CTAT. Please update or use another browser.</canvas>
</div>

  3. Adding CTAT components:

    • Add a <div> component with a unique id and one of our component name in the class list. For example: <div id="my_button" class="CTATButton">My Button</div>

    • Component parameters can be changed with additional attributes on the div with a data-ctat- prefix. For example to make #my_button untutored: <div id="my_button" class="CTATButton" data-ctat-tutor="false">My Button</div>

      • Supported parameters:
        • data-ctat-tutor="true|false"
        • data-ctat-show-feedback="true|false"
        • data-ctat-disable-on-correct="true|false"
        • data-ctat-show-hint-highlight="true|false"

  4. Changing look:

    • positioning can be handled in the style parameter of defining <div> : <div id="my_button" class="CTATButton" style="margin:5px; display: inline-block;">My Button</div>

    • Look and feel parameters should be set using css. For example: <style type="text/css"> .CTATRadioButton { width: auto; } #my_button { background-color: pink; } </style>

  5. Do not forget to add a hint button and a hint window, for example something like the following:
    <div id="hint-box" style="height: 157px; padding: 5px;"> <div id="hint-button" class="CTATHintButton" style="margin: 0 5px 5px 5px; display: inline-block"></div> <div id="HintWindow" class="CTATHintWindow" style="display: inline-block; width: 400px;"></div> </div>

  6. A Done button should also be included in most tutors: <div id="done-button" class="CTATDoneButton"></div>

#Component Specific Notes

##Parameters of all tutorable components

  • Show Hint Highlight, Whether or not the component becomes highlighted when a hint is displayed that corresponds to the component

  • Tutor Component, Options are Tutor, Tutor but no visual feedback, or Do not tutor. With Tutor, a component is both highlighted or its text turns red or green after the student interacts with it. When set to Tutor but no visual feedback, the interactions cause tutoring to occur within CTAT, but no visual feedback appears in Flash. The component lock, however, on a correct attempt, and hint requests concerning that component will appear. With Do not tutor, the component acts as if it were a standard Flash component: interacting with the component does not trigger example-tracing to occur within CTAT, nor does it show visual feedback or lock.

  • Disable on Correct, Controls whether or not the component will lock after a correct attempt. Note that this parameter will override the setting in the behavior graph Lock Widgets on Correct Action. Both default to true. If a behavior graph is set to suppress feedback, the component will never lock regardless of this parameter's setting.

##Parameters of all components with visible text

  • Font Bold
  • Font Face
  • Font Italic
  • Font Size
  • Font Underlined
  • Text Align, Options are Left, Right, Center, and Justified
  • Text Color

##Parameters of all text input components

  • Background Color
  • Disabled Background Color
  • Disabled Text Color

##Standard Components

CTATAudioButton

Image of Yaktocat

Quick Example:

<div id="audiobutton" class="CTATAudioButton" data-ctat-src="https://drive.google.com/uc?export=view&id=0BwGsdDsj8yYcTXZFc2hHZUx5VW8">Listen</div>

Image of Yaktocat

CTATButton

Image of Yaktocat

Quick Example:

<div id="button" class="CTATButton">Click Me</div>

CTATDragNDrop

Image of Yaktocat

Quick Example

<div id="source" name="dndtest" class="CTATDragNDrop"> <div id="dndtext1">Drag Me</div> <div id="dndtext2">Drag Me Too</div> </div>

CTATDoneButton

Image of Yaktocat

Quick Example:

<div id="done" class="CTATDoneButton">Done</div>

CTATGroupingComponent

Quick Example:

<div id="groupA" class="CTATGroupingComponent">Done</div>

CTATHintButton

Image of Yaktocat

Quick Example:

<div id="hint" class="CTATHintButton">Hint</div>

CTATHintWindow

Image of Yaktocat

Quick Example:

<div id="hintwindow" class="CTATHintWindow"> </div>

CTATNumberLine

Image of Yaktocat

Quick Example:

<div id="numberline" class="CTATNumberLine"> </div>

CTATSkillWindow

Image of Yaktocat

Quick Example:

<div id="skillwindow" class="CTATSkillWindow"> </div>

CTATHintWindow

Image of Yaktocat

Quick Example:

<div id="table" class="CTATTable" data-num-rows="3" data-num-cols="2"> </div>

CTATTextArea

![Image of Yaktocat]http://ctat.pact.cs.cmu.edu/images/commtextarea-as3.png)

Quick Example:

<div id="textarea" class="CTATTextArea"> </div>

CTATTextInput

![Image of Yaktocat]http://ctat.pact.cs.cmu.edu/images/commtextinput-as3.png)

Quick Example:

<div id="textinput" class="CTATTextInput"> </div>

CTATTextField

Note: this is the component to use for Tutor controlled text that should be static for a student. It is also the text component that can display HTML. Yes, it does understand all of the various tutoring options, but they are unlikely to be used as the text itself is not modifyable by students by default, but there is a way to make it editable via css.

Quick Example

<div id="textfield" class="CTATTextField"> </div>

CTATVideo

Image of Yaktocat

Quick Example:

<div id="videoplayer" class="CTATVideo" src="https://drive.google.com/uc?export=view&id=0BwGsdDsj8yYceWtUUE9LTUtWZ28"> </div>

CTATCheckBox

CTATRadioButton

Image of Yaktocat

<div>RadioButtons: <div id="rb1" class="CTATRadioButton" name="rbGroup" style="margin:5px; display: inline-block;">Nope</div> <div id="rb2" class="CTATRadioButton" name="rbGroup" style="margin:5px; display: inline-block;">Yes</div> <div id="rb3" class="CTATRadioButton" name="rbGroup" style="margin:5px; display: inline-block;">Never</div> </div>

CTATComboBox

Image of Yaktocat

Use the tag to list options. Quick Example:

<div id="combo" class="CTATComboBox" style="margin:5px; display: inline-block;"> <option>----</option> <option>select</option> <option>do not select</option> </div>

CTATFractionBar

Image of Yaktocat

Quick Example:

<div id="fb" class="CTATFractionBar" data-ctat-value="1/3+1/3+(0*1/3)" style="margin:5px; display: inline-block;"></div>

CTATPieChart

Image of Yaktocat

Quick Example:

<div id="pc" class="CTATPieChart" data-ctat-value="1/3+1/3+(0*1/3)" style="margin:5px; display: inline-block;"></div>

CTATSubmitButton

Image of Yaktocat

Quick Example:

<div id="fb_submit" class="CTATSubmitButton" data-ctat-target="fb" style="display:inline-block;">Submit Fraction Bar</div>

CTATJumble

Image of Yaktocat

Quick Example:

<div id="jumble" class="CTATJumble" style="margin:5px; display: inline-block;"> <div id="item1">a</div> <div id="item2">brown</div> <div id="item3">quick</div> <div id="item4">fox</div> </div>

Note: this component is still in development as the interaction in HTML is a bit different than in Flash.

#Working With Logging

If you are building tutors you most likely want to be able to find out how well your students are doing. CTAT tutors are equipped with a logging module that can transcribe all user interaction to a logging service such as DataShop. There are various way this can be accomplished. By default the tutor starts a copy of the Logging Library which will try to contact a log service url (if provided). Most if not all user interaction can be logged automatically using this mechanism and the author doesn't need to intervene other than to configure the tutor with some basic information as to the context of a specific problem, class, school, etc.

Authors can also manually call the logging library embedded in the tutor and add custom events to be logged. For more information on how to manually drive the logging library please consult the Logging Documentation page.

#Deploying Your Tutor

When providing your tutor to one of the many existing Learner Management Systems (LMSs), you will be providing the exact same page as you've created before. Please notice how we do not make a configuration call to set the name of the BRD or any other configuration like logging options. The ctatloader in collaboration with the specific deployment environment will take care of all these steps.

See below for a typical example:

When building your html tutor file, please take the following criteria into account if you want to deploy to one of the listed LMSs:

  • Always use a https source for external files, e.g. css and js files not bundled with your tutor. For example https://code.jquery.com/jquery-2.1.4.min.js is a valid url to use but http://code.jquery.com/jquery-2.1.4.min.js will not work. This is due to the fact that code.jquery.com does not provide proper headers when serving the file resulting in a cross origin error.

  • Make sure you know which parameters will be picked up from the ones coded in your html file and which ones will be overwritten by the LMS. For example in the example above the question_file parameter is only used in what we call standalone mode, where you run your tutor through your own webserver. In every other case the BRD file name will be provided by the LMS you're running on.

Image of Yaktocat

We highly encourage you to use the Export feature available in the Behavior Recorder. This will bring up a wizard that will guide you through the process of packaging your tutor for a specific LMS. Please consult the platform specific notes below for any information that will help you once you've produced an LMS package with the wizard.

== Local Deployment (e.g. Apache or other webserver)

Most of the time you will want to use an LMS to run your tutor since it provides grading and better student tracking. But sometimes it might be useful to run a tutor by itself in a browser. In those cases you can execute your tutor from a browser served by a webserver.

WARNING! It is very important to run your tutor from a an address in your browser that starts with http:// or https:// You can not run a tutor by with something like: file://tutor.html This will cause security violations when the tutor tries to load a BRD file.

Image of Yaktocat

== SCORM (Moodle, Blackboard)

Currently we support SCORM 1.2, which is compatible with most platforms that support SCORM packages. We have tested our code against Moodle and Blackboard but we expect any other system to behave similarly that supports SCORM.

  • For blackboard please see this page for detailed information

  • For Moodle, please consult the following documentation

== LTI

  • In TutorShop, upload your behavior graph (.brd) and user interface files using the Packages screens. For simplicity, use a package name that has no spaces or special characters.
  • In TutorShop, define the problem sets your package provides; again it's helpful to use problem set names that have no spaces or special characters.
  • In TutorShop, create or edit a school instance for your integration. You need to fill in 2 items on the school Settings page; remember these values for use with the LMS:

1. Consumer Key
2. Consumer Secret

Note that you don't have to put "CTAT" as the first item in the passport. The idea is you have to choose an LTI ID, "CTAT" is a good default to make the passport unique and tracable to a tutor, it can be anything, you just need to make sure you use the same one in the LTI units afterwards. So an LTI passport is just a way edX created so you don't have to put the consumer key and secret on each LTI unit, you store them in the course settings associated with an ID and then just use the ID. Thanks for updating the instructions.

== OLI

Integration with OLI can be quite elaborate if you start from a fresh new curriculum. The documentation for this process is therefore quite substantial and we provide a full version in its own location. For information on how to import the generated tutor package please navigate to the official OLI deployment documentation. For information on how the CTAT team directly imports tutors please click Here to navigate to the OLI deployment documentation.

== OpenEdX (XBlock)

#Advanced Topics

##Dynamic Interfaces

Steps in a behavior graph can be either student-performed (steps the student should perform) or tutor-performed (steps that the tutor itself should perform). While a student-performed step specifies behavior the student should perform while using the tutor, a tutor-performed step specifies an action that the tutor software will perform on the interface. Tutor-performed steps are therefore powerful links that can be used to complete problem-solving steps, make changes to the student interface such as hiding or showing a widget, or perform other actions that you specify.

Image

By default, demonstrated steps are stored in the behavior graph as correct steps that a student should perform when using the tutor. Steps such as these have an actor of student; that is, they are performed by the student. For steps where the tutor performs the step, the actor is the tutor itself—a tutor-performed action.

To specify a tutor-performed action

  • Create a new link (optional) - while in Demonstrate mode, demonstrate a step in the student interface. For steps that cannot be demonstrated (e.g., hiding an interface widget), create a blank step in the graph by right-clicking a node in the graph and choosing Add Blank Step.

  • Right-click (Windows) or Control+Click (Mac) on the action label of the link in the graph for which you'd like to specify a tutor-performed action.

  • Select Edit Student Input Matching

  • To the right of Actor, select Tutor (unevaluated)

Image

Note: A tutor-performed action (TPA) can be evaluated or unevaluated. An evaluated TPA is graded (as if the student performed the step), while an unevaluated TPA is not graded. Use unevaluated TPAs for steps that cannot be demonstrated, such as hiding, locking, and highlighting widgets.

Timing of tutor-performed actions

A tutor-performed action can be state-triggered or link-triggered. This option can be set at the bottom of the Edit Student Input Matching dialog. If "On current state" is selected, the tutor-performed action link is activated when the state preceding it becomes the current state. If "On previous link" is selected, the tutor-performed action link is activated when the link preceding it is traversed.

Often used TPAs

Each component supports a number of specific function calls but all components support a common set of calls. Below is the total list of common methods and their arguments:

  • SetVisible ()

* Argument
* true/false
* Description, Show or hide the widget named by the selection

  • lock ()

* Argument
* none
* Description, Disable a component for input. This is reversible by calling unlock.

  • unlock ()

* Argument
* none
* Description, Enable a component for input. This is reversible by calling lock.

  • highlight ()

* Argument
* none
* Description, Show a yellow glowing highlight halo around the component. This is the same method as used by the tutoring engine to show to a user that a certain step should be taken.

  • unhighlight ()

* Argument
* none
* Description, Remove a previously set highlight glow.

You can use the TPA methodology to simulate a remote procedure call. In other words you can call your own functions directly from the graph. In order to do so create a new empty link in the graph and open the matcher window for that link. For the Selection enter "root", the Action can be any function name you want to create in JavaScript and the Input field can hold any string you want to send over to your interface. Make sure that at the bottom of the matcher dialog window you set the Actor to Tutor (unevaluated). You can see the matcher configuration we've used for the corresponding JavaScript example below:

Image(https://drive.google.com/uc?export=view&id=0BwGsdDsj8yYcM1hubnp0aHFrQVk,475px)

##CORS Headers

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.

##Adding Internationalization Support

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:

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:

##Problem to Problem Navigation

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:

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

The meaning of the ProblemSummary attributes and skill elements are described in more detail [ProblemSummary 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.

[=#ts]

##Using a Tutoring Service

Most users will prefer using what we call the onboard tracer, which is a javascript implementation of our original Java based tracer code. For some projects however you might choose to use the Java version, especially if you want to use a cognitive model written in Jess. The HTML5 tutors can use the Java tracer through a wrapper called the Tutoring Service. If you've installed CTAT from our release page you will have all the necessary tools to get started. Most importantly you will need:

  • A web accessible place to store your BRD file

  • A batch file that starts the Tutoring Service with the appropriate command line arguments. For example the following template starts a generic Tutoring Service (on Windows):

Our Java code can work with both Flash and HTML5 tutors, which is why you see two port specifications. The one you will want to configure is the -h port, since that is what you will use in your Javascript tutor configuration.

<html>
<head>
<link rel="stylesheet" href="http://ctat.pact.cs.cmu.edu/html5releases/latest/CTAT.css"/>

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

<script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="http://ctat.pact.cs.cmu.edu/html5releases/latest/ctat.min.js"></script>

<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>
</head>
<body>

<div id="container" style="margin: 0px; padding: 0px; text-align:center; border: 1px solid black;">
	<div id="done-button" class="CTATDoneButton" style="position: absolute; top:0; left: 0; right: 0; bottom: 0; margin: auto;"></div>
</div>

</body>
</html>

##Tutor Configuration

In the previous tutor examples and fragments you've seen how you can set some of the settings that determine how a tutor starts up and how it should behave. The relevant part in your page to do so would look like:

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

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

You can configure the tutor 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 webserver. Please be advised though that when you run via an LMS (such as Moodle, EdX, Blackboard, etc) it is the LMS that 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.

In total we currently have the following configurable parameters available:

Parameter Name Default Value Description
admit_code "ies" Description
authenticity_token "none" Description
auth_token "none" A unique authorization token.
BehaviorRecorderMode "AuthorTimeTutoring" The mode of the Flash tutor. Possible values are: AuthorTime (for connecting to the Behavior Recorder) and AuthorTimeTutoring (for connecting to a Tutoring Service).
class_name "" Name of the class
curriculum_service_url "" '[host]/process_problem_set/[parameters]' or '[host]/process_student_assignment/[parameters]'. Command that processes the problem summaries
dataset_level_name "" Required for logging. Can specify multiple nested levels. Example: dataset_level_name1=Fractions dataset_level_type1=Unit
dataset_level_name1 'Unit1' Description
dataset_level_type1 'unit' Description
dataset_level_type "ProblemSet" Required for logging. Can specify multiple nested levels. Example: dataset_level_name2=FractionAddition dataset_level_type2=Section
dataset_name "FlashLoggingTest_xxx" Required for logging. Appears in DataShop as the name of the dataset
expire_logout_url "none" '[host]/admin/logout?type=expire'. Command that logs the user out on session expiration.
info "" html containing the problem caption.
instructor_name "none" Name of the instructor
instrumentation_log "off" Debugging parameter. 'off', 'on' or 'verbose'
lcId "none" Description
Logging "None" 'ClientToService', 'ClientToLogServer', 'ServiceToLogServer', 'ServiceToDisk', 'ServiceToDiskAndLogServer'
log_service_url "http://pslc-qa.andrew.cmu.edu/log/server" The URL of a web service for logging. Required for ClientToLogServer logging. The default value is the URL of the Pittsburgh Science of Learning Center (PSLC) QA logging server, which should be used for testing. When logging for a PSLC study, log to the LearnLab production machine: http://learnlab.web.cmu.edu/log/server
log_to_disk_directory '.' The path name for the directory in which disk logging files will be stored. If the value is a relative path, it is relative to the value of the Projects dir preference at LauncherServer startup.
keyboard 'disabled' Description
problem_name "xxx" The name of the problem.
problem_position "none" Description
problem_started_url "none" Description
problem_state_status "empty" 'empty', 'complete', or 'incomplete'
question_file "" The path to the behavior graph to load. Can be a relative path (if the BRD is located on the same machine as the Tutoring Service), in which case the path is relative to the Tutoring Service, or a full URL—the BRD does not need to be located on the same machine running the Tutoring Service.
refresh_session_url "none" '[host]/admin/refresh_session'
remoteSocketPort "80" The port on which the Tutoring Service is listening.
remoteSocketURL "http://localhost" The host name of the machine running the Tutoring Service. If remoteSocketURL is not set in FlashVars, the tutor will use the property from the CommShell.
restore_problem_url "none" '[host]/restore_student_assignment/[parameters]'
reuse_swf "false" 'true' or 'false'. Should we reuse the SWF from problem to problem?
run_problem_url "none" '[host]/run_student_assignment/[parameters]' or '[host]/run_problem_set/[parameters]'. Command that starts the next tutor. Location from which to receive the next problem (as HTML) if the Flash SWF is not being reused.
school_name "none" School where these data will be collected.
SessionLog "true" 'true' or 'false'. Determines whether or not to send a session log message at the beginning of a session. If true, Flash should send the session log, not the LMS.
session_id "none" Generated by the learner management system (LMS) and used in all log messages.
session_timeout "none" number of seconds to wait before the session times out
skills "" XML containing the set of skills of interest for the current tutor
source_id "PACT_CTAT_HTML5" "PACT_CTAT_HTML5" or 'HTML5'FLASH_PSEUDO_TUTOR' or 'CTAT_JAVA_TUTOR'
student_interface "none" current tutor's full .swf path. Used for loading assets given a relative path, and for reuse_swf.
student_problem_id "none" Description
study_condition_name "" Name to identify the study condition; can specify multiple conditions that apply to these data (e.g., study_condition_name1=mycondition).
study_condition_type "" Type of study condition; can specify multiple conditions that apply to these data.
study_condition_description "" A description of the study condition; can specify multiple conditions that apply to these data.
study_name "Study1" Description
target_frame "none" name of html frame where tutor is runname of html frame where tutor is run
TutorShopDeliveryMethod "sendandload" Description
tutoring_service_communication 'javascript' 'socket', 'javascript', 'http', 'https', 'applet', 'websocket'
user_guid "qa-test" Description
DeliverUsingOLI false If delivering the tutor outside of the OLI course delivery system, set this to false and specify values for the following parameters: user_guid, session_id, auth_token, container_id, source_id and external_object_id. If DeliverUsingOLI is false, you are responsible for authentication and providing values for the above parameters.
ssl "off" Description
sui "" Description
centerTutor false Description
previewMode false Description

##Embedding a BRD File

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:

##Dynamically Generating CTATComponents

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>

CTAT: Cognitive Tutor Authoring Tools, Software for authoring intelligent tutor behavior

CTAT Documentation

Getting Started
Using CTAT
HTML Components
TutorShop
Additional Documentation
In Development
Clone this wiki locally