Part XI: HTML Locations and the Data Root

Parts I through X of the tutorial have covered features available since TQS 2.0. This section will cover the main new features of TQS 2.1: HTML locations and the data root dynamic value.

While advanced customization is useful for defining rich, interactive HTML and script-based locations, sometimes all that you want to do is simply display HTML content for the user to read. TQS 2.1 introduces the HTML location type.

Like Questions and Hangman, an HTML location type is created by setting the LOC element's TYPE attribute to "HTML" and including an HTML subelement. Add the following location definition to a TQS file and run it to see how it is displayed:

<LOC ID="1" TYPE="HTML">
  <HEADING>My HTML Location</HEADING>
  <HTML>
<div style="color:black;background-color:#f0f0f0">
This is my HTML location. Inside this
location is a bunch of HTML-formatted text.
<hr/>
You can use <b>HTML</b> formatting and
other HTML features, much like a custom location
type but without the complexity.
<p align="center"/>
Just copy and paste your web page code
into the <b>HTML</b> element of your
TQS file, make it XML compliant, and execute it!
</div>
  </HTML>
</LOC>

This code would produce the following HTML:

This is my HTML location. Inside this location is a bunch of HTML-formatted text.

You can use HTML formatting and other HTML features, much like a custom location type but without the complexity.

Just copy and paste your web page code into the HTML element of your TQS file, make it XML compliant, and execute it!

One requirement of using HTML locations is that everything between the opening and closing HTML tags must be XML compliant. This means that all elements must have a matching closing tag; notice how the hr and p elements are specified as <hr/> and <p .../>, respectively. Although a web browser would not require a closing tag for these elements, it is required here for XML compliance.

Additionally, XML compliance requires that all attributes be enclosed in quotes. For instance, in the p element above is the align="center" attribute. A browser would interpret align=center correctly; quotations are required in TQS for XML compliance.

Put an image file in the same folder as the TQS application, and add an img element inside of the HTML code, as follows, changing img.gif to the name of the image file:

<HTML>
<div style="color:black;background-color:#f0f0f0">
...
  <img src="img.gif"/>
</div>
</HTML>

Notice how the image is not displayed. Even though the image is within the same folder as your TQS application, TQS does not go through your code and try to figure out where you are actually trying to refer to an outside file. However, there is an easy-to-use mechanism to refer to outside files: the data root.

TQS 2.1 introduces the DATAROOT dynamic value. The contents of this value is, by default, the path of the folder containing your TQS file. If your file is C:\TQS Applications\test.tqs, the data root is equal to C:\TQS Applications\.

In order to use this in your HTML code, you add the SUBST attribute to the HTML element. The contents of this attribute must be "string,DATAROOT", where all occurrences of string inside the HTML element are replaced with the data root. (TQS 2.5 supports additional substitutions using this attribute; see the HTML element reference for more information.)

Change the code to read as follows:

<HTML SUBST="%data%,DATAROOT">
<div style="color:black;background-color:#f0f0f0">
...
  <img src="%data%img.gif"/>
</div>
</HTML>

The image appears. Be sure to pick a substitution string that you do not use in other places in your HTML code; using percent characters (%) in the string is advised to avoid unwanted substitutions.

The SUBST attribute can be specified within global settings (that is, within an HTML element within the GLOBAL element) to specify a substitution string to be used in all HTML location types.

Use of the data root is automatic when specifying graphics for use in headings, questions, or background images, as well as with the background sound. TQS 2.1 adds a means through which you can manually set the data root; this can be useful for loading all data files from a web site folder.

The TQS element supports the DATAROOT attribute, whose contents specify a folder which is to be used as the data root. All data files must exist in this folder.

<TQS VERSION="2.1"
  DATAROOT="http://www.example.com/tqsdata/">
  ...
</TQS>

Note that this attribute must end with a slash ("/" for Internet folders, "\" for hard drive folders). Image and sound file names will be appended to this string.

In addition to allowing you to set the data root, TQS also allows you to override the data root and specify an absolute path to the image or sound file. Because you are unlikely to know the structure of a user's hard drive, it is useful mainly for loading specific data files from the Internet. If you do not set the DATAROOT attribute, because you distribute your image files with your TQS application, but would like to load a few files from the Internet, you use the following means to specify an absolute path:

<QUESTION>
  ...
  <LIMG
    SRC="NOROOT?http://www.example.com/img.gif"/>
</QUESTION>

Preceding the file path with NOROOT? will cause the following path to be used exactly as it is specified, ignoring the data root. This applies to all cases where data files are used, except HTML and custom locations.

TQS 2.1 introduces several additional Hangman features which will not be covered in this tutorial; see the HANGMAN element reference for more information.

This part of the tutorial has discussed the important new features of TQS 2.1, the HTML location type and the data root value. More information on new TQS 2.1 features can be found in the Reference. The remaining parts of the tutorial cover features introduced in TQS 2.5 and 2.6.

Part XII: Question Types, Sounds, and Finish Buttons