Skip to content

API

Jump to bottom
jsewall edited this page Feb 24, 2017 · 26 revisions

#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()

    • Arguments:
      • <Object> Configuration object created with generateDefaultConfiguration
      • <String> id of the tutor canvas, defaults to 'container' (Optional)
      • <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

##Methods Supported by Every Component

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

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

  • move(newX,newY)

    • Arguments:
      • newX <Integer> - New X coordinate
      • newY <Integer> - New 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 sections are methods in the CTATCommShell class and can be accessed through the global object CTATCommShell.commShell. So for example the first function below would be called as:

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

  • gradeSAI(s,a,i)

    • Arguments:
      • s <String> Selection
      • a <String> Action
      • i <String> 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 <Object> processing function
    • Returns:
      • None
    • Description:

  • assignGradingHandler(fn)

    • Arguments:
      • fn <Function> (String, CTATMessage), processing function, a function that will be called with two arguments: String: either CORRECT or INCORRECT and an object of type CTATMessage, which 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 CTATMessage for 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> (String, CTATMessage), processing function, a function that will be called with two arguments: String: either CORRECT or INCORRECT and an object of type CTATMessage, which 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 CTATMessage for 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 when receiving grading results.

  • assignDoneProcessor(fn)

    • Arguments:
      • fn <Function> (String), processing function, a function that will be called when the tutor has determined the student has successfully completed the problem. See more elaborate documentation above
    • Returns:
      • None
    • Description: see above

##CTATShellTools (class)

  • findComponent(aName, aCompName)

    • Arguments:
      • aName <String> Component ID
      • aCompName <String> Component ID (optional)
    • Returns:
      • <Object> Returns a list of pointers to a object of type CTATComponent
    • Description: aCompName is only needed for component groups such as radio buttons. We only get the name of the component group, which is only half useful. The actual component name is also needed.

  • findComponentInstance(aName, aCompName)

    • Arguments:
      • aName <String> Component ID
      • aCompName <String> Component ID (optional)
    • Returns:
      • <Object> Returns a pointer to a object of type CTATComponent
    • Description: aCompName is only needed for component groups such as radio buttons. We only get the name of the component group, which is only half useful. The actual component name is also needed.

  • 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)

  • setTutorWidth ()

    • Arguments:
      • <Object> Configuration object created with generateDefaultConfiguration
      • <Number> Tutor width in pixels
    • Returns:
      • None
    • Description:

  • setTutorHeight ()

    • Arguments:
      • <Object> Configuration object created with generateDefaultConfiguration
      • <Number> Tutor width in pixels
    • Returns:
      • None
    • Description:

  • setTutorDimensions ()

    • Arguments:
      • <Object> Configuration object created with generateDefaultConfiguration
      • <Number> Tutor width in pixels
      • <Number> Tutor height in pixels
    • Returns:
      • None
    • Description:

##CTATGlobalFunctions (class)

We've collected most globally used tutor specific functions in one class. Please note that these are not utility or shell functions, for those please consult the API documentation of CTATUtils and CTATShellTools respectively. Using this class is very straightforward:

CTATGlobalFunctions.generateDefaultConfiguration ();

You can see how we use the class in all the example tutors above.

  • generateDefaultConfiguration ()

    • Arguments:
      • None
    • Returns:
      • <Object> Returns a configuration object (CTATConfiguration) containing configuration key, value pairs
    • Description:

  • isCTATObject=function ()

    • Arguments:
      • <Object> Any Javascript object or variable
    • Returns:
      • <Boolean>
    • Description:

  • getCTATClassname ()

    • Arguments:
      • <Object> Any Javascript object or variable
    • Returns:
      • <String>
    • 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 ()

    • Arguments:
      • <Object> Any Javascript object or variable
    • Returns:
      • None
    • Description: Pulls up the wait scrim.

  • waitScrimUp ()

    • Arguments:
      • <String> Any Javascript object or variable
    • 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()

    • Arguments:
      • <String> A static text
      • <Object> 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:
      • <String> A static text
      • <Object> onYes: Function to call when the user clicks Yes
      • <Object> onNo: 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:
      • <String> Any sized static error text
    • Returns:
      • <None>
    • Description: Pulls up a non-removable scrim displaying an error message aMessage.

  • warningScrimUp(aMessage)

    • Arguments:
      • <String> Any sized static warning text
    • 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:

CTATCommShell.commShell.addGlobalEventListener(startStateEndListener);

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

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 an 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 an 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 an 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 an 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.

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