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:

]]>

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:

]]>

You should also add the following attributes to your module tag:

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:


	  
          ...
	]]>

QML with CNXML and MathML If you are using QML, CNXML, and MathML, the first three lines of your document should read as follows:

]]>

You should also add the following attributes to your module tag:

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:


	  
          ...
	]]>

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

]]>

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


	
	
        
	  Are bananas a fruit or a vegetable?
        
	
        
	
        
	  .
          .
	

        
	  .
	  .
        

        Bananas grow on trees.

	Bananas are a fruit.

        
	
      ]]>

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


	
	Are bananas a fruit or a vegetable?
      
	]]>

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

]]>

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


	  
	  
          
	    Are bananas a fruit or a vegetable?
          
	
          
	
          
	    A fruit.
  	    Correct!
	  

          
	    A vegetable.
	    Incorrect.
          

          Bananas grow on trees.
	   
          Bananas are a fruit.

          
	
      
	]]>

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


	  
	  
          
	    Are bananas a fruit or a vegetable?
          
	
          
	
          
  	    Correct!
	    Incorrect.
	  

          Bananas grow on trees.

          Bananas are a fruit.

          
	
        
	]]>

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


	Bananas grow on trees.
	]]>

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

]]>

For multiple-response items, the answer id should refer to all the necessary response ids for a correct answer, separated by commas.

Example

]]>

For ordered-response items, the response ids should be in correct order and separated by commas.

Example

]]>

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


	One example of a correct answer is "No hay nadie
      aqui."

      3.14159
	]]>

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.


	  
	  
          
	    Are bananas a fruit or a vegetable?
          
	
          
	    A fruit.
	  

          
	    A vegetable.
          

          
	
        
	]]>

Full single-response item Here is an example of a single-response item with all options - resource, hints, and feedback.


	  
	  
          
	    Are bananas a fruit or a vegetable?
          
	
          
	
          
	    A fruit.
  	    Correct!
	  

          
	    A vegetable.
	    Incorrect.
          

          Bananas grow on trees.
	   
          Bananas are a fruit.

          
	
        
	]]>

Stripped-down multiple-response item Here is an example of a multiple-response item with only a question, three answers, and a key.


	  
	  
          
	    Bananas are (pick two):
          
	
          
	    A fruit.
	  

          
	    A vegetable.
          

          
	    Yellow.
          

          
	
        
	]]>

Full multiple-response item Here is an example of the same multiple-response item with all options - resource, hints, and feedback.


	  
	  
          
	    Bananas are (pick two):
          
	
          
	
          
	    A fruit.
  	    Yes, bananas are a fruit.
	  

          
	    A vegetable.
	    Bananas are not a vegetable.
          

	  
	    Yellow.
            Yes, bananas are yellow.
	  

          Bananas grow on trees.
	  Bananas are the same color as lemons.

          Bananas are a yellow fruit.

          
	
        
	]]>

Stripped-down ordered-response item Here is an example of an ordered-response item with only a question, three answers, and a key.


	  
	  
          
	    In order to boil water, you need to do the following
	    (please select in the correct order):
          
	
          
	    Put the pot on the stove.
	  

          
	    Put water in the pot.
          

          
	    Wait until you see bubbles in the water.
          

          
	
        
	]]>

Full ordered-response item Here is an example of the same ordered-response item with all options - resource, hints, and feedback.


	  
	  
          
	    In order to boil water, you need to do the following
	    (please select in the correct order):
          

	  

          
	    Put the pot on the stove.
	    You put the pot on the stove second.
	  

          
	    Put water in the pot.
	    You put the water in the pot first.
          

          
	    Wait until you see bubbles in the water.
	    You wait for the bubbles third.
          

	  The pot won't boil till there's water in it.

	  First you put water in the pot, then you put the
	  pot on the stove, then you wait for the bubbles.

          
	
        
	]]>

Stripped-down text-response item Here is an example of an ordered-response item with only a question, general feedback, and a key.


	  
	  
          
	    What are some common tests of executive function?
          
	
	  Some common tests of executive function are the
	  Wisconsin Card Sort Test and the Tower of Hanoi.

          Wisconsin Card Sort Test, Tower of Hanoi
	
        
	]]>

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.


	
	
          
	    What are some common tests of executive function?
          

          
		
          
	    Incorrect.
	    Correct.
	  

	  Think about square states and towers.

	  Some common tests of executive function are the
	  Wisconsin Card Sort Test and the Tower of Hanoi.

          Wisconsin Card Sort Test, Tower of Hanoi
	
        
	]]>