API

Sometimes you might want to change something in the interface dynamically or you might want to add your own code that responds to tutoring events and takes specific action that isn't provided with the CTAT library. We try to make our tutorable components as accessible and as open as possible, so we've made our internal API accessible and we've added a number of function calls that can help you gain more control over the behavior of your tutor. For example in the past we've seen authors who needed an external module that calculated additional student performance data. That particular author used our event listening API to monitor incoming messages from the tutoring engine. Others have used events and API calls to add animation and visual effects to tutors.

Global

initTutor(configObj, container, id)
- Arguments:
  - configObj - <Object> CTATConfiguration object created with generateDefaultConfiguration().
  - container - <String> id of the tutor canvas, defaults to 'container'. (Optional)
  - id - <String> id of an html5 canvas, managed by the tutor and scaled to tutor area for backdrop drawing. (Optional)
- Returns:
  - None
- Description:
centerTutorContainer()
- Arguments:
  - None
- Returns:
  - None
- Description: If you're using an absolute layout, in other words a fixed size tutor, then you can call this function to center the tutor on the page if the page has been resized. This function is called by default when the tutor starts.

CTAT Components

For all the methods documented below they should be called on a component instance. For example:

var aComponent=CTATShellTools.findComponentInstance("mytextbox");
aComponent.move(10,20);

move(newX, newY)
- Arguments:
  - newX - <Integer> X coordinate.
  - newY - <Integer> Y coordinate.
- Returns:
  - None
- Description: Moves the component to a new location on the screen. The x, y coordinates represent the upper left corner of the component relative to the parent div or page.
setSize(newWidth, newHeight)
- Arguments:
  - newWidth - <Integer> Width.
  - newHeight - <Integer> Height.
- Returns:
  - None
- Description: Defines the pixel width and height of the component.
setVisible(isVisible)
- Arguments:
  - isVisible - <Boolean> TRUE | FALSE
- Returns:
  - None
- Description: Renders the component visible when TRUE, or invisible when FALSE.
setX(newX)
- Arguments:
  - newX - <Integer> X coordinate.
- Returns:
  - None
- Description: Sets the upper left corner X value of the component to the integer specified relative to the parent div or page.
setY(newY)
- Arguments:
  - newY - <Integer> Y coordinate.
- Returns:
  - None
- Description: sets the upper left corner Y value of the component to the integer specified relative to the parent div or page.
setWidth(newWidth)
- Arguments:
  - newWidth - <Integer> Width
- Returns:
  - None
- Description: Sets the width (in pixels) of the component to the specified integer value.
setHeight(newHeight)
- Arguments:
  - newHeight - <Integer> Height
- Returns:
  - None
- Description: Sets the height (in pixels) of the component to the specified integer value.

CTATCommShell (class) Manually Grading and Processing Feedback

All of the functions in this section are methods in the CTATCommShell class and can be accessed through the commShell object. So, for example, the gradeSAI function below would be called as:

CTATCommShell.commShell.gradeSAI("button1","ButtonPressed","-1");

The handler functions require a function that takes two arguments. For example, to add a grading handler to a non-CTAT button:

<head>
  ...
  <script>
    function buttonCheck(indicator, msg)
    {
      alert("buttonCheck: "+indicator+", "+msg.getSAI().getInput());
    };
  </script>
</head>
<body onload="CTATCommShell.commShell.assignGradingHandler(buttonCheck);">
  ...
  <button id="b" type="button" onclick="CTATCommShell.commShell.gradeSAI('b', 'BPressed', 'wrong');">Wrong</button>
</body>

gradeSAI(selection, action, input)
- Arguments:
  - selection - <String> The component ID.
  - action - <String> The component action.
  - input - <String> The component input.
- Returns:
  - None
- Description:
showFeedback(text)
- Arguments:
  - text - <String> Text or string to be displayed in the hint window if available or any other component that has indicated it can handle feedback.
- Returns:
  - None
