Part XIV: New Customization Features

This part of the tutorial is aimed at advanced developers who are interested using new TQS features in their own custom location types. Built-in capabilities, such as scoring, location state tracking, and playing sounds, are available to custom locations through new script functions.

First, TQS 2.5 adds several new functions for accessing and modifying XML data. These include xmlRetrieveEx, xmlGetText, xmlSetText, and xmlSetAttr. More information on these functions can be found in the Reference.

You can use TQS built-in scoring in your custom locations. To display the score table in the window, set the SHOWSCORE attribute of your CUSTOM_* element to "1". To actually change the score values, use the setScoreValue and offsetScoreValue functions. The latter function is most frequently used. Here is an example from the CUSTOM_MATCHING location type script, adapted from Part X of the tutorial:

<SCRIPT>
...

function loadMatchQuestion(first)
{
  ...
  // Increment the "Tried" score by 1
  offsetScoreValue(0, 1);
  ...
}

function onMatchEvent(evt, choice)
{
  if((canAnswerMatch == 1) &amp;&amp; (choice &lt;
    matchQuestionsUsed.length) &amp;&amp;
    (matchQuestionsUsed[choice] == 0))
  {
    switch(evt)
    {
      case 0:
        ...
        break;
      case 1:
        ...
        break;
      case 2:
        ...
        if(curMatchIndex == choice)
        {
          // Increment the "Correct" score by 1
          offsetScoreValue(1, 1);
          matchingStatus.innerText = matchCorrectString;
        } else
        {
          // Increment the "Incorrect" score by 1
          offsetScoreValue(2, 1);
          matchingStatus.innerHTML = matchWrongString +
            xmlAttr(xmlChildOf(xmlLocData, "ITEM",
            curMatchIndex), "A", "") + ".";
        }
        ...
    }
  }
}
</SCRIPT>

As shown in the script above, the three score values (Tried, Correct, and Incorrect) are represented by the numbers 0, 1, and 2, respectively.

To retrieve a current score value, use the getScoreValue function. More information on the scoring functions is available in the Reference.

If you include your location type (CUSTOM_*) in the INCLUDETYPES element of the REPORT element, it will automatically be included in the score report, using the score values that you set. However, you must manage the location's state yourself, using TQS's State Functions.

By default, your location's will be set to "PARTIAL" when invoked. You are responsible for setting the state to "DONE" (or "DONE100", if applicable) when the user has completed your location. The function setCurLocState allows you to do this.

<SCRIPT>
...

function onMatchEvent(evt, choice)
{
  if((canAnswerMatch == 1) &amp;&amp; (choice &lt;
    matchQuestionsUsed.length) &amp;&amp;
    (matchQuestionsUsed[choice] == 0))
  {
    switch(evt)
    {
      case 0:
        ...
        break;
      case 1:
        ...
        break;
      case 2:
        ...
        if(curMatchIndex == choice)
        {
          // Increment the "Correct" score by 1
          offsetScoreValue(1, 1);
          matchingStatus.innerText = matchCorrectString;

          // Set state to "DONE" if finished
          // (if number of questions tried equals total)
          if(getScoreValue(0) == numQuestions)
            setCurLocState("DONE");
        } else
        {
          ...
        }
        ...
    }
  }
}
</SCRIPT>

Other state functions, described in detail in the Reference, are:

getCurLocState, useful for seeing if this location has already been completed
getLocState, useful for seeing if a location that must be completed first has been completed
setLocState, useful for changing a different location's state

Also, the function getStateImg can be used to retrieve the image file that corresponds to a location state, should you wish to use these images in your location.

TQS also allows you to use the FINISH prompt and/or button(s) from your own custom locations. For instance, in the code sample above:

...
// Set state to "DONE" if finished
// (if number of questions tried equals total)
if(getScoreValue(0) == numQuestions)
{
  setCurLocState("DONE");

  // Display any finish buttons specified
  locFinished();
}
...

The locFinished function tells TQS to display the FINISH prompt and/or buttons, just as if it were a Questions or Hangman location.

In addition, you can use TQS's built-in correct and incorrect sound capabilities to invoke these sounds from your custom location, through the playSound function.

if(curMatchIndex == choice)
{
  // Increment the "Correct" score by 1
  offsetScoreValue(1, 1);
  matchingStatus.innerText = matchCorrectString;
  
  // Play the correct sound
  playSound(0);
  ...
} else
{
  // Increment the "Incorrect" score by 1
  offsetScoreValue(2, 1);
  matchingStatus.innerHTML = matchWrongString +
    xmlAttr(xmlChildOf(xmlLocData, "ITEM",
    curMatchIndex), "A", "") + ".";
  
  // Play the incorrect sound
  playSound(1);
}

As shown, passing 0 plays the correct sound, and 1 plays the incorrect sound. These sounds are retrieved from the CORRECT and INCORRECT elements of the current location's CUSTOM_FOO element, or if not specified there, from global settings.

Furthermore, you can have TQS play any sound file, by calling the playSoundFile function:

playSoundFile("mysound.wav");

TQS 2.5 adds the getDynVal function, to retrieve a dynamic value. For instance, the new USERNAME dynamic value contains the name that the user typed in at the Get Name screen (if the REPORT element's GETNAME attribute is set to "1"). Here is an example of how to use this:

function loadMatchQuestion(first)
{
  if(first)
  {
    greetingSpan.innerText = "Welcome, " +
      getDynVal("USERNAME") + ", to Matching!"
  }
  ...
}

In addition to the xmlLocData variable available since TQS 2.0, the new xmlCurLoc variable represents an XML object. Whereas the xmlLocData object represents the current location's CUSTOM_* subelement, the xmlCurLoc variable represents the current location's LOC element. Having access to this element allows you to access the non-location-specific data, such as ID and heading.

This section of the tutorial has given an overview of how custom location types can use new built-in TQS features. Again, the TQS Reference contains more detailed information on how to use these new functions. The next part of the tutorial introduces new features of TQS 2.6.

Part XV: Embedding Files in TQS Applications