Development log: December 2016, Numbas 2.1

Numbas has acquired a few new features and had a bit of a tidy-up in the last couple of months, so I thought it was time to bump the version number up to 2.1 and let you all know what’s been happening with another development log.

Groups of questions in exams

You can now separate the questions in an exam into groups, allowing you to pick a subset from each group at random. This feature was requested by Ione Loots at the University of Pretoria, who wanted a way of showing students a randomly-picked variation of each question in a test. (documentation, issue)

Extension part

While rewriting the GeoGebra extension, I realised I needed a blank part which was worth marks but delegated the marking to an extension or custom marking script. So I added a new type called “Extension” which does just that.  (documentation)

Intro and outro messages

You can now write some text to be shown on the exam’s front page, and give a selection of texts to show to the student on the results page, based on their score. A couple of people asked for each of these – some people wanted to give some information about how the test would run to students before they begin, and some other people wanted to show a message directing students to a support service if they failed a test. (documentation)

Theme HTML is created using jinja2 templates

While Numbas has always allowed its layout to be changed using themes, if you wanted to change some of the HTML on the page you had to override a single .html file, meaning that you could quickly get left behind as the default theme is updated with new features and bug fixes.

I’ve completely rewritten the way that themes work, so now index.html is created by rendering a collection of template files, using the popular jinja2 templating engine. This allows you to change individual sections of the layout, without affecting any others.  The XSLT file used to create the HTML for questions has also been split up the same way, so as well as it being easier to find the code relevant to what you want to do, you can make small changes without copying the whole template.

This is quite a technical change, but one that will make possible all sorts of new variations on how a Numbas exam is displayed.

While I was doing this, I took the opportunity to refactor the Python scripts which compile Numbas exams. It’s now a lot tidier, and they do say tidiness is next to godliness.

A theme aimed at schoolchildren

I’ve been thinking for a while about how Numbas would need to be adapted to make it more appropriate for use with younger students. The main problem I’ve got in mind is that younger students won’t know as many of the conventions of interfaces, and exams in particular, and would prefer a less formal register. Making everything a bit bigger will help students with less developed motor skills use the interface more easily.

I began by making a variant of the default theme. It has bigger text, in a typeface which is more friendly while maintaining legibility. I tried to do a bit of research about usability of interfaces for younger people, but didn’t find much concrete advice. I tried to add more colours to buttons, to signal more or less dangerous actions (for example, “end test” is in red because it’s irreversible). tick and cross icons are much bigger – I think kids will be more motivated to see this kind of feedback, compared to long text explanations. Finally, I changed a few bits of text – “submit part” is now “check answer”, for example.

I’ve made up a test with some questions on topics from the GCSE maths syllabus to try out these ideas. I’d really appreciate feedback on this – ideally, I’d like to have a theme for Numbas that I’m comfortable recommending to school teachers interested in the system.


Chris requested the ability to link the Numbas LTI provider to an editor instance, so we can provide a menu of ready-made exams for lecturers using Numbas for the first time, through our VLE. Doing this required setting up an API for external tools to retrieve data from the editor. It’s quite basic at the moment – it’ll show you information about published exams, and publicly-visible projects.

The API for the mathcentre is available at It’ll probably change a lot as more things are required of it. To appear through this API, a project has to be marked “visible to the public”, and questions or exams need to be published to the public database and labelled “Ready to use”.

Everything runs in Python 3

The Numbas editor has always run under Python 2, because the Django framework didn’t support Python 3 until a long time after we started. I just checked on Monday, and every package we use now works in Python 3, so I’ve updated the editor code and installation instructions to use Python 3 for both the compiler and editor. This makes setting up your own instance of the editor a lot simpler.

The editor is still compatible with Python 2, so you can carry on as you were if you already had your own instance running.

New JME functions

  • The JME scope object now stores a reference to the containing question, in case an HTML object created by JME function needs to refer to it. (code)
  • The function separateThousands inserts a given character between every three digits in a number. Another product of our trip to South Africa, where they use a dot instead of a comma! (documentation)
  • The function currency formats a number to two decimal places and adds the given prefix or suffix characters. (documentation)
  • When you call transpose on a vector, it returns a one-row matrix. (code)
  • log(x,b) returns the logarithm of \(x\) to the base \(b\), i.e. \(\ln(x)/\ln(b)\) (documentation)
  • angle(a,b) returns the angle between the vectors \(a\) and \(b\), in radians. (documentation)

Other changes

  • Numbas now throws an error message when you set a number entry part to require the student to give their answer to 0 significant figures. (issue)
  • Thanks to a contribution from James Ndegwa Maringa, there’s now a text hint displayed next to number entry parts where the student must round their answer. (documentation, issue)
  • Numbas now uses i18next.js for localisation. i18next is a bit more powerful than the old system, allowing some more natural-looking text in other languages. (code)
  • The compiler now sorts script files by filename before collating them into the file scripts.js. This means that the code is always in the same order each time you compile an exam, making debugging a lot easier! (code)
  • Numbas now shows an error message if one of its scripts has not been executed after the document has finished loading. This can sometimes happen when an extension file is badly written. (code)
  • The question editor now catches most errors in the variable definition field (for example, entering a non-number in a number field) and shows a sensible error message. (code)
  • Copied exams and questions no longer inherit the feedback stamp of the original item.(issue)
  • You can search for a user in the search bar at the top of the page. Clicking on a user’s name will take you to their profile page. (code)
  • The feedback stamps of each question in an exam are shown next to their names, so you can see at a glance if any questions have problems. (issue)
  • The activity timelines on various pages in the editor, most notably the homepage, are now paginated so you can leaf back through older items. (code)
  • When you create an exam from the questions in your basket, your basket is cleared by default, though there’s a checkbox to keep it as-is.  (issue)
  • Searching from the exam or question editors searches inside that item’s project. (code)
  • The compiler will throw a sensible error if it’s asked to use a theme or extension that it can’t find. (code)