- Description: Shows the text or string argument in the hint window if available or any other component that has indicated it can handle feedback.
assignFeedbackHandler(fn)
- Arguments:
  - fn - <Function> fn(aString, aMessage). A callback function that will be called with two arguments: aString, which will be either "CORRECT" or "INCORRECT", and aMessage, which is an object of type CTATMessage. The CTATMessage object can be used to find out which component the feedback is meant for, what the feedback is and any suggested alternative steps in case of an "INCORRECT". Please see the API documentation for CTATMessagefor more information.
- Returns:
  - None
- Description:
assignGradingHandler(fn)
- Arguments:
  - fn - <Function> fn(aString, aMessage). A callback function that will be called with two arguments: aString, which will be either "CORRECT" or "INCORRECT", and aMessage, which is an object of type CTATMessage. The CTATMessage object can be used to find out which component the grading result is meant for, what the feedback is and any suggested alternative steps in case of an "INCORRECT". Please see the API documentation for CTATMessagefor more information.
- Returns:
  - None
- Description: Use this method to provide CTAT with a means to give you feedback on any custom components (divs, html widgets, etc) with respect to grading. This method is the processor called by the CommShell on processing the return result of gradeSAI. Note: this method differs from assignAnonymousGradingProcessor in that the CommShell will not called the assigned grading handler if assignAnonymousGradingProcessor has assigned a global grading override function.
assignAnonymousGradingProcessor(fn)
- Arguments:
  - fn - <Function> fn(aString, aMessage). A callback function that will be called with two arguments: aString, which will be either "CORRECT" or "INCORRECT", and aMessage, which is an object of type CTATMessage. The CTATMessage object can be used to find out which component the grading result is meant for, what the feedback is and any suggested alternative steps in case of an "INCORRECT". Please see the API documentation for CTATMessagefor more information.
- Returns:
  - None
- Description: Use this method to provide CTAT with a means to give you feedback on any custom components (divs, html widgets, etc) with respect to grading. This method is the processor called by the CommShell on processing the return result of gradeSAI. Note: if you assign a handler using this method than only this will be called when receiving grading results.
assignDoneProcessor(fn)
- Arguments:
  - fn - <Function> fn(aString). A callback function that will be called with one argument: aString, which is an XML string containing problem summary information. This function is called after a short delay when the tutor has determined that the student has successfully completed the problem.
- Returns:
  - None
- Description: Use this method to provide CTAT with a means to give you feedback when the student has completed a problem.
- Example:

   <head>
     ...
      <script>
        function processDone(msg)
        {
          console.log("processDone: "+msg);
          window.location.replace("../index.html");
        };
      </script>
    </head>
    <body onload="CTATCommShell.commShell.assignDoneProcessor(processDone); ">
      ...
      <div id="done" class="CTATDoneButton" tabindex="9"></div>
      ...
    </body>

CTATShellTools (class)

findComponent(aName)
- Arguments:
  - aName - <String> Component ID.
- Returns:
  - <Object> Returns an array of pointers to objects of type CTATComponent
- Description: Because an HTML id attribute value should be unique to an element, the returned array usually has at most a single element. If the id is for a group, such as the id for a CTATRadioButton group, the returned array has an element for each button in the group.
findComponentInstance(aName)
- Arguments:
  - aName - <String> Component ID
- Returns:
  - <Object> Returns a pointer (or an array of pointers) to a object of type CTATComponent.
- Description: If aName is the id of a CTAT component, a pointer to that component is returned. If the id is for a group, such as the id for a CTATRadioButton group, an array is returned with an element for each button in the group.
findComponentByClass(aClass)
- Arguments:
  - aClass - <String> The class name of the component you want to get.
- Returns:
  - <Object> Returns a pointer to a object of type CTATComponent.
- Description: Finds the first component with the specified class name.

CTATConfiguration (class)

The CTATConfiguration class enables you to configure and retrieve settings for your tutor. See Tutor Configuration for more information on the values you can get and set.

CTATConfiguration.set("dataset_name", "MyDataset");
CTATConfiguration.get("dataset_name");

var myConfig = CTATConfiguration.generateDefaultConfigurationObject();
myConfig.get("problem_name");

generateDefaultConfiguration()
- Arguments:
  - None
- Returns:
  - <Object> Returns a configuration object (CTATConfiguration) containing configuration key, value pairs
