Overview

This guide describes the basics of embedding, configuring and working with Learnosity's Grading API, an embeddable API for scoring Learnosity Items. 

We'll set up a simple example page for an educator grading a learner's activity, then look at the code in detail. 

Prerequisites

• Basic PHP, JavaScript and HTML knowledge.
• This quick start's server side code is written in PHP, but multiple languages are supported, such as Java, .net, Python and more.
• A PHP-enabled web server, installed on your local machine. (To set up a simple test environment, follow our environment setup guide.)

Download the quick start example, or visit our PHP GitHub repository for other options such as "git clone", or installation via Composer.

The quick start example package includes:

• The Learnosity Software Development Kit (LearnositySDK).
• The quick start example files.

Once set up, you can load the examples index page at http://localhost:8000/index.html.

How it works

Server-side code

We start by including some Learnosity SDK helpers - they'll make it easy to generate and sign the config options.

<?php
    include_once 'vendor/autoload.php';
    use LearnositySdk\Request\Init;

Then we declare the config options for Grading API:

• rendering_type - inline is the only rendering type currently available. 
• user_id - The ID of the grader scoring the session. You must specify this option so that the grader is identifiable, and to prevent score overrides. It must not exceed 50 characters nor contain any personally identifiable information. We suggest a UUID for this value.

• session_id - The ID of the session the grader will be evaluating.

• state - The grader’s mode of grading
  • initial - the grader is in edit mode where they can re-score and post their feedback
  • review - the app is readonly mode wherein the grader can not edit nor save the session, useful for audits or learner review.

"request": {
    "rendering_type": "inline",
    "user_id": "graderid0-3c46-4c64-8f48-805be0b73a1",
    "session_id": "ad6a30ba-a4bf-492f-9d11-575e57e705c0",
    "state": "initial"
}

Next, we declare the Learnosity consumer credentials we'll use to authorize this request. These keys grant access to Learnosity's public demos account. Once Learnosity provides you with your own consumer credentials, your Item bank and assessment data will be tied to your consumer key.

$consumerKey = 'yis0TYCu7U9V4o7M';
$consumerSecret = '74c5fd430cf1242a527f6223aebd42d30464be22';

We construct security settings that ensure Grading API is initialized on the intended domain.

$security = [
    'domain'       => $_SERVER['SERVER_NAME'],
    'consumer_key' => $consumerKey
];

Now we call LearnositySDK's Init() helper to construct our Grading API configuration parameters, and sign them securely with the $security and $consumerSecret parameters. $init-generate() returns us a JSON blob of signed config params.

$Init = new Init('items', $security, $consumer_secret, $request);
$signedRequest = $Init->generate();
?>

Web page content

For a grader to evaluate a session, initialize the Grading app to create a new instance and to load and interact with the Learnosity Grading interface. This will return a promise that resolves if the init is successful or a catch if the init failed.

The init method is called from the LearnosityGrading factory, and should only be called once per instantiation of the Grading API.

Syntax:

LearnosityGrading.init(initOptions, hook)

Grading API can be initialized by using the method "init()" with the required parameters of the initialization object and the DOM hook element. This will return a promise of the API instance if the intialization is successful otherwise will return an error.

<div id="hook-element"></div>
...
<script>
const initOptions = {
    "security": {
        "consumer_key": "**",
        "user_id": "***",
        "signature": "***"
    },
    "request": {
        "rendering_type": "inline",
        "user_id": "graderid0-3c46-4c64-8f48-805be0b73a1",
        "session_id": "ad6a30ba-a4bf-492f-9d11-575e57e705c0",
        "state": "initial"
    }
}

const hookElement = document.querySelector('#hook-element');

LearnosityGrading.init(initializationObject, hookElement)
    .then((app) = {
        // Attach the API instance to the window object        
       window.gradingApp = app;
    })
    .catch((error) = {
        // ....
    });
</script>

Once the Grading API has been initialized, the Item with the responses to be scored can now be attached inline to the hook element using the method attachItem().

<script>
  const hookElement = document.querySelector('#item-element');
  const payload = {
    sessionId: "ad6a30ba-a4bf-492f-9d11-575e57e70123",
    userId: "abca30ba-a4bf-492f-9d11-575e57e70123",
    item: "item-to-grade",
    element: hookElement
  };

  window.gradingApp.attachItem(payload);
</script>

Use the method save() to save all the Items with the modified score, max score, and feedback.

<script>
  window.gradingApp.save();
</script>

Sample code :

<!DOCTYPE html>
<html>
    <head>
        <link rel="stylesheet" type="text/css" href="../css/style.css">
    </head>
    <body>
        <script src="https://grading.learnosity.com"></script>

        <div id="grading-container"></div>

        <script>
        const initOptions = {
            "security": {
                "consumer_key": "**",
                "user_id": "***",
                "signature": "***"
            },
            "request": {
                "rendering_type": "inline",
                "user_id": "graderid0-3c46-4c64-8f48-805be0b73a1",
                "session_id": "ad6a30ba-a4bf-492f-9d11-575e57e705c0",
                "state": "initial"
            }
        }
        const hookElement = document.querySelector('#grading-container');
        LearnosityGrading.init(initOptions, hookElement)
            .then((app) => {
                // make reference of the app
                window.gradingApp = app;
            })
            .catch((error) => {
                // ....
            });
        </script>

    </body>
</html>