Skip to content

API

Jump to bottom
Scott Herbst edited this page Jun 7, 2016 · 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=commShell.findComponentInstance ("mytextbox");
aComponent.move (10,20);

  • move(newX,newY)

    • Arguments:
      • <Integer> - New X coordinate
      • <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()

    • Arguments:
      • <Integer> width
      • <Integer> height
    • Returns:
      • None
    • Description: defines the pixel width and height of the component.

  • setVisible ()

    • Arguments:
      • <Boolean> TRUE | FALSE
    • Returns:
      • None
    • Description: renders the component visible when TRUE, or invisible when FALSE.

  • setX ()

    • Arguments:
      • <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 ()

    • Arguments:
      • <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 ()

    • Arguments:
      • <Integer> Width
    • Returns:
      • None
    • Description: sets the width (in pixels) of the component to the specified integer value.

  • setHeight ()

    • Arguments:
      • <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 commShell. So for example the first function below would be called as:

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

  • gradeSAI ()

    • Arguments:
      • <String> Selection
      • <String> Action
      • <String> Input
    • Returns:
      • None
    • Description:

  • showFeedback ()

    • Arguments:
      • <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 ()

    • Arguments:
      • <Object> processing function
    • Returns:
      • None
    • Description:

  • assignGradingHandler ()

    • Arguments:
      • <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 ()

    • Arguments:
      • <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 ()

    • Arguments:
      • <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 ()

    • Arguments:
      • <String> aName
      • <String> aCompName
    • 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 ()

    • Arguments:
      • <String> aName
      • <String> aCompName
    • 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 ()

    • Arguments:
      • <String> aClass, the name of a class you want to get.
    • Returns:
      • <Object> Returns a pointer to a object of type CTATComponent
    • Description

##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 global listener:

commShell.addGlobalEventListener(processCTATEvent);

function processCTATEvent (anEvent,aMessage)
{
  if (anEvent=="StartState")
  {
    alert ("Start state finished, tutor ready for input");
  }
}

Example using a specific listener:

commShell.addEventListener("StartStateEnd",processStartStateFinished);

function processStartStateFinished (aMessage)
{
  alert ("Start state finished, tutor ready for input");
}

Events as the result of an incoming tutoring message:

  • Start state finished

    • String: StartState
    • Description:

  • Interface received a StartStateEnd message

    • String: StartStateEnd
    • Description:

  • Problem done

    • String: ProblemDone
    • Description:

  • Process problem summary

    • String: ProblemSummary
    • Description:

  • Correct: Message

    • String: CorrectAction
    • Description:

  • Incorrect Message

    • String: InCorrectAction
    • Description:

  • Interface received a highlight message

    • String: HighlightMsg
    • Description:

  • Interface received an unhighlight message

    • String: UnHighlightMsg
    • Description:

  • Interface received an StateGraph message

    • String: StateGraph
    • Description:

  • Interface received an StartProblem message

    • String: StartProblem
    • Description:

  • Interface received an AssociatedRules message

    • String: AssociatedRules
    • Description:

  • Interface received an BuggyMessage message

    • String: BuggyMessage
    • Description:

  • Interface received an SuccessMessage message

    • String: SuccessMessage
    • Description:

  • Interface received an InterfaceAction message

    • String: InterfaceAction
    • Description:

  • Interface received an InterfaceIdentification message

    • String: InterfaceIdentification
    • Description:

  • Interface received an AuthorModeChange message

    • String: AuthorModeChange
    • Description:

  • Interface received an ResetAction message

    • String: ResetAction
    • Description:

  • Interface received an ShowHintsMessage message

    • String: ShowHintsMessage
    • Description:

  • Interface received an ConfirmDonemessage

    • String: ConfirmDone
    • Description:

  • Interface received an VersionInfo message

    • String: VersionInfo
    • Description:

  • Interface received an TutoringServiceAlert message

    • String: TutoringServiceAlert
    • Description:

  • Interface received an TutoringServiceError message

    • String: TutoringServiceError
    • Description:

  • Interface received an ProblemSummaryResponse message

    • String: ProblemSummaryResponse
    • Description:

  • Interface received an ProblemRestoreEnd message

    • String: ProblemRestoreEnd
    • Description:

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:

  • 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 has clicked the Next button in the hint window

    • String: NextPressed
    • Description:

  • Student has clicked the Previous button in the hint window

    • String: PreviousPressed
    • Description:

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