- Description:
setTutorWidth(width)
- Arguments:
  - width - <Number> Tutor width in pixels.
- Returns:
  - None
- Description:
setTutorHeight(height)
- Arguments:
  - height - <Number> Tutor width in pixels.
- Returns:
  - None
- Description:
setTutorDimensions(width, height)
- Arguments:
  - width - <Number> Tutor width in pixels.
  - height - <Number> Tutor height in pixels.
- Returns:
  - None
- Description:

CTATMessage (class)

CTATSAI (class)

CTATScrim (class)

A class with only static methods that can be used to either block the tutor for important feedback, ask the user an out-of-tutoring question or show a warning. Typical usage is:

var myScrim = new CTATScrim();
myScrim.scrimUp('The scrim is up');

scrimUp(aMessage)
- Arguments:
  - aMessage -<String> A static text message.
- Returns:
  - None
- Description: Pulls up the wait scrim.
waitScrimUp(aMessage)
- Arguments:
  - aMessage - <String> A static text message.
- Returns:
  - <None>
- Description: Pulls up the wait scrim displaying a pre-defined message. Please see the language pack section on how to configure that message.
OKScrimUp(aMessage, aFunction)
- Arguments:
  - aMessage - <String> A static text message.
  - aFunction - <Function> Function to call when the user clicks Ok.
- Returns:
  - <None>
- Description: Pulls up a scrim with a dialog message of aMessage, and executes aFunction when the ok button is clicked.
confirmScrimUp(prompt, onYes, onNo)
- Arguments:
  - prompt - <String> A static text message.
  - onYes - <Object> Function to call when the user clicks Yes.
  - onNo - <Object> Function to call when the user clicks No.
- Returns:
  - <None>
- Description: Pulls up a scrim with a prompt message, and function handlers for clicking on yes/no buttons.
errorScrimUp(aMessage)
- Arguments:
  - aMessage - <String> A static text message.
- Returns:
  - <None>
- Description: Pulls up a non-removable scrim displaying an error message aMessage.
warningScrimUp(aMessage)
- Arguments:
  - aMessage - <String> A static text message.
- Returns:
  - <None>
- Description: Pulls up scrim displaying a warning message aMessage, and may only be closed when the close button is clicked.
scrimDown()
- Arguments:
  - <None>
- Returns:
  - <None>
- Description: Pulls down the scrim if it is in a state that allows it to be pulled down.

Events

Through our event mechanism developers can augment their tutor by listening for either message traffic between the interface and the tracer (or cognitive model) or be informed of important events that arise from within the interface itself. Events are added through the CommShell instance. Please note that you will only be notified of an event, you will not be able to intercept or block these events (yet).

Example using a listener for message traffic:

startStateEndListener =
{
  processCommShellEvent: function (anEvent, aMessage)
  {
    if (anEvent=="StartStateEnd")
    {
      alert ("Start state finished, tutor ready for input");
    }
  }
};

document.addEventListener("tutorInitialized", function() {CTATCommShell.commShell.addGlobalEventListener(startStateEndListener)});

Here is a more elaborate example showing one use of the AssociatedRules message. This message provides the selection-action-input of the tutor engine's answer to the last step attempted by the student. The code below will show this answer in a call to alert() when the tutor evaluates the student's entry as incorrect.

assocRulesListener =
{
    processCommShellEvent: function(evt, msg)
    {
        if("AssociatedRules" != evt || !msg)
        {
            return;
        }
        var indicator = msg.getIndicator();
        var sai = msg.getSAI();                               // selection-action-input from tutor engine
        var selection = (sai ? sai.getSelection() : "_noSuchComponent_");
        var comps = CTATShellTools.findComponent(selection);  // array of components with this name
        var component = (comps && comps.length ? comps[0] : null);
        if(component && "incorrect" == indicator.toLowerCase())
        {
            alert("Tutor's answer is "+sai.toString());
        }
    }
};

document.addEventListener("tutorInitialized", function() {CTATCommShell.commShell.addGlobalEventListener(assocRulesListener)});

Events as the result of an incoming tutoring message:

