QML 1.0 tutorial
Summary: Tutorial for QML 1.0
This tutorial will show you how to create problemsets and write
individual items, and how to embed them into other XML
documents. It is intended primarily for people involved in the
Connexions Project.
Displaying QML
The Connexions project provides the ability to do simple
response processing through stylesheets and
JavaScript. Examples of QML items thus processed are available
in the QML 1.0 examples module.
PLEASE NOTE: This response processing is intended for the
student to do self-testing as he or she moves through modules.
Any student with minor technological know-how can determine
the answers to the questions by viewing the source file.
Hence, if you do not want students to have easy access to the
answers to the questions, do not include them in the QML -
leave the key blank and do not put information in the feedback
tags that will allow the student to determine the correct
answer.
Please also note that while the current Connexions response
processing can determine whether answers to single-response,
multiple-response, and single-response questions are correct, it
does not process the responses to text-response questions (this
requires high-level and very situation-specific software that we
do not have plans to provide at this time). Instead, it only
shows the general feedback.
Starting out: QML, CNXML, and MathML
The first line in a file containing QML is the XML declaration
and the second two lines are the document type
declaration. These three lines are what allow your document to
be understood as QML. However, they may differ depending on
whether you are writing QML in a file containing only QML, or
in a file containing another XML language as well. This
tutorial gives instructions for using QML alone, with CNXML,
and with CNXML and MathML. If you are using QML with other
languages, the method is similar but the exact text you use
will vary somewhat.
QML alone
If you are using QML by itself, the first three lines of
your document should read as follows:
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> <!DOCTYPE item PUBLIC "-//CNX//DTD QML 1.0//EN" "http://cnx.rice.edu/qml/1.0/DTD/qml.dtd">
If your base tag is problemset, rather than item, you will
need to change "item" in the second line to "problemset".
If you are using QML alone, you do not need to add a
namespace to your document or prefix your tags as you would
if you were using multiple XML languages.
QML with CNXML
If you are using both QML and CNXML, the first three lines
of your document should read as follows:
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> <!DOCTYPE document PUBLIC "-//CNX//DTD CNXML 0.5 plus QML//EN" "http://cnx.rice.edu/cnxml/0.5/DTD/cnxml_qml.dtd">
You should also add the following attributes to your module
tag:
xmlns="http://cnx.rice.edu/cnxml" xmlns:q="http://cnx.rice.edu/qml/1.0"
You can now add QML to your CNXML document. You may only
add items, not problemsets. Each item goes within a CNXML
exercise tag, and you may have only one item within each
CNXML exercise tag. You must also prefix each QML tag with
"q:" as follows:
<exercise id="prob1">
<q:item id='item01'>...</q:item>
</exercise>
QML with CNXML and MathML
If you are using QML, CNXML, and MathML, the first three
lines of your document should read as follows:
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> <!DOCTYPE document PUBLIC "-//CNX//DTD CNXML 0.5 plus MathML plus QML//EN" "http://cnx.rice.edu/cnxml/0.5/DTD/cnxml_mathml_qml.dtd">
You should also add the following attributes to your module
tag:
xmlns="http://cnx.rice.edu/cnxml" xmlns:q="http://cnx.rice.edu/qml/1.0" xmlns:m="http://www.w3.org/1998/Math/MathML"
You can now add QML to your CNXML/MathML document. You may
only add items, not problemsets. Each item goes within a
CNXML exercise tag, and you may have only one item within
each CNXML exercise tag. You must prefix each MathML tag
with an "m:", and you must also prefix each QML tag with
"q:" as follows:
<exercise id="prob2">
<q:item id='item02'>...</q:item>
</exercise>
Structural overview
In QML, items (test and homework questions) are either grouped
together in a problemset or are written individually. Each
item contains the question being asked of the user, the
response options together with answer-specific feedback, if
any, general feedback, if any, and a key. The items can also
contain hints and links to resources.
Problemsets and items
The first thing you need to do is decide whether your items
should be grouped together in a problemset or not. If you are
writing QML with CNXML, you can only use items, and each item
will go within a CNXML exercise tag. If you have a reason to
logically group your items together (e.g.
they comprise a homework set) and you are not writing for CNXML,
enclose them in a problemset. To write a problemset, all you
need to do is enclose your individual items within a problemset
tag. If you are writing individual items and do not have a good
reason to group them together within problemsets, or you are
using CNXML, write items without enclosing them within a
problemset tag.
Problemset
The problemset tag encloses one or more items, and has one
optional attribute called id. If you will be making a number of
problemsets and need to be able to reference them individually,
you will want to add a unique id attribute to each of your
problemsets to distinguish between them.
Example
<problemset id="homework1">
<item . . .>
</item>
</problemset>
Item
The next tag is the item tag, which contains the question,
response options, and so forth. Each item tag must contain an
id attribute and a type attribute. Ideally, the id attribute
should be unique; no two items you write should have the same
attribute. How you do this is up to you.
The type attribute determines the type of question you are
asking. It must be one of the following:
- single-response
- multiple-response
- ordered-response
- text-response
Finally, it is important to note that an item must contain one
question tag. It may also contain zero or more answer tags, and
zero or one key tags. However, the existence or non-existence,
as well as the contents of these last two tags, may be slightly
different depending on the type of question. Items may also
contain one or more resource tags and hint tags, and one general
feedback tag.
Single-response
Single-response items are items for which there is one and
only one correct answer to be selected from the provided
answers. Examples are multiple-choice (select only one) and
Likert scale items.
Multiple-response
Multiple-response items are items which require more than one
selected response option for a correct answer. Examples are
multiple-choice items where the user must select two or more
responses to each item.
Ordered-response
Ordered-response items are multiple-response items for which
the order of the selected response is important. An example
is an item that asks the user to select the instructions for
performing a procedure in their proper order.
Text-response
Text-response items are items which require a textual or
numeric response. Examples are short-answer questions and
supply-the-answer math questions.
Example
An example for a single-response question:
<item id="item1" type="single-response">
<question>
Are bananas a fruit or a vegetable?
</question>
<resource uri="http://bananas.com/bananas.csv" />
<answer id="fruit">
.
.
</answer>
<answer id="vegetable">
.
.
</answer>
<hint>Bananas grow on trees.</hint>
<feedback>Bananas are a fruit.</feedback>
<key answer="fruit" />
</item>
Question
The question tag contains the question you are asking of the
user. It can be written in plain text, or using markup from
another language (such as HTML, which allows you to include
pictures and graphs as well as text). Be aware that the
stylesheets for the Connexions project currently only allow
plain text and CNXML (with and without MathML) within question
tags. If you use CNXML (with or without MathML) within a QML
tag, the first tag must be a section tag, which may contain any
of the tags a CNXML section tag is allowed to contain.
Example
<question>
Are bananas a fruit or a vegetable?
</question>
Resource
The resource tag allows you to provide a URI attribute (file
location, web address, etc.) for a particular
item. For example, if you had the necessary software, you could
use the resource tag to attach a reference to a dataset and
generate question and answer values from that dataset. At the
present time, Connexions has no software to do this, and the
resource tag is ignored by our stylesheets.
It also has an optional id attribute. If you are using more
than one resource for a particular item and need to keep track
of which resource is which, you will want to include an id tag.
The resource tag is an empty tag, which means you must include a
slash at the end of the tag.
Example
<resource uri="http://cnx.rice.edu/datasets/dataset1.csv" id="resource1" />
Answer, Response, and Feedback
How you construct the answer tag, including whether you include
an answer tag at all, depends on your item-type. However, in all
cases where you have an answer tag, the ID of the answer tag
must not contain any commas, as the key tag refers to the answer
IDs separated by commas.
Single-response, multiple-response, and ordered-response
To write answer tags for single-response, multiple-response,
and ordered-response items:
You will want one answer tag for each response option. Each
answer tag has an id, which is referenced by the key tag,
below. Preferably, the id tags should have an obvious
relation to the response option. For example, if your
response options are "London, England;" "Washington, DC;" and
"Paris, France" your id attributes could be london,
washington, and paris.
Each of your answer tags should contain a response tag and may
contain a feedback tag if you wish to provide feedback
specific to that response (general feedback goes in another
tag). The response tag contains the response option, in text
or markup, and has no attributes. Be aware that the
stylesheets for the Connexions project currently only allow
plain text and CNXML (with or without MathML) within response
tags. If you use CNXML (with or without MathML) within a QML
tag, the first tag must be a section tag, which may contain
any of the tags a CNXML section tag is allowed to contain.
The feedback tag contains feedback to be displayed to the user
upon selection of that response option. The feedback may be
text or markup. The feedback tag does not have attributes for
single-response, multiple-response, or ordered-response items.
Example for a single-response question
<item id="item1" type="single-response">
<question>
Are bananas a fruit or a vegetable?
</question>
<resource uri="http://bananas.com/banana_dataset1.csv" />
<answer id="fruit">
<response>A fruit.</response>
<feedback>Correct!</feedback>
</answer>
<answer id="vegetable">
<response>A vegetable.</response>
<feedback>Incorrect.</feedback>
</answer>
<hint>Bananas grow on trees.</hint>
<feedback>Bananas are a fruit.</feedback>
<key answer="fruit" />
</item>
Text-response items
To write answer tags for text-response items: Because
text-response items do not have response options, you will
have either have no answer tag (if you are not providing
response feedback) or only one answer tag which may contain
two response-specific feedback tags: one for a correct
response, one for an incorrect response.
The feedback tag containing the correct feedback should have
the attribute correct="yes", and the other should have the
attribute correct="no". You may also include a general
feedback tag; this is recommended as Connexions does not have
plans to provide response processing for text-response items
and at the present time only shows the general feedback for
the user to compare his/her answer with. The content of the
feedback tags may be text or markup; be aware that the
stylesheets for the Connexions project currently only allow
plain text and CNXML (with or without MathML) within question
tags. If you use CNXML (with or without MathML) within a QML
tag, the first tag must be a section tag, which may contain
any of the tags a CNXML section tag is allowed to contain.
Example for a text-response item
<item id="item1" type="text-response">
<question>
Are bananas a fruit or a vegetable?
</question>
<resource uri="http://bananas.com/bananas2.csv" />
<answer id="fruit">
<feedback correct="yes">Correct!</feedback>
<feedback correct="no">Incorrect.</feedback>
</answer>
<hint>Bananas grow on trees.</hint>
<feedback>Bananas are a fruit.</feedback>
<key answer="fruit" />
</item>
Hint
The hint tags each contain a hint to be displayed to the user
upon request. The content of the hint tags is text or markup.
Be aware that the stylesheets for the Connexions project
currently only allow plain text and CNXML (with or without
MathML) within response tags. If you use CNXML (with or without
MathML) within a QML tag, the first tag must be a section tag,
which may contain any of the tags a CNXML section tag is allowed
to contain. The hint tag has no attributes; it is assumed that
if there are multiple hints, they will be displayed to the user
in order.
Examples
<hint>Bananas grow on trees.</hint>
Key
The key tag contains the answer key, for items for which the
answer key is included.
The key tag varies slightly depending on the type of item. For
single-response items, the key tag contains an "answer"
attribute which refers to the id tag of the correct answer.
Example
<key answer="fruit" />
For multiple-response items, the answer id should refer to all
the necessary response ids for a correct answer, separated by
commas.
Example
<key answer="fruit,yellow" />
For ordered-response items, the response ids should be in
correct order and separated by commas.
Example
<key answer="uno,dos,tres,cuatro,cinco" />
For text-response items, the key tag should have no attributes,
and should contain text which will be helpful to the program or
person scoring the user's answers.
Examples
<key>One example of a correct answer is "No hay nadie
aqui."</key>
<key>3.14159</key>
Complete examples
Stripped-down single-response item
Here is an example of a single-response item with only a
question, two answers, and a key.
<item id="item1" type="single-response">
<question>
Are bananas a fruit or a vegetable?
</question>
<answer id="fruit">
<response>A fruit.</response>
</answer>
<answer id="vegetable">
<response>A vegetable.</response>
</answer>
<key answer="fruit" />
</item>
Full single-response item
Here is an example of a single-response item with all options
- resource, hints, and feedback.
<item id="item1" type="single-response">
<question>
Are bananas a fruit or a vegetable?
</question>
<resource uri="http://bananas.com/yellowbananas.csv" />
<answer id="fruit">
<response>A fruit.</response>
<feedback>Correct!</feedback>
</answer>
<answer id="vegetable">
<response>A vegetable.</response>
<feedback>Incorrect.</feedback>
</answer>
<hint>Bananas grow on trees.</hint>
<feedback>Bananas are a fruit.</feedback>
<key answer="fruit" />
</item>
Stripped-down multiple-response item
Here is an example of a multiple-response item with only a
question, three answers, and a key.
<item id="item1" type="multiple-response">
<question>
Bananas are (pick two):
</question>
<answer id="fruit">
<response>A fruit.</response>
</answer>
<answer id="vegetable">
<response>A vegetable.</response>
</answer>
<answer id="yellow">
<response>Yellow.</response>
</answer>
<key answer="fruit,yellow" />
</item>
Full multiple-response item
Here is an example of the same multiple-response item with all
options - resource, hints, and feedback.
<item id="item1" type="multiple-response">
<question>
Bananas are (pick two):
</question>
<resource uri="http://bananas.com/bananas.csv" />
<answer id="fruit">
<response>A fruit.</response>
<feedback>Yes, bananas are a fruit.</feedback>
</answer>
<answer id="vegetable">
<response>A vegetable.</response>
<feedback>Bananas are not a vegetable.</feedback>
</answer>
<answer id="yellow">
<response>Yellow.</response>
<feedback>Yes, bananas are yellow.</feedback>
</answer>
<hint>Bananas grow on trees.</hint>
<hint>Bananas are the same color as lemons.</hint>
<feedback>Bananas are a yellow fruit.</feedback>
<key answer="fruit,yellow" />
</item>
Stripped-down ordered-response item
Here is an example of an ordered-response item with only a
question, three answers, and a key.
<item id="item1" type="ordered-response">
<question>
In order to boil water, you need to do the following
(please select in the correct order):
</question>
<answer id="stove">
<response>Put the pot on the stove.</response>
</answer>
<answer id="pot">
<response>Put water in the pot.</response>
</answer>
<answer id="boil">
<response>Wait until you see bubbles in the water.</response>
</answer>
<key answer="pot,stove,boil" />
</item>
Full ordered-response item
Here is an example of the same ordered-response item with all
options - resource, hints, and feedback.
<item id="item1" type="ordered-response">
<question>
In order to boil water, you need to do the following
(please select in the correct order):
</question>
<resource uri="www.howtoboilwater.com/instructions.csv" />
<answer id="stove">
<response>Put the pot on the stove.</response>
<feedback>You put the pot on the stove second.</feedback>
</answer>
<answer id="pot">
<response>Put water in the pot.</response>
<feedback>You put the water in the pot first.</feedback>
</answer>
<answer id="boil">
<response>Wait until you see bubbles in the water.</response>
<feedback>You wait for the bubbles third.</feedback>
</answer>
<hint>The pot won't boil till there's water in it.</hint>
<feedback>First you put water in the pot, then you put the
pot on the stove, then you wait for the bubbles.</feedback>
<key answer="pot,stove,boil" />
</item>
Stripped-down text-response item
Here is an example of an ordered-response item with only a
question, general feedback, and a key.
<item id="item1" type="text-response">
<question>
What are some common tests of executive function?
</question>
<feedback>Some common tests of executive function are the
Wisconsin Card Sort Test and the Tower of Hanoi.</feedback>
<key>Wisconsin Card Sort Test, Tower of Hanoi</key>
</item>
Full text-response item
Here is an example of an ordered-response item with a
resource, hints, and an answer with correct and incorrect
feedback.
<item id="item1" type="text-response">
<question>
What are some common tests of executive function?
</question>
<resource uri="www.execfunc.com/tests.csv" />
<answer>
<feedback correct="no">Incorrect.</feedback>
<feedback correct="yes">Correct.</feedback>
</answer>
<hint>Think about square states and towers.</hint>
<feedback>Some common tests of executive function are the
Wisconsin Card Sort Test and the Tower of Hanoi.</feedback>
<key>Wisconsin Card Sort Test, Tower of Hanoi</key>
</item>
More about this content: Metadata | Version History | Cite This Content
This work is licensed by Elizabeth Bartmess. See the Creative Commons License about permission to reuse this material.
Last edited by Charlet Reedstrom on May 31, 2005 8:59 pm GMT-5.