User Reference

Structure of a question database

Each spreadsheet document must at least have three sheets:

  1. One sheet named settings which stores project specific settings for this question database:

    • In this sheet in the first column the tags below need to be written and in the second column the specific values for each tag.

    • It must specify categoriesSheet with the name of the sheet, which lists the Categories.

    • It must specify imgFolder which is the directory name for the pictures, relativ to the path of the spreadsheet itself.

    • It may specify any of the tags listet in Supported settings tags Tags are listed in the first, their values in the second column.

  2. One sheet which stores the information about the different categories of questions.

    • The name of this sheet must be as specified by categoriesSheet in the settings.

    • It may/must have at least those columns:

      categorymandatory

      in this column all the different category identifiers are listet. Those identifiers must be coherent to the names of the sheets, which store the questions of for this category.

      descriptionmandatorystring | int

      A short description of the category. This is later shown as the description for the category in moodle and in excel2moodle

      pointsoptionalfloat

      The total points for each question of this category. If omitted, the Fallback points as specified in settings sheet is used.

      versionoptionalint

      The version of the question. If omitted, the default version as specified in settings sheet is used.

  3. At least one category sheet, which stores all the questions in for that category.

    • The name of this sheet(s) must be as specified by category sheet

    • The first column of this sheet list all the tags (refer to: Question Tag Definitions) in each of the folowing columns the values for each of the questions are provided.

Supported settings tags

Below is a list of all supported settings which can be set in the settings sheet. None of them has to be set, if the defaults are to your liking.

pointsfloatdefault=1.0

Fallback value for the points for each question. Can be overridden by a definition in the categories sheet.

versionintdefault=1

Fallback version number of the question. Can be overriden by a definition in the categories sheet.

toleranceintdefault=1

Fallback tolerance if the NF or NFM question doesn’t define it. See also Question Tag Definitions for details of how this value is treated.

imgWidthintdefault=500

Width of the picture in the questions

imgPictureWidthintdefault=120

Width of the pictures set as answers for tho MC questions.

imgFolderstrdefault=Abbildungen

Folder where the images are stored, relative to the folder of the spreadsheet. Inside this Folder for each category a folder needs to be created with the same name as the category sheet.

Question ID convention

Each Question gets an unique 5 digit identifier consisting of three parts.

  1. part is a one digit version number

  2. part is the two digit category number

  3. part is the two digit question number.

Beispiel: 10613 ist die Frage 13 aus der Kategorie 6 in der Version 1

Supported Question Types

MCMultiple Choice

This is the multiple choice question Type. It supports a main text and two list of answers. One with correct and one with incorrect answers. Optionally a picture can be shown below the main text. See Question Tag Definitions for an overview what needs to be specified.

NFNumericEinfach Berechnet

This is a question which expects an numeric answer. It consist of the main text, optionally a bullet Point list, where variables may be presented in a structured way. Optionally a picture can be included. See Question Tag Definitions for an overview what needs to be specified.

NFMNumeric (multiple Variants)Einfach Berechnet (mehrfache Variation):

This is an easy way to serialize numerical Questions based on a set of Variables on which a result is calculated by excel2moodle When imported into moodle it is the same as the NF Question. When creating this question mostly the same rules apply as for the NF type. But instead of specifying the numeric answer, a formula is given, which will evaluated by excel2moodle Inside the formula variables need to be used. For each of these variables another tag is created in the spreadsheet to which a list of numbers need to be passed. For better understanding please have a look at Numerische Fragen.

CLOZELückentext

Added in version 0.4.0: This will be implemented in v0.4.0

Question Tag Definitions

When writing questions several important things must be considered, as the program still is quite buggy and likely to crash, when unexpected input is reached.

Important

The following list shows all tags that need or may be declared in the spreadsheet. It has the following structure

tagclassifierQuestionType

Description of what this tags does

The first classifier shows weather this tag is optional or mandatory. Each tag may have slightly different meanings for each question type.

For example: the bulletPoints tag is mandatory for NFM questions, but for NF questions it is optional.

General tags for all Question Types

numbermandatoryALL

The number of the question

typemandatoryALL

Any of NFM, NF, MC

namemandatoryALL

The internal name of the question, not the title that will be seen when the question is viewed

textmandatoryALL

The question text. At least one of these must be filled out. If it occurs more than once, a new paragraph gets added for each.

pictureoptionalALL

If left empty, no picture will be included All pictures have to be in the folder specified in the settings by the imgFolder Tag (see also: Supported settings tags) If a picture with the same ID as the question should be included, true or yes or the number of the question can be written here. If a picture from another question (in the same category) should be used, write the number of that question: The Width or Height of the question can be set by appending :width:600 to the number.

Examples (for questions inside category 6 with version 1, see also: Question ID convention):

  • 15:width:650 will include the picture imgFolder/KAT_06/10615.jpg and set its width to 650 px.

  • 1_a:height:90 will include the picture imgFolder/KAT_06/10601_a.jpg and set its height to 90 px.

Specific tags for question Types

truemandatoryMC

One true answer. For each true answer this tag can be specified.

falsemandatoryMC

One false answers. For each wrong answer this tag can be specified.

answerTypemandatoryMC

controls the formatting of the answers either text, formula, unit, or picture

bulletPointoptionalNF

One bullet point it consists of four parts

  1. Name: (Example: length)

  2. Variable Name: (Example l )

  3. =-Sign

  4. Value: (Example 5.4)

  5. Si-Unit: (Example m)

A list of bullet points can be created by defining multiple times the tag bulletPoint

bulletPointmandatoryNFM

list of bullet points separated by ;, each bullet Points consist of 4 parts: The only difference to the NF bullet point is the use of variables instead of values.

  1. Name: (Example: length)

  2. Variable Name: (Example l )

  3. =-Sign

  4. Variable: (Example {l}): must be one letter enclosed by curly braces

  5. Si-Unit: (Example m)

A list of bullet points can be created by defining multiple times the tag bulletPoint

resultmandatoryNF

the value of the result. Decimal separator must be a . dot.

resultmandatoryNFM

formula to calculate the result. Must follow those rules.

  • Decimal separator must be a . dot.

  • Variables must not be encapsulated by {curly} braces.

  • Example: 3.7*a/(b+4*c)-a**2/4 is a valid representation of \(\frac{3.7}{b+4c}-a^{2/4}\)

  • All available functions are are listed in asteval built in functions

  • Each variable a, b, c needs to be set as a new tag in the spreadsheet. For each of those variables a list of values needs to be given. Each value needs to be separated by a semicolon Each variable name may use any number of letters and numbers, without spaces or special characters.

Warning

excel2moodle uses the ASTEVAL: Minmal Python AST Interpreter, for parsing the mathematical expressions. Broadly speaking the code of result is executed in a more isolated environment to not harm your computer. This makes it harder for malicious code being executed. But still there is a potential security risk when executing external code. Therefore always make sure the result field does not contain code, that could harm your machine.

toleranceoptionalNFNFM

absolute tolerance in which the answer is considered true. Fraction 0.01 or percent 1 Both would be interpreted as a relative Tolerance of \(\pm 1\%\)

  • Any value below \(1\) will be interpreted as a fraction. \(0.8\) would give \(\pm 80\%\) tolerance.

  • Any value above \(1\) will be interpreted as percentage: \(1.3\) would give \(\pm 1.3\%\) tolerance.

Note

If no tolerance is specified for the question, the tolerance from the settings sheet is used. The tolerance definition in the question takes precedence over that in the settings sheet.

unitoptionalNFNFM

‘not yet implemented’

firstResultoptionalNFM

but recommended to verify the formula inside result with the equation-checker tool.