Start state finished
- String: StartStateEnd
- Description: The tutor has completed that part of initialization that results from settings in the HTML student interface itself and from values stored while authoring in CTAT's Set Start State mode.
Correct message
- String: CorrectAction
- Description: The tutor engine has evaluated the student's entry on a step as correct.
Incorrect message
- String: InCorrectAction
- Description: The tutor engine has evaluated the student's entry on a step as incorrect.
Interface received a highlight message
- String: HighlightMsg
- Description: The tutor engine has asked the HTML interface to highlight a component.
Interface received an unhighlight message
- String: UnHighlightMsg
- Description: The tutor engine has asked the HTML interface to remove highlighting.
Interface received an StateGraph message
- String: StateGraph
- Description: The message contains problem-wide parameters, such as whether the tutor is to show feedback for this problem.
Interface received an StartProblem message
- String: StartProblem
- Description: The message signals the start of the initializing values recorded while authoring in CTAT's Set Start State mode.
Interface received an AssociatedRules message
- String: AssociatedRules
- Description: The message contains all the data from the tutor engine in response to a student step. This message provides the data for the tutor_message sent to DataShop when logging is on.
Interface received an BuggyMessage message
- String: BuggyMessage
- Description: The message provides the feedback text an author has provided for a modeled error. By default, the text is displayed in the Hint Window.
Interface received an SuccessMessage message
- String: SuccessMessage
- Description: The message provides the optional feedback text an author has provided for display when a student has completed a step correctly. By default, the text is displayed in the Hint Window.
Interface sent or received an InterfaceAction message
- String: InterfaceAction
- Description: The message transmits the selection-action-input tuple for a student- or tutor-performed action. Student-performed actions are sent to the tutor engine; tutor-performed actions are received from the tutor engine.
Interface received a ShowHintsMessage message
- String: ShowHintsMessage
- Description: The message supplies the tutor engine's full list of hint texts for a hint request. By default, the Hint Window shows these one at a time, in the given sequence. The Window's Previous and Next buttons let the student page back and forth through the individual hint texts.
Interface received a TutoringServiceError message
- String: TutoringServiceError
- Description: The message describes an error condition detected by the tutoring service. For example, the tutor's initialization parameters might have specified a behavior recorder (.brd) file that cannot be found.
Interface received a ProblemSummaryResponse message
- String: ProblemSummaryResponse
- Description: The message contains current skill values and transaction counts (number of correct steps, hint requests, etc.) for this problem so far.
Interface received a ProblemRestoreEnd message
- String: ProblemRestoreEnd
- Description: The message marks the end of tutor initialization. Prior to this message, the tutor engine may be replaying saved transactions, in order to resume a previously-suspended problem at the student's last step. After this message, student actions in the user interface will be evaluated by the tutor.

Events as the result of the student interacting with the interface. These events do not provide a pointer to a CTATMessage as the argument to the callback.

Student requests a hint
- String: RequestHint
- Description: The student pressed the hint button. The tutor engine will send back all hint texts defined for the next step in the problem. The Hint Window will display the first of these.
Student presses the done button
- String: DonePressed
- Description: this event fires when the student clicks the done button. Note that if in the graph 'confirm done' is configured the interface will first display an OK/Cancel dialog before this event fires
Student asks for the next hint text
- String: NextPressed
- Description: The student has clicked the Next button in the Hint Window.
Student asks for the previous hint text
- String: PreviousPressed
- Description: The student has clicked the Previous button in the Hint Window.

API - CMUCTAT/CTAT GitHub Wiki

API

Global

CTAT Components

CTATCommShell (class) Manually Grading and Processing Feedback

CTATShellTools (class)

CTATConfiguration (class)

CTATMessage (class)

CTATSAI (class)

CTATScrim (class)

Events

⚠️ GitHub.com Fallback ⚠️

API - CMUCTAT/CTAT GitHub Wiki

API

Global

CTAT Components

CTATCommShell (class) Manually Grading and Processing Feedback

CTATShellTools (class)

CTATConfiguration (class)

CTATMessage (class)

CTATSAI (class)

CTATScrim (class)

Events

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️