This document provides a high-level view of the development tasks required when creating Custom Questions and Features with Learnosity.

 

Custom Questions Overview 

Learnosity provides the building blocks required to assemble and deliver rich, online assessments at scale. From content authoring and assessment delivery, to results and analytics.

At the core of Learnosity are the Questions that allow delivering any of our many out-of-the-box Questions to end users. However, you may want to provide something different for your app.

Learnosity Custom Questions allow you to create your own unique Questions, giving you full control over the rendering of the response area, the user interaction with the Question, and the scoring of the response.

You can integrate technical Features and third-party tools in your Learnosity solution, by creating Custom Questions.

 

Figure 1: the categories of each Learnosity API, the normal Golden Path APIs, and the lower-level APIs used by Custom Questions or Features

 

Separation of Hosting Responsibilities

It is important to highlight that the Custom Question or Feature files are owned by you. This means they must be hosted and supported on your own web server infrastructure. Learnosity will make calls to these files whenever they are requested by an end-user because Custom Question files are not hosted within the Learnosity infrastructure itself.

 

Figure 2: hosting diagram, showing the separation between files hosted by Learnosity or clients

 

Custom Question Code Files

A Custom Question is defined, as with any other Learnosity Question type, by a JSON object that the Questions API will interpret and render. In the Question JSON, you provide URLs to JavaScript files containing the program logic that will drive your Question and Scorer. You will also need to provide a CSS file containing the Custom Question styles. When Authoring you will also need an HTML file for the Question Editor API, containing the Editor Layout.

Figure 3: essential files in a Custom Question for Learnosity

 

Note: it is important to highlight that the Custom Question files are owned by you. They must be hosted and supported on your own infrastructure or web server, outside of the Learnosity system.

 

Custom Question File Descriptions

1. question.js

A JavaScript file that defines an AMD module for the Question, and optionally, Scorer. The Question and Scorer logic can be split into two different files.

 

2. scorer.js

This file contains the scoring logic for the Custom Question (optional -- you can include the scoring logic in the main file if desired). 

 

Important: for successful server-side scoring, the JavaScript files supplied must be accessible externally.

 

3. question.css

This file contains the CSS styles for the Question.

 

4. question.html 

This file contains the Question Editor layout of your Custom Question or Feature when authoring with Question Editor API. Visit our Question Editor's layout page to learn more.

 

Starting your Custom Question project

1. Clone or fork the Custom Questions Skeleton GitHub repo:
   https://github.com/Learnosity/custom-questions-skeleton
2. In the folder demos/custom-question-skeleton you will find the bare bones of a clean Custom Question that you can leverage to start working on your Custom Question project. We recommend renaming this folder to your Custom Question name. See the folder content overview in GitHub for more details.
3. You can now run yarn dev to start the localhost server, and test your Custom Question project from http://localhost:12345 (the default port is 12345 and you can change it to any port that you like).
4. For more technical details, you can go through the README file

Suggested order of development tasks

When planning the development of your Custom Question or Feature, you should approach the process in a specific order, as shown below. 

1. Create the Question structure, logic, rendering, saving and general code, to be used by Questions API. You can work on this in the custom-question-skeleton/src/question/index.js file.
2. Create the Custom Scoring logic following the structure in custom-question-skeleton/src/scorer/index.js
3. Set the CSS styling and presentation using the SASS source code folder.
4. Create the Editor Template to be used by Question Editor API. Have a look at the custom-question-skeleton/authoring_custom_layout.html
5. Once you are done, you can publish your Custom Question.

 

Figure 4: suggested order of development tasks when creating Custom Questions and Features

 

Questions API

The Learnosity Questions API is a lower-level API. Lower-level APIs are not recommended for most projects, however, the process of building a Custom Question starts with building the JSON structure that the Learnosity Questions API will use to render the Question. Once the Question structure is working, this will be integrated to build Items in the Author API, save them in the Item bank and then use them with the Items API on Assessments.

 

Follow the instructions in this article to create the Custom Question JavaScript files. We highly recommend using the Custom Question Skeleton project.

 

Key Concepts for Custom Questions

At this stage in your Custom Question development, you should review the following five topics and ensure you have completed the necessary steps. 

• Rendering your Question
• Saving Responses
• Scoring
• Validation UI
• Question API States

 

Custom Features

Learnosity Features are interactive components similar to Questions, except they do not capture a student response. Learnosity predefined Feature types include interactive calculators, rulers, text passages, protractors, embeddable audio players and video players.

 

You can create Custom Features in a similar way to building Custom Questions. These are just simpler in a way that they won’t capture user responses, so they don’t have validation and scoring.

 

Testing your Custom Question

You can use the Custom Question Skeleton project to test your Custom Questions.

Run yarn dev and you will be able to test your Custom Question on this page:  http://localhost:12345/assessment.php

To test the server-side scoring, update question/response in debugeServerScorer.jsand run the following command: 

yarn debug-server-scorer

 

Authoring

Learnosity authoring tools give you the freedom to create content building Items including Questions and Features. This could be any of the Learnosity Question types including Custom Questions and Features.

The Learnosity Author API leverages the functionality of the Learnosity Question Editor API. We recommend following the instructions on the Custom Question Authoring article.

You will find the following files in the Custom Question Skeleton project to help you achieve this:

• authoring.php: a local Assessment demo page to help you to develop the Schemas and Authoring layout for your Custom Question or Feature.
• authoring_custom_layout.html: the Authoring HTML layout of your Custom Question or Feature.

 

Assessment

The simplest way to deliver an Assessment with Learnosity is using the Items API.

 

Items API is designed to provide either an assessment player experience or allow you to build and deliver formative learning content with bespoke placement of content dotted around your learning material.

 

Once an Item has been authored in Learnosity and saved in the Item bank, you can then use it in assessments. There is no difference in usage when the Item has Custom Questions.

 

Analytics

No extra work to be done. Analytics APIs will work seamlessly with your Custom Question or Feature.

 

Caveats

Custom Questions and Custom Features currently cannot be accessed in an offline app mode, or with Local Device Assessment (LDA).