Use the Items API, in inline or assess mode, to create an assessment.

Introduction

This tutorial will cover the creation of a basic assessment using Learnosity's Items API. The Items API provides a simple way to embed assessment content from your Learnosity item bank into your web application. The assessment can be presented in a self-contained player, or each question can be placed exactly where you want it to appear in your product design.

This tutorial assumes you are comfortable with PHP, JavaScript, and HTML, and have a working knowledge of Learnosity items. Understanding Learnosity's items and questions was discussed in the Questions and Items tutorial.

Using the Learnosity SDK

The first step in interacting with any Learnosity API is to authenticate the client and securely sign the API server request. This ensures that a valid client is accessing the API, and also protects the data from outside manipulation. In short, this security allows both Learnosity and our customers to know that no data has been changed en route between client and server.

To simplify the security process, Learnosity offers an easy to use SDK to handle the signing of each server request. The SDK is available in a number of languages, and these tutorials will use the PHP version.

If you want to build this tutorial from scratch, download the SDK of your choice, rename the folder “learnosity-sdk” and place it into a parent directory you plan to use for these files. If you prefer to just follow along, you can download the completed tutorial files. Once you're ready to begin, we’ll cover the minimum code required for secure signing, and tuck these tasks into a config file for efficient reuse.

The Config File

Lines 3 and 4 of config.php start things off with the consumer key and consumer secret—two components of customer credentials supplied by Learnosity. The consumer key is a public key, and the consumer secret is a private key known only by the client and Learnosity. The consumer secret should never be exposed by sending it to the browser or across the network such as in email or a support ticket.

Note: This tutorial uses demo values for the consumer key and secret. In production, you must use your own consumer key and secret.

 1  <?php
 2
 3      $consumer_key = "yis0TYCu7U9V4o7M";
 4      $consumer_secret = "74c5fd430cf1242a527f6223aebd42d30464be22";
 5
 6      $domain = $_SERVER["SERVER_NAME"];
 7
 8      $security = array(
 9          "consumer_key" => $consumer_key,
10          "domain"       => $domain
11      );
12
13      include_once "learnosity-sdk/src/LearnositySdk/autoload.php";
14
15  ?>

Code example 1: code for secure signing in config.php

Line 6 stores the site domain—the name of the API's client host. The domain value included in the security object will need to match location.hostname of the client system and, during the authentication process, the server will check to make sure that each domain is one of the customer’s authorized domains. For testing purposes, “localhost” will always work.

Lines 8 through 11 create the security object, including the consumer key, and domain. Immediately prior to initializing an API, the SDK will use the SHA256 hashing algorithm to combine all of these values, along with the request object we’ll discuss in a moment, to create a signature. Learnosity will perform the same operation on the server side, and the signatures must match to proceed.

The last line of the config file, line 13, references an autoloader to simplify including dependencies and reduce related errors. The autoloader will attempt to load any class or interface which hasn't yet been defined, before throwing an error.

Using Config and Autoloader

Now that the config file is complete, we can include it at the top of the main tutorial file, tutorial_102.php. We’ll also create aliases, in lines 5 and 6, to the SDK’s Init and Uuid classes, preventing the need to use their fully qualified paths.

 1  <?php
 2
 3      include_once 'config.php';
 4
 5      use LearnositySdk\Request\Init;
 6      use LearnositySdk\Utils\Uuid

Code example 2: creating aliases for the Init and Uuid classes.

Building the Assessment

Now that we’ve got the security out of the way, we’re ready to create the request object, which includes student and session information, and the items that will be displayed in the assessment, and properties that control the assessment’s appearance and behavior.

The student ID shown in line 9 links a student to submitted results. It’s typically the same student ID as used in the host system but can be anything you choose, as long as it's unique. Similarly, a unique session ID allows reports to be run on a specific session that any student may have submitted. This session ID value should be stored by the customer so it can be used when requesting reports in the future. For this tutorial, a unique session id is generated by the SDK’s Uuid class in line 10.

 
8   $request = array(
9       "user_id"        => "student_1234",
10          "session_id"     => Uuid::generate(),
11          "items"          => array("Tut002_Item1", "Tut002_Item2", "Tut002_Item3"),
12          "rendering_type" => "inline",
13          "type"           => "local_practice"
14      );

Code example 3: creating the request object.

As stated in our security policy, Personal Identifiable Information should not be used as a user_id. We recommend using a hashing function (e.g. SHA256, bcrypt etc) to generate a unique identifier (and, optionally, prepending a user type such as 'student', 'teacher' or 'admin'). Identifiers such as 'firstname.surname', or email addresses should not be used as user_ids.

