Embedding Numbas content in other pages#

Numbas can be used as a generic library in any webpage, providing a <numbas-exam> custom HTML element which will load and display a Numbas exam.

To do this, first download a standalone copy of a Numbas question or exam. It doesn’t matter which exam or question you download. If you want to include single questions in your page, download a question so that the single-question theme is used.

Setting up the page#

The files numbas.js and numbas.css contain the JavaScript logic and CSS stylesheets. You should load numbas.js in your page, and make sure that numbas.css is accessible.

Inside index.html, there is a large <template> element with the ID numbas-exam-template. Copy all of this into your page, and change the URL in the <style id="numbas-style"> tag to the URL of your copy of numbas.css.

Note

At the moment, the default Numbas theme uses an icon font for the tick, cross and warning feedback symbols. Due to a browser limitation, the definition of the icon font can’t be inside the custom element, so you have to copy it across to your main page’s stylesheet.

From numbas.css, copy the @font-face block defining font-family: 'FontAwesome' into your page’s stylesheet.

In the future we will replace the icon font with SVG symbols which won’t have this limitation, and this step won’t be needed.

Now you are ready to include Numbas content in your page.

Embedding a Numbas exam#

Wherever you want to embed Numbas content, write a <numbas-exam> tag.

Attributes#

source_url

The URL of the .exam file defining the question or exam. You can get this from the Download source link in the Numbas editor.

It is possible to load published .exam files directly from the Numbas editor, but it’s best to take a copy of the file yourself.

Or instead of using this attribute, you can include a <script type="application/numbas-exam"> tag inside the <numbas-exam> tag with the content of the .exam file.

noload

If this is present, then the exam doesn’t load automatically when the page loads.

This is a good idea if you have lots of exams in the page. You can use the .load_exam() method on each <numbas-exam> element when you want it to load.

scorm

If this is set to false, then the exam will not try to use the SCORM API in the containing page.

If you have multiple Numbas exams in the same page and a SCORM API, make sure to set scorm="false" on all, or all but one, of the <numbas-exam> elements in the page, so that they don’t conflict with each other.

template

The ID of the <template> element that contains the templates for Numbas to generate HTML. If you omit this, the ID numbas-exam-template is used.

Properties#

The element object has an exam property which can be accessed from JavaScript, representing the Numbas.Exam object which this element contains.

Wait until the numbas:setExam event has been triggered before trying to access this.

Methods#

load_exam()#

Load the exam.

This is called automatically when the element is connected to the page and the document has finished loading, unless the noload attribute is set.

Once called, it will wait for the Numbas runtime to finish loading before loading the exam.

If the exam has already been loaded, it does nothing.

Events#

The <numbas-exam> event will trigger an event for each signal and event produced by the Numbas exam object.

The names of signals are prefixed with numbas:signal:, and events are prefixed with numbas:event:.

It also triggers events numbas:loaded after the exam’s ready signal has triggered, and numbas:setExam once the element’s .exam property is set.

Extension data#

If the exam uses any extensions, you must tell Numbas how to find the extension’s files by adding a <script type="application/json" slot="extension-data"> element inside <numbas-exam>.

You must obtain a copy of the files for each extension used and put them somewhere that can be accessed from your page. If you download a standalone .zip of the exam from the editor, all of the extension files are included in a directory called extensions, and the data JSON is in the file :file:extensions/extensions.json.

The extension data JSON has the following format:

{
    (The extension's name): {
        "root": (The root URL of the extension's files),
        "javascripts": (a list of filenames of all JavaScript files needed by the extension, relative to the root),
        "stylesheets": (a list of filenames of all CSS files needed by the extension, relative to the root)
    }
}

So an exam which uses JSXGraph, loaded from extensions/jsxgraph, would look like this:

<numbas-exam source_url="test.exam">
    <script type="application/json" slot="extension-data">{"jsxgraph": {"root": "extensions/jsxgraph", "stylesheets": ["jsxgraph.css"], "javascripts": ["jsxgraph.js"]}}</script>
</numbas-exam>

Example#

There is a short page demonstrating this at numbas.org.uk/demos/generic-runtime.

Embedding Numbas content in other pages

Contents