Configuring CTAT Flash Tutors with FlashVars

Last updated July 11, 2013

This page is out of date. See the latest Flashvars reference.

What is FlashVars?

FlashVars is a common way to assign variables for a Flash movie from an HTML document. This method is used extensively by CTAT Flash tutors, which are commonly included in HTML pages for viewing over the web (see Delivering CTAT Flash Tutors for instructions on how to generate such an HTML file).

When the Flash tutor (ie, the SWF) loads in a browser, it looks for the FlashVars parameter in HTML and, if found, converts the name-value pairs into variables that the Flash tutor can use. This mechanism is not unique to CTAT tutors, and can be used by any Flash movie for initializing data (see Adobe's FlashVars documentation for more information).

CTAT uses the flashvars parameter for a variety of things. These include setting:

  • logging parameters needed to satisfy the OLI logging DTD and the PSLC logging DTD;
  • the path to the logging library (CommLoggingLibrary.swf);
  • the path to the question (.BRD) file; and
  • the path to the video file (.FLV) when using the Video Component.

Flash logging flow: Flashvars

How to specify FlashVars for CTAT tutors

The way in which you specify flashvars for your tutors depends on the delivery framework you are using.

  • Online Learning Initiative (OLI): specify flashvars as parameters in OLI workbook pages (XML)
  • TutorShop: flashvars are generated dynamically based on tutor information contained in the TutorShop database
  • No delivery application (standalone pages): Use the CTAT_FlashPublish template from the Flash IDE to generate HTML, which contains a FlashVars stub that you can modify.
  • Your own application: Use the CTAT_FlashPublish template from the Flash IDE to generate HTML, which contains a FlashVars stub that you can examine for learning the flashvars syntax.

From Adobe's documentation:

The format of [FlashVars] is a set of name=value combinations separated by '&'. Special and/or non-printable characters can be escaped with a '%' followed by a 2 digit hexadecimal value. A single blank space can be represented using the '+' sign.

FlashVars is given in a single string enclosed by double quotes. In HTML, it will look like:

<object ...>
<param name="FlashVars" value="log_service_url=http://www.loggingserver.com&
question_file=media/problemFileName.brd&problem_name=fractionaddition&
..."
</object>

In the above simplified example, the first name=value combination consists of log_service_url for the name, and http://www.loggingserver.com for the value.

Include as many or as few flashvars as you'd like. Consult the tables below for deciding which parameters to include.

FlashVars Parameters and Values

The tables below present a list of FlashVars parameters that are commonly used by CTAT Flash tutors. For a simple, non-logging tutor, only question_file is required.

Table 1. Tutoring parameters
NameDefault ValueDescription
question_filemyGraphName.brdThe behavior graph to be load. Relative to the HTML document. Required for logging.

To use repetition, specify multiple question_file and problem_name values in Flashvars. For example, "question_file=abc.brd:def.brd&problem_name=probABC:probDEF&..." CommShell will load each problem in succession, triggered by the done correct action. If multiple question_file values are given, but zero problem_name values, the tutor will use the question_file name for logging: it will use the current BRD file name without the '.BRD'.
BehaviorRecorderModeRunTime The data mode of the CommShell component. This corresponds to the CommShell property named Behavior Recorder Mode. If this parameter is missing from flashvars, the CommShell will use the value specified in the component property (settable in the Flash IDE). Possible values are: RunTime, AuthorTime, or AuthorTimeTutoring.
media_filec.flvThe name and path of the video file that plays. The path is relative to the Flash movie (SWF). The media file should be a .FLV or .MP3 format file
TutorCuePointNameTutorCuePointThe name of the cue point. The video pauses at this time. Used by the video component, CommAudioVideo.
TutorCuePointTime5The time of the cue point in seconds. The video pauses at this time. Used by the video component, CommAudioVideo.
MediaPathThe path to media files (MP3, JPG, etc) used in the problem. Used by Jumble and MediaMultipleSelection. Relative to the HTML document.
VideoPathThe path to FLV (Flash Video) files used in the problem. Used by Jumble and MediaMultipleSelection. Relative to the Flash movie (SWF).
RandomizeAnswersUsed by Jumble, MediaMultipleSelection, and MultipleSelection. Can be true or false. When true, the order of answer items will be random.

Show fewest parameters required for logging

Table 2. Logging* parameters
NameDefault ValueDescription
LoggingNoneSpecify logging source and destination. Can also be set via the CommShell property of the same name. If not set in FlashVars, CommShell will use the value specified in its component property. Possible values:
  • ClientToLogServer: Flash client sends log messages to log server using the Flash Logging Library
  • ServiceToLogServer: Tutoring Service sends log messages to log server
  • ServiceToDisk: Tutoring Service stores log messages to its disk
  • ServiceToDiskAndLogServer: Tutoring Service stores log messages to disk AND sends to log server.
  • None: no logging
LoggingLibraryPathhttp://learnlab.web.cmu.edu/swf/CommLoggingLibrary.swfThe path or URL to the logging library SWF. Required when Logging is set to ClientToLogServer. Path relative to the HTML document. The canonical URL for accessing the logging library over the Web is http://learnlab.web.cmu.edu/swf/CommLoggingLibrary.swf
Can also be set via the CommShell property Logging Library. If not set in FlashVars, the tutor will use the CommShell property.
log_service_urlhttp://pslc-qa.andrew.cmu.edu/log/server The URL of a web service for logging. Required for 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
problem_nameDefaults to the value of question_fileThe name of the problem. When using repetition, you can specify multiple problem_name values, separated by the ":" character for logging. See question_file.
problem_contextA text description of the problem or how the problem is being used.
problem_tutorflagA description of the problem type. DataShop prefers one of: tutor, test, pre-test, post-test, or other. If other, then specify a value in problem_otherproblemflag
problem_otherproblemflagA description of the problem type that does not fit the categories in problem_tutorFlag. This parameter is ignored unless problem_tutorFlag is set to other.
dataset_nameRequired for logging. Appears in DataShop as the name of the dataset
dataset_level_name[1-9]Required for logging. Can specify up to 9 nested levels. Example: dataset_level_name1=Fractions dataset_level_type1=Unit
dataset_level_type[1-9]Required for logging. Can specify up to 9 nested levels. Example: dataset_level_name2=FractionAddition dataset_level_type2=Section
course_nameDeprecated; if used, will map to dataset_name
unit_nameDeprecated; If used, will map to dataset_level_name1
section_nameDeprecated; if used, will map to dataset_level_name2
school_nameSchool where these data will be collected.
class_nameName of the class
period_nameName or number of the class period
class_descriptionDescription of the class
instructor_nameName of the instructor
study_condition_name[1-9]Name to identify the study condition; can specify up to 9 conditions that apply to these data. Example: study_condition_name1=Personal study_condition_name2=Unworked
study_condition_type[1-9]Type of study condition; can specify up to 9 conditions that apply to these data.
study_condition_description[1-9]A description of the study condition; can specify up to 9 conditions that apply to these data.
user_guidmyUniqueUserIdentifierA unique user id used for logging. If using the OLI course delivery system, OLI supplies this.
session_idmySessionIDA unique session id. If using the OLI course delivery system, OLI supplies this.
auth_tokenmyAuth_tokenA unique authorization token. If using the OLI course delivery system, OLI supplies this.
container_idmyContainerA unique ID. If using the OLI course delivery system, OLI supplies this.
source_idPACT_CTAT_FLASHThe name of the tutor source. Can be changed to identify your project.
external_object_idmyExternalIdA unique object id. If using the OLI course delivery system, OLI supplies this.
DeliverUsingOLItrueIf 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
  • external_object_id
If DeliverUsingOLI is false, you are responsible for authentication and providing values for the above parameters.

* OLI-supplied values are inserted by the OLI course delivery system when the XML workbook pages are transformed to HTML.

These parameters map to elements in the tutor message DTD, version 4.

Table 3. Tutoring Service parameters
NameDefault ValueDescription
log_to_disk_directory. (a single dot)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.
cognitive_model_folderFor a cognitive tutor, the path to the folder containing cognitive model files (eg, production rules, WME, and template files)
remoteSocketURLlocalhostThe URL to the Tutoring Service; used when BehaviorRecorderMode is AuthorTimeTutoring (for Tutoring Service) or AuthorTime (for Behavior Recorder). This can also be set in the CommShell Socket URL property. If remoteSocketURL is not set in FlashVars, the tutor will use the property from the CommShell.
remoteSocketPort1502The port on which the Behavior Recorder or Tutoring Service is listening.
Table 4. TutorShop parameters
NameDefault ValueDescription
study_nameThe name of the study. Inserted by the TutorShop servlet.
curriculum_service_urlInserted by the TutorShop servlet.
admit_codeTutorShop admit code for the course. Often corresponds to the experimental condition of the study.
student_problem_idSimilar to the user_guid property. A user indentifier that the TutorShop uses.