Line 11 holds the array of items displayed. Line 12 specifies the rendering type of the assessment. Items can be rendered into DOM elements that match the names of the item references, allowing the customer full control over placement (“inline”), or can be collected into a single DOM element, complete with navigation (“assess”). The request object and accompanying HTML in this segment of this tutorial will be rendered inline. In a few moments, we’ll look at the collected, or assess, rendering method.

Line 13 sets the items. By default, no state has to be defined. At different stages of the assessment process, other states may be “preview” (to audition an item, for example) or “review” (after validation). Finally, line 14 sets the assessment type as a “local_practice” type. This is ideal for questions that have been configured with a Check Answers button. Local practice allows the student to see validated results locally without submitting to the server. Using “submit_practice” will instead submit the assessment to the server, typically without using the Check Answers feature, leaving the decisions if, when, and how session reports are shown to the host environment.

Note If you plan to use specific questions in multiple contexts, using the Author site to add a Check Answers button at the question level increases flexibility. You can use the feature for instant feedback, or suppress it for submitted graded assessments. We'll look at both options in this tutorial.

Signing the Request

The final step in the security and authentication process is to initialize and sign the request. The SDK’s Init class in line 30 accepts the array of items to be shown in the assessment, the security object, the consumer secret, and the request object as parameters. The generate()method of the class instance, shown in line 31, creates the signed request that will be used when the Items API is initialized in JavaScript in a few moments.

Note: We’ve left a gap in line numbers simply to make the numbering consistent across multiple examples in this tutorial.

30      $Init = new Init("items", $security, $consumer_secret, $request);
31      $signedRequest = $Init->generate();
32
33  ?>

Code example 4: initializing and signing the request.

This wraps up the PHP required, and next we need to create a minimal HTML page to display the assessment.

Creating the Host Page

The following block of HTML shows a basic page skeleton, but the most important thing to note are the <span> elements in lines 44-46. The data-reference attributes contain the item reference for each item displayed. The customer is in complete control of the layout of the assessment. While it’s not typically a best practice to use inline styles, line 42 of this stripped down example demonstrates, in an unobtrusive way, that items will automatically fill their containers.

35  <!DOCTYPE html>
36  <html lang="en">
37      <head>
38          <meta charset="utf-8">
39          <title>How Color Works</title>
40      </head>
41      <body>
42          <div style="width:750px;">
43              <h3 class="item-title">The Color Wheel</h3>
44              <span class="learnosity-item" data-reference="Tut002_Item1"></span>
45              <span class="learnosity-item" data-reference="Tut002_Item2"></span>
46              <span class="learnosity-item" data-reference="Tut002_Item3"></span>
47
48          </div>

Code example 5: creating the host page.

Initializing

All that remains is to load and initialize the Items API in JavaScript. Line 50 includes the latest version of the Items API, which can be helpful for testing. For production releases, a specific version of the API should be appended. Line 52 initializes the Items API, using as its parameter the signed request created in PHP.

50          <script src="//items.learnosity.com?[VERSION]"></script>
51          <script>
52              var itemsApp = LearnosityItems.init(<?php echo $signedRequest; ?>);
53          </script>
54      </body>
55  </html>

Code example 6: loading and initializing Items API.

The Rendered Assessment

The output of this tutorial is a simple HTML page with three questions rendered inline. Each question was configured with a Check Answer button for immediate feedback, and the assessment operates in local practice mode. This can be useful for sample questions preceding graded material, study questions, or classroom discussion.

Figure 1: Using rendering_type "inline".

Additional Options

We’ll now modify this example in a couple of simple ways to show the flexibility of the Items API. Multiple source files have been included in the downloadable archive to represent each of these options.

Submitting the Assessment

The first change we’ll look at is enabling the assessment to submit results so reports can be run on the session at a later time. To do this, we need to make a few changes to the request object, and HTML page.

In the PHP portion of the code, we need to use the “submit_practice” type (instead of “local_practice”) in the request object, and add a configuration object to render a submit button and suppress instant feedback. We also need two additional properties to submit activities.

activity_id: This is a unique reference to the activity, and should be the same for all students submitting results from this activity. It is used for reporting and comparison.
name: This is a descriptive name for this activity which is displayed in reports.

Note: An activity is the assessment delivered to the student and can be created dynamically, as in this tutorial, or in the Learnosity Author site.

Lines 14 through 23 in the edited request object address the changes described above. In particular, lines 18 through 20 cover the config option. Line 19 will render a submit button into the HTML DOM element we'll create in a moment, and lines 20 through 22 will suppress the instant feedback provided via the question-level Check Answers button.

8  $request = array(
 9      'user_id'        => 'student_1234',
10      'session_id'     => Uuid::generate(),
11      'items'          => array('Tut002_Item1', 'Tut002_Item2', 'Tut002_Item3'),
12      'rendering_type' => ‘inline’,
14      'type'           => 'submit_practice',
15      'activity_id'    => 'demo_activity',
16      'name'           => 'The Color Wheel',
17      'config'         => array(
18                              'renderSubmitButton' => true,
19                              "ignore_question_attributes" => array(
20                                  "instant_feedback"
21                              )
22                          )
23  );

