Note: You are currently viewing documentation for Moodle 3.6. Up-to-date documentation for the latest stable version of Moodle is likely available here: Moodle XML format.

Moodle XML format: Difference between revisions

From MoodleDocs
(fixed grammar error)
(48 intermediate revisions by 15 users not shown)
Line 1: Line 1:
==A word about validity==
{{Export questions}}
The XML Format is a Moodle-specific format for importing and exporting questions to be used with the [[Quiz module]]. The format has been developed within the Moodle Community but other software may support it to a greater or lesser degree.


The XML parser assumes that the XML file is well formed and does not detect or report errors. If it is not you are very likely to get unexpected errors. If you are hand-coding the XML file it is strongly recommended that you pass it through some sort of XML verifier before importing into Moodle. A simple way to do this is to open the XML file using Firefox. Note particularly that embedded HTML fragments should be within CDATA sections.
==A word about validity (and CDATA)==
 
The XML parser assumes that the XML file is well formed and does not detect or report errors. If it is not you are very likely to get unexpected errors. If you are hand-coding the XML file it is strongly recommended that you pass it through some sort of XML verifier before importing into Moodle. A simple way to do this is to open the XML file using Firefox or Internet Explorer.  
 
Note particularly that embedded HTML fragments should be within [http://en.wikipedia.org/wiki/CDATA CDATA sections]. CDATA example:
 
<code xml>
<questiontext format="html">
      <text><![CDATA[
              Now I can include <strong>any</strong> HTML that I<br />
              wish. Without the CDATA, the <i>HTML</i> tags would break
              the XML!!
              ]]>
        </text>
</questiontext>
</code>


==Overall structure of XML file==
==Overall structure of XML file==


The file is enclosed by tags as follows.
The file is enclosed by tags as follows. It is '''important''' to make sure the xml tag only is really the first line of the file. A blank first line, or additional tags on the first line will confuse the Moodle XML parser.


<?xml version=1.0?>
<code xml>
<quiz>
<?xml version="1.0" ?>
<quiz>
  .
  .
  .
  .
  .
  .
</quiz>
</quiz>
</code>


Within the <quiz> tags are any number of <question> tags. One of these <question> tags can be a dummy question with a ''category'' type to specify a category for the import/export.  
Within the <quiz> tags are any number of <question> tags. One of these <question> tags can be a dummy question with a ''category'' type to specify a category for the import/export.  


<question type="category">
<code xml>
<question type="category">
     <category>
     <category>
         <text>$course$/XXXX</text>
         <text>$course$/XXXX</text>
     </category>
     </category>
</question>
</question>
</code>
 
Where XXXX is the new category name. If the category exists, the question(s) will be added to the existing course; otherwise a new category will be created. This only works if you have "Get category from file" checked.


Where XXXX is the new category name. If the category exists, the question(s) will be added to the existing category; otherwise a new category will be created.
Multiple categories can be specified in the same file. Just add another dummy 'category' question each time you would like to establish a new category and the questions that follow it will be placed there.


The file must be encoded in [[UTF8]]
The file must be encoded in [[UTF8]]
Line 32: Line 54:
A question is written as follows.
A question is written as follows.


<question type="multichoice|truefalse|shortanswer|match|cloze|essay|numerical|description">
<code xml>
<question type="multichoice|truefalse|shortanswer|matching|cloze|essay|numerical|description">
    <name>
        <text>Name of question</text>
    </name>
     <questiontext format="html">
     <questiontext format="html">
         <text>What is the answer to this question?</text>
         <text>What is the answer to this question?</text>
Line 39: Line 65:
     .
     .
     .
     .
</question>
</question>
</code>


"Format" selects the [[Formatting options]] for the question text. The options are '''moodle_auto_format''' (the default), '''html''', '''plain_text''' and '''markdown'''. The choice effects the way in which the text will be displayed.  
Each question requires a <name> tag and <question-text> tag for the XML file to import into Moodle properly.
 
"Format" selects the [[Formatting options]] for the question text. The options are '''html''' (the default), '''moodle_auto_format''', '''plain_text''' and '''markdown'''. The choice effects the way in which the text will be displayed.  


Further tags, which usually include at least one <answer> tag, follow in the space marked with dots as child nodes to the <question> tag. The response-related tags are listed further down on this page. Various (optional?) tags are possible.  
Further tags, which usually include at least one <answer> tag, follow in the space marked with dots as child nodes to the <question> tag. The response-related tags are listed further down on this page. Various (optional?) tags are possible.  


* tags (non-hierarchical keywords)
* penalty
* penalty
* generalfeedback
* generalfeedback
* defaultgrade
* defaultgrade
* hidden
* hidden
Even though question tags (non-hierarchical keyowords) are not fully supported in the question engine, they can be imported and exported via XML.
<code xml>
<question ...>
  ...
  <tags>
    <tag>
      <text>keyword1</text>
    </tag>
    <tag>
      <text>keyword2</text>
    </tag>
    ...
  </tags>
  ...
</question>
</code>


The <image> tag contains the url of any included image. Nested within the <image> tag may be an <image_base64> tag which contains the actual image data encoded in base64 [http://www.php.net/manual/en/function.base64-encode.php].
The <image> tag contains the url of any included image. Nested within the <image> tag may be an <image_base64> tag which contains the actual image data encoded in base64 [http://www.php.net/manual/en/function.base64-encode.php].


{{Note|If you export questions from a Moodle 1.9 server, the exported file might contain only the relative URL to the image hosted in the 1.9 server, while exported questions from Moodle 2.x and 3.x severs might contain the actual image encoded in base 64. This explains why some question bank import-export operations include all the images and some others don't.}}
'''In the following question type examples the common parts of the question are not shown to improve clarity. It's a good idea to export some examples yourself to see a full example.'''
'''In the following question type examples the common parts of the question are not shown to improve clarity. It's a good idea to export some examples yourself to see a full example.'''


Line 63: Line 112:
* partiallycorrectfeedback  
* partiallycorrectfeedback  
* incorrectfeedback
* incorrectfeedback
* answernumbering (allowed values: 'abc', 'ABC' or '123')
* answernumbering (allowed values: 'none', 'abc', 'ABCD' or '123')


The <single> tag is used to distinguish single response (radio button) and multiple response (checkbox) variants.
The <single> tag is used to distinguish single response (radio button) and multiple response (checkbox) variants.


<question type="multichoice">
<code xml>
<question type="multichoice">
  <answer fraction="100">
  <answer fraction="100">
     <text>The correct answer</text>
     <text>The correct answer</text>
Line 83: Line 133:
  <single>true</single>
  <single>true</single>
  <answernumbering>abc</answernumbering>
  <answernumbering>abc</answernumbering>
</question>
</code>


== True/false ==
== True/false ==
Line 88: Line 140:
Two answer tags are given, one which is true, and one which is false. The fraction attribute of the answer tag identifies which option is correct (100) and which is false (0). Feedback is supported. The following example shows the format when true is the correct answer and false is wrong.
Two answer tags are given, one which is true, and one which is false. The fraction attribute of the answer tag identifies which option is correct (100) and which is false (0). Feedback is supported. The following example shows the format when true is the correct answer and false is wrong.


<code xml>
  <question type="truefalse">
  <question type="truefalse">
  <answer fraction="100">
  <answer fraction="100">
Line 97: Line 150:
     <feedback><text>Ooops!</text></feedback>
     <feedback><text>Ooops!</text></feedback>
  </answer>
  </answer>
</question>
</code>


== Short answer  ==
== Short answer  ==
Line 104: Line 159:
The <usecase> tag toggles case-sensitivity with the values 1/0.  
The <usecase> tag toggles case-sensitivity with the values 1/0.  


<code xml>
  <question type="shortanswer">
  <question type="shortanswer">
  <answer fraction="100">
  <answer fraction="100">
Line 119: Line 175:
     <feedback><text>Correct!</text></feedback>
     <feedback><text>Correct!</text></feedback>
  </answer>
  </answer>
</question>
</code>


== Numerical response ==
== Numerical response ==
Line 124: Line 182:
The following is a simplified version of the Moodle XML format for numerical responses.
The following is a simplified version of the Moodle XML format for numerical responses.


<code xml>
  <question type="numerical">
  <question type="numerical">
  <answer fraction="100">
  <answer fraction="100">
Line 129: Line 188:
     <feedback><text>Feedback</text></feedback>
     <feedback><text>Feedback</text></feedback>
  </answer>
  </answer>
</question>
</code>


Moodle also supports a <tolerance> tag (how accurate must the number be?) and one or more <unit> tags. Unit tags have names and multipliers. E.g. if the main answer is in kilometres, an additional answer could be the equivalent in metres with a multiplier of 1000.
Moodle also supports a <tolerance> tag (how accurate must the number be?) and one or more <unit> tags. Unit tags have names and multipliers. E.g. if the main answer is in kilometres, an additional answer could be the equivalent in metres with a multiplier of 1000.
Line 139: Line 200:
Each pair is contained inside a <subquestion> tag. The first item of each pair is contained with a <text> tag, while the second has an <answer> tag around it as well. Feedback and score weighting is not supported by Moodle for this response type.
Each pair is contained inside a <subquestion> tag. The first item of each pair is contained with a <text> tag, while the second has an <answer> tag around it as well. Feedback and score weighting is not supported by Moodle for this response type.


  <question type="match">
<code xml>
  <question type="matching">
  <subquestion>
  <subquestion>
     <text>This is the 1st item in the 1st pair.</text>
     <text>This is the 1st item in the 1st pair.</text>
Line 153: Line 215:
  </subquestion>
  </subquestion>
  <shuffleanswers>true</shuffleanswers>
  <shuffleanswers>true</shuffleanswers>
</question>
</code>


== Essay ==
== Essay ==
Line 158: Line 222:
An example of the essay type question...
An example of the essay type question...


<code xml>
   <question type="essay">
   <question type="essay">
     <answer fraction="0">
     <answer fraction="0">
Line 163: Line 228:
     </answer>
     </answer>
   </question>
   </question>
</code>


There isn't an answer and there isn't a grade in this case.  
There isn't an answer and there isn't a grade in this case.  
Line 182: Line 248:
Moodle has a question type which consists of taking short answer questions in the same quiz and displaying them as a pair matching exercise. However Moodle is neither able to export nor import this question type.
Moodle has a question type which consists of taking short answer questions in the same quiz and displaying them as a pair matching exercise. However Moodle is neither able to export nor import this question type.


==Hints and Tips==
==Text formats==
Here's a Word Template for generating Moodle XML [http://finemetronome.com/moodle/].


==See also==
Moodle XML files should explicity specify the text format ('''html''', '''moodle_auto_format''', '''plain_text''' and '''markdown''' - these correspond to the constants , FORMAT_HTML, FORMAT_MOODLE, etc used in the Moodle code) for each piece of content. Note that, by default, the format should be specified on the parent of the <text> element. This is slightly odd, but a remnant of history.


*[[Export questions]]
If the format is not specified for the questiontext, then '''html''' is the default. If the format is not specified on any other part of the question, then the format of the questiontext is the default.
*[[Import questions]]
 
*[[GIFT format]]
(This default changed around November 2011. Before that, the default was '''moodle_auto_format''' whenever the format was not specified.)
 
==Useful utilities==
*[http://vletools.com Online Moodle XML converter] Convert from existing text files glossaries and quizzes to Moodle XML format. Also can convert from Moodle XMl to text.
*[http://finemetronome.com/moodle/ Word Template for generating Moodle XML].
*[http://www.learningseekers.com/products MoXMLE - A Java based application] MoXMLE is a Java based application that converts a Simple TXT file into a Moodle XML format.
 
== See also ==
* [http://www.qedoc.org/index.php?title=Moodle_XML_format Quedoc's Moodle XML documentation]
* [[User:Frank Ralf/Moodle XML1]] (work in progress)
*[[Aiken format]]
*[[Aiken format]]
*[[XML FAQ]]
*[[XML FAQ]]
*[[Import and export FAQ]]  
*[[Import and export FAQ]]  
[[Category:Questions]]


[[ja:Moodle XMLフォーマット]]
[[ja:Moodle XMLフォーマット]]
[[de: Moodle XML-Format]]
[[de: Moodle XML-Format]]
[[fr:Format XML Moodle]]
[[es:Formato Moodle XML]]

Revision as of 23:46, 28 February 2017

The XML Format is a Moodle-specific format for importing and exporting questions to be used with the Quiz module. The format has been developed within the Moodle Community but other software may support it to a greater or lesser degree.

A word about validity (and CDATA)

The XML parser assumes that the XML file is well formed and does not detect or report errors. If it is not you are very likely to get unexpected errors. If you are hand-coding the XML file it is strongly recommended that you pass it through some sort of XML verifier before importing into Moodle. A simple way to do this is to open the XML file using Firefox or Internet Explorer.

Note particularly that embedded HTML fragments should be within CDATA sections. CDATA example:

<questiontext format="html">
      <text><![CDATA[
             Now I can include any HTML that I
wish. Without the CDATA, the HTML tags would break the XML!! ]]> </text> </questiontext>

Overall structure of XML file

The file is enclosed by tags as follows. It is important to make sure the xml tag only is really the first line of the file. A blank first line, or additional tags on the first line will confuse the Moodle XML parser.

<?xml version="1.0" ?> <quiz>

.
.
.

</quiz>

Within the <quiz> tags are any number of <question> tags. One of these <question> tags can be a dummy question with a category type to specify a category for the import/export.

<question type="category">

   <category>
       <text>$course$/XXXX</text>
   </category>

</question>

Where XXXX is the new category name. If the category exists, the question(s) will be added to the existing course; otherwise a new category will be created. This only works if you have "Get category from file" checked.

Multiple categories can be specified in the same file. Just add another dummy 'category' question each time you would like to establish a new category and the questions that follow it will be placed there.

The file must be encoded in UTF8

Moodle XML import and export are balanced in functionality, so if you need to understand the format you can simply create some questions and export them to see what it looks like.

Tags common to all question types

A question is written as follows.

<question type="multichoice|truefalse|shortanswer|matching|cloze|essay|numerical|description">

    <name>
        <text>Name of question</text>
    </name>
    <questiontext format="html">
        <text>What is the answer to this question?</text>
    </questiontext>
    .
    .
    .

</question>

Each question requires a <name> tag and <question-text> tag for the XML file to import into Moodle properly.

"Format" selects the Formatting options for the question text. The options are html (the default), moodle_auto_format, plain_text and markdown. The choice effects the way in which the text will be displayed.

Further tags, which usually include at least one <answer> tag, follow in the space marked with dots as child nodes to the <question> tag. The response-related tags are listed further down on this page. Various (optional?) tags are possible.

  • tags (non-hierarchical keywords)
  • penalty
  • generalfeedback
  • defaultgrade
  • hidden

Even though question tags (non-hierarchical keyowords) are not fully supported in the question engine, they can be imported and exported via XML.

<question ...>

 ...
 <tags>
   <tag>
     <text>keyword1</text>
   </tag>
   <tag>
     <text>keyword2</text>
   </tag>
   ...
 </tags>
 ...

</question>

The <image> tag contains the url of any included image. Nested within the <image> tag may be an <image_base64> tag which contains the actual image data encoded in base64 [1].

Note: If you export questions from a Moodle 1.9 server, the exported file might contain only the relative URL to the image hosted in the 1.9 server, while exported questions from Moodle 2.x and 3.x severs might contain the actual image encoded in base 64. This explains why some question bank import-export operations include all the images and some others don't.


In the following question type examples the common parts of the question are not shown to improve clarity. It's a good idea to export some examples yourself to see a full example.

Multiple choice

MC questions have one <answer> tag for each choice. Each choice can carry feedback and score weighting (by using the fraction attribute). In addition, an MC question has the following tags:

  • single (values: true/false)
  • shuffleanswers (values: 1/0)
  • correctfeedback
  • partiallycorrectfeedback
  • incorrectfeedback
  • answernumbering (allowed values: 'none', 'abc', 'ABCD' or '123')

The <single> tag is used to distinguish single response (radio button) and multiple response (checkbox) variants.

<question type="multichoice">

<answer fraction="100">
    <text>The correct answer</text>
   <feedback><text>Correct!</text></feedback>
</answer>
<answer fraction="0">
    <text>A distractor</text>
   <feedback><text>Ooops!</text></feedback>
</answer>
<answer fraction="0">
    <text>Another distractor</text>
   <feedback><text>Ooops!</text></feedback>
</answer>
<shuffleanswers>1</shuffleanswers>
<single>true</single>
<answernumbering>abc</answernumbering>

</question>

True/false

Two answer tags are given, one which is true, and one which is false. The fraction attribute of the answer tag identifies which option is correct (100) and which is false (0). Feedback is supported. The following example shows the format when true is the correct answer and false is wrong.

<question type="truefalse">
<answer fraction="100">
   <text>true</text>
   <feedback><text>Correct!</text></feedback>
</answer>
<answer fraction="0">
   <text>false</text>
   <feedback><text>Ooops!</text></feedback>
</answer>

</question>

Short answer

The short answer question type supports alternative correct responses, each with its own weighting and feedback. The Moodle XML format uses one <answer> tag for each of the alternative correct answers.

The <usecase> tag toggles case-sensitivity with the values 1/0.

<question type="shortanswer">
<answer fraction="100">
    <text>The correct answer</text>
    <feedback><text>Correct!</text></feedback>
</answer>
<question type="shortanswer">
<answer fraction="100">
    <text>The correct answer</text>
    <feedback><text>Correct!</text></feedback>
</answer>
<answer fraction="100">
    <text>An alternative answer</text>
    <feedback><text>Correct!</text></feedback>
</answer>

</question>

Numerical response

The following is a simplified version of the Moodle XML format for numerical responses.

<question type="numerical">
<answer fraction="100">
    <text>23</text>
    <feedback><text>Feedback</text></feedback>
</answer>

</question>

Moodle also supports a <tolerance> tag (how accurate must the number be?) and one or more <unit> tags. Unit tags have names and multipliers. E.g. if the main answer is in kilometres, an additional answer could be the equivalent in metres with a multiplier of 1000.

Note: prior to 1.7.2 the fraction was expressed as a value between 0 and 1 in a <fraction> element and the answer value was not enclosed in <text> tags. This format of the numerical question type is deprecated but will still be correctly imported if found (for now).

Matching

Pair matching responses use the <shuffleanswers> tag to determine whether the order of the items should be randomized. Each pair is contained inside a <subquestion> tag. The first item of each pair is contained with a <text> tag, while the second has an <answer> tag around it as well. Feedback and score weighting is not supported by Moodle for this response type.

<question type="matching">
<subquestion>
    <text>This is the 1st item in the 1st pair.</text>
    <answer>
        <text>This is the 2nd item in the 1st pair.</text>
    </answer>
</subquestion>
<subquestion>
    <text>This is the 1st item in the 2nd pair.</text>
    <answer>
        <text>This is the 2nd item in the 2nd pair.</text>
    </answer>
</subquestion>
<shuffleanswers>true</shuffleanswers>

</question>

Essay

An example of the essay type question...

 <question type="essay">
   <answer fraction="0">
       <text></text>
   </answer>
 </question>

There isn't an answer and there isn't a grade in this case.

Note: prior to 1.7.2 the fraction was expressed as a value between 0 and 1 in a <fraction> element and the answer value was not enclosed in <text> tags. This format of the essay question type is deprecated but will still be correctly imported if found (for now).

Other question types

Cloze

It is supported, and depends on a special format for the <questiontext> tag.

Description response type

This response type has no further tags other than those contained in the question header (such as <questiontext>).

Random matching

Moodle has a question type which consists of taking short answer questions in the same quiz and displaying them as a pair matching exercise. However Moodle is neither able to export nor import this question type.

Text formats

Moodle XML files should explicity specify the text format (html, moodle_auto_format, plain_text and markdown - these correspond to the constants , FORMAT_HTML, FORMAT_MOODLE, etc used in the Moodle code) for each piece of content. Note that, by default, the format should be specified on the parent of the <text> element. This is slightly odd, but a remnant of history.

If the format is not specified for the questiontext, then html is the default. If the format is not specified on any other part of the question, then the format of the questiontext is the default.

(This default changed around November 2011. Before that, the default was moodle_auto_format whenever the format was not specified.)

Useful utilities

See also