# numbas/editor-docs

Switch branches/tags
Nothing to show
Fetching contributors…
Cannot retrieve contributors at this time
374 lines (213 sloc) 18.8 KB

# How do I...

This section largely draws from the "How-tos" project on the numbas.mathcentre.ac.uk editor, where we gather example questions created to demonstrate authoring techniques.

If you've got a question that isn't answered here, try asking on the Numbas users mailing list.

## Images, diagrams and other media

### Include an image

It's best practice to attach images to questions so that they're distributed with the final compiled exam, rather than linking to images stored on a webserver.

When editing a content area, click on the :guilabel:Insert/Edit Image button. You can then either pick an image you've already uploaded, or click the :guilabel:Choose file button to upload an image from your computer.

You can resize images and add a title attribute by selecting the image in the content area and clicking on the :guilabel:Insert/Edit Image button.

### Embed a video

Upload your video to somewhere like YouTube or Vimeo. Including videos in downloaded exam packages is a terrible idea, so we discourage that. Click the :guilabel:Embed image/video button (it's a blue cloud), and paste in the URL of your video.

### Include an interactive diagram

There are a couple of ways of including an interactive diagram in a Numbas question. You can either embed a GeoGebra applet, or use JSXGraph.

For JSXGraph diagrams, there is :ref:an extension <jsxgraph-extension> which takes care of most of the setup. You will need to write a fair amount of JavaScript code to create a diagram using JSXGraph.

GeoGebra applets are much easier to create and use, but are loaded from geogebra.org so the student must have internet access in order to use any questions containing GeoGebra applets.

The screencast below explains how to use a GeoGebra applet in a question. For more information, see the page on the :ref:geogebra extension <geogebra-extension>.

### Show one of several images based on a random variables

See the question Using a randomly chosen image for an example of one method.

### Display a random line in a GeoGebra applet

A neat way to create a random line is to randomly pick the positions of two points on the line.

Create two points in your GeoGebra worksheet, and a line between those two points. Set the positions of the points in the parameters to the :jme:func:geogebra_applet function.

### Use student input in a JSXGraph diagram

This question shows how to construct a line corresponding to an equation given by the student.

## Appearance and display

### Change how the question looks

You can use the formatting tools in the question editor to style your text. However, if you repeat the same styles over and over, or want to change aspects of the layout such as space between elements or decoration, you'll need to write some CSS.

CSS is a language for defining how things should look - there's a good introduction at Khan Academy. In the Numbas editor, you can add CSS rules to a question in the :ref:preamble section.

The following questions demonstrate how to use CSS to change the look of a Numbas question:

### Reveal the answer to a single part after submitting an answer

Someone wanted to know how to reveal the answer to one part of a question as soon as the student submits an answer, because the following part depends on having the correct answer to the first part.

This example question shows a few different ways of doing this.

Think very carefully before using this: by revealing the answer, you are removing the opportunity for the student to later on realise they've got that step wrong, as a consequence of some further work. It's often possible to use :ref:adaptive marking <adaptive-marking> to use the student's answer in place of the correct answer in later parts.

### Set an attribute on an HTML element based on the value of a question variable

Use the :guilabel:Source code view in a content area to edit its HTML code. You can set the value of an attribute on an HTML tag to the result of a JME expression by prefixing the attribute's name with eval-. Variables are substituted into the attribute's value using curly braces.

For example, this tag will have its class attribute set to the value of the variable classes:

<div eval-class="{classes}">


## Question text

### Show one of several blocks of text based on a random variable

Suppose you have a random variable a, which has the value 1,2 or 3, corresponding to three different scenarios. First, write out the text for each scenario.

There is a button in the :ref:rich text editor <content-areas> labelled :guilabel:Conditional visibility. This allows you to give an expression (in :ref:JME syntax) which dictates whether or not the selected text is shown. For each scenario, select the corresponding text and click on the :guilabel:Conditional visibility button. Enter a=1 for the first block, a=2 for the second, and a=3 for the third.

When you run the question, only the block of text corresponding to the value of a is shown.

You can see an example of this technique in the question Conditional visibility.

### Check that the student has simplified a polynomial fraction

This question uses pattern-matching to check that the student's answer is in the form \frac{x+?}{?}. In combination with the normal mathematical expression marking algorithm, this confirms that the student has simplified a fraction of the form \frac{x+a}{x+b}.

### Check that the student has factorised a quadratic expression

This question uses :ref:pattern-matching to check that the student's answer is the product of two factors. In combination with the normal mathematical expression marking algorithm, this confirms that the student has factorised the expression.

### Use data from a CSV file that the student has uploaded

This question uses some custom JavaScript to process a file that the student uploads, and use it to set the correct answers for the question's parts.

## Variable generation

### Make sure my generated variables satisfy a condition

Use the :ref:variable testing <variable-testing> tools.

### Generate a random list of unique numbers

Suppose you want to pick a list of numbers from a given range, but don't want any repeats.

Use the :jme:func:shuffle function to put the numbers in random order, then take as many as you need from the front of the resulting list. The example below picks three distinct numbers between 0 and 10:

shuffle(0..10)[0..3]


### Assign several variables corresponding to a scenario

A simple way of randomising a question, particularly when working with real-world data, is to come up with a number of distinct scenarios. Use the :data:dictionary data type to list the values of variables corresponding to each scenario, then pick randomly from a list of these dictionaries.

This more sophisticated example combines lists of names with JSON data to construct a table of data about people's hobbies.

JSON is a commonly-used format to store data in a way that is easy for both people and computers to read.

The following questions show how to use large JSON data sets in Numbas questions:

## Maths

### Find the factors of a number

If your number is small enough - as a rule of thumb, at most 5 digits - the easiest way to list all the factors of a number N is to check each lower number for divisibility by N:

filter(x|n, x, 1..n)


### Find the prime factorisation of a number

Primality testing is a difficult topic, but if your number is small enough it's easiest just to check against a hard-coded list of prime numbers. The following produces a list of pairs [prime, power] for the prime-power factors of the number n:

filter(x[1]>0,x,zip(primes,factorise(n)))


See this example question, which also produces LaTeX code to show the factorisation.

### Randomly give two of hypotenuse, opposite, and adjacent side of a triangle

This question shows how to randomly generate a Pythagorean triple - a right-angled triangle with integer-length sides - and randomly show two of the lengths to the student. The student is asked to calculate the length of the third side.

### Take a logarithm to a randomly-chosen base.

The built-in JME functions :jme:func:ln and :jme:func:log compute logarithms to base e and 10, respectively. :jme:func:log can take a second parameter defining the base. For example:

log(x,3)


Computes \log_3(x).

This example question shows how to ask the student to enter a mathematical expression containing a logarithm to a randomly-chosen base, or with an unbound variable as the base.