Code example 6: enabling the assessment to submit results.

Adding a Submit Button when Rendering Inline

Because the assess rendering type renders everything in a single container, a submit button is automatically created when using submit practice. When rendering an assessment inline, however, we need to add a element into which a submit button can be created. This span must have a class called “learnosity-submit-button”.

34    <div style="width:750px;">
35        <span class="learnosity-item" data-reference="Tut002_Item1"></span>
36        <span class="learnosity-item" data-reference="Tut002_Item2"></span>
37        <span class="learnosity-item" data-reference="Tut002_Item3"></span>
38        <span class="learnosity-submit-button"></span>
39    </div>

Code example 7: adding an element for a submit button.

Rendering Using Assess

The second option we’ll look at is rendering all the items in a single DOM element, complete with navigation. This is accomplished by using the Learnosity Assess API to render the items, and requires a few changes to the request object and host HTML. We’ll look at using the assess rendering style for both local practice and submit practice use.

Changing the Request Object for Local Practice

The first change we need to make is to switch the assessment rendering type from “inline” to “assess” in line 12 of the request object. We’ll also apply two settings to the configuration of the Assess API, which is responsible for the rendering in assess mode. In line 16, we’ll use the “horizontal” UI style to place the navigation bar at the bottom of the assessment. This allows the items to fill more horizontal space in the container. And, because this is local practice, we’ll tell the Assess API not to render a submit button at the end of the assessment. We do this via the navigation object in lines 17 through 19. Additional documentation about the Assess API configuration and navigation features are available in the Assess API initialization options section of the Learnosity documentation site.

 8  $request = [
 9      'user_id'        => 'student_1234',
10      'session_id'     => Uuid::generate(),
11      'items'          => ['Tut002_Item1', 'Tut002_Item2', 'Tut002_Item3'],
12      'rendering_type' => 'assess',
14      'type'           => 'local_practice',
15      'config'         => [
16                              'ui_style'   => 'horizontal',
17                              'navigation' => [
18                                  'show_submit' => false
19                              ]
20                          ]
21  ];

Code example 8: changing the request object for local practice.

Changing the Page Markup

The change required in the HTML is actually a simplification. We just need to remove the item-specific DOM elements and replace them with one DOM element for the assess engine. This element must be a <div> with the ID “learnosity_assess”.

42          <div style="width:750px;">
43              <h3 class="item-title">The Color Wheel</h3>
44              <div id="learnosity_assess"></div>
45
46
47
48              </div>

Code example 9: replacing item-specific DOM elements with one DOM element for the assess engine.

Changing the Request Object for Submit Practice

Using the assess rendering type for submit practice requires no further changes to the HTML, but a few changes to the PHP request object. As with inline submit practice, we need to update the type, and add the activity_id and name properties, in lines 14-16.

Finally, after submission, the assess engine will show a Close button to redirect the student. We must include the configuration object of the Assess API in lines 23 through 25, providing the page to which the assessment will redirect. If you don’t want to redirect at all, you can use false for this value, and the Close button will do nothing.

8  $request = [
 9      'user_id'        => 'student_1234',
10      'session_id'     => Uuid::generate(),
11      'items'          => ['Tut002_Item 1', 'Tut002_Item2', 'Tut002_Item3'],
12      'rendering_type' => 'assess',
14      'type'           => 'submit_practice',
15      'activity_id'    => 'demo_activity',
16      'name'           => 'The Color Wheel',
17      'config'         => [
18                              'ui_style'                   => 'horizontal',
19                              'ignore_question_attributes' => [
20                                  'instant_feedback'
21                              ],
22                              'configuration' => [
23                                  'onsubmit_redirect_url'  => 'index.html'
24                              ]
25                          ]
26  ];

Code example 10: updating the type, adding the activity_id and name properties.

The Result

The assess engine renders the items one at a time, with a navigation bar to allow students to move forward and (optionally) backward through the assessment.

Figure 2: Using rendering_type "assess".

What you learned

In this tutorial we learned how to create a basic assessment using Learnosity's Items API. We learned how to render the assessment in a single, navigable engine, as well as in item-specific containers for maximum control over page design. We also learned how to create an assessment that could be used for low stakes study, or submit to a server for scoring and reporting. Additional tasks are available for review in the Additional Resources section of this tutorial, including how to listen for an assessment’s Ready event, and how to add a save button.

Additional Resources

Where to Next?

Up next in Displaying a Session Detail Report, we’ll discuss how to run reports on submitted results.