Adapt Learning Hello Something Plugin

Hello Something Plugin

In a previous post I stepped through creating a basic Adapt plugin that outputs the static text Hello World https://ianluckraft.co.uk/2020/05/adapt-learning-hello-world-plugin/ . But a plugin that only outputs some static text is possibly less than useful. In this post we’ll look at the next logical step of allowing a course builder to add some dynamic text to the output.

As a starter we will clone the Hello World plugin and then replace World with Something. If you want to follow along clone the repo from this commit https://github.com/ianckc/adapt-hello-something-plugin/commit/c6c66b2c700e82a6061ce48f81a7b78b710a8fdd

The complete plugin code can be seen in the GitHub repo.

To add extra fields to the plugin we need to edit the properties.schema file.

There is already a properties object with a _supportedLayout key. We need to add two more JSON objects at the same level as _supportedLayout

I’ll paste them here and then we will look at each of them to identify their purpose.

"instruction": {
  "type": "string",
  "required": false,
  "default": "",
  "inputType": "Text",
  "validators": [],
  "help": "Enter the instruction text for this component.",
  "translatable": true
},
"somethingElse": {
  "type": "string",
  "required": true,
  "default": "Enter your something else here.",
  "title": "Text to say hello to",
  "inputType": "Text",
  "validators": [],
  "help": "When output the component will say Hello followed by the text you enter",
  "translatable": true
}

The first property with the key of instruction allows an author to add some instructional text applicable to the component. This could be something such as “Select all of the images containing the world” for a component requiring users to select from a set of images.

If used in the authoring tool it will display as a text input and is not required.

The second property with the key somethingElse is the string that we will be outputting in the template file. It contains the same properties as the instruction object but we set a default value that will appear in the input and also make it required.

The next step is to update the template file templats/helloSomething.hbs

We only need to make a single change to output the text entered in the somethingElse input.

Change the H1 tag to the following

<h1>Hello {{{somethingElse}}}</h1>

If there is instruction text it will be output by default due to the Handlebars partial being called with

{{> component this}}

To use our new component in an Adapt course there are two options, built via the command line tool or in the authoring tool.

Via the Command Line Tool

Open up the components file inside the correct language directory. I am using English so the path to my file is src/course/en/components.json

Add a new JSON object with a unique ID and the correct parent ID, this is the block ID that the component will be nested in. If you do not require instruction text then leave it as an empty string e.g. "instruction": “",

{
    "_id":"c-03",
    "_parentId":"b-05",
    "_type":"component",
    "_component":"helloSomething",
    "_classes":"",
    "instruction": “Look at the text we are outputting",
    "somethingElse": “The Sun"
}

If we then launch our course it will look like this

Via the Authoring Tool

First we need to create a zip file of the adapt-hello-something-plugin directory that contains all of our code. Next in the Authoring Tool click the hamburger menu icon in the top left and choose Plugin Management from the dropdown menu.

You will now be on the Manage Available Extensions page. Click the green Upload Plugin menu in the left hand column. On the Upload Plugin page select the zip file you have just created and then click the green Upload button in the left hand column. After a successful upload you should be on the Manage Available Components and the Hello Something plugin is listed and is enabled.

To use the Hello Something component navigate to your chosen course and edit a page. Select Add component inside a block and look for the Hello Something option inside the Add component drawer. Select the layout you wish to use (left, full or right).

Now the component has been added double click it to edit the settings. Under Properties you will see the two fields we defined in properties.schema, Instruction and Text to say hello to. The instruction is optional but you will need to add something in the Text to say hello to field.

After saving the updates to the component you can now preview the course and you will see the component output with the text you have entered. Below is a screenshot where I have added it to my Hello World course.

Now you have seen how to add fields to your Adapt plugin the next step would be to add some creative interactivity to really engage the learner and deliver high value courses.

Adapt Learning Hello World Plugin

This tutorial will not go into depth about some of the code used. The idea is to give an overview of creating a basic Adapt plugin that will output some static text.

The plugin code can be downloaded from gitHub.

The Adapt framework comes with a good selection of components to help you build your e-learning course, then added to this are the contributed plugins. But what if there isn’t quite the thing you need? The good news is that like all good Open Source software you can just make your own.

In this tutorial I’m going to make a very simple bare bones plugin that will allow us to add a component that simply says Hello World.

Before you begin you will need to install the Adapt CLI and Bower.

To give us somewhere to test our plugin we will create a new Adapt course. In terminal run the following command

adapt create course

Accept all of the defaults except the name which we will set to plugin-development.

Once the framework has been downloaded follow the instructions to build and run the course.

cd plugin-development
grunt build
grunt server

You will now have a course running at http://localhost:9001

From within the plugin-development directory navigate to src/extensions and create a new directory called adapt-helloWorld which will contain our plugin.

In a terminal window cd into the adapt-helloWorld directory and run bower init

Name adapt-helloWorld

Description An example Adapt plugin to say Hello World

Main file js/adapt-helloWorld.js

Keywords adapt-plugin,adapt-component

Authors Accept default

License Accept default

Homepage Accept default

Set currently installed components as dependencies No

Add commonly ignored files to ignore list? Yes

Would you like to mark this package as private which prevents it from being accidentally published to the registry? Yes

Looks good? Yes

We now have a bower.json file inside the adapt-helloWorld directory. In addition to the elements Bower has created for us we need to add some extra ones for this to be a valid Adapt component.

Open up bower.json in a text editor and add a comma after the closing square bracket of the ignore array so it looks like this

  "ignore": [
    "**/.*",
    "node_modules",
    "bower_components",
    "src/plugins",
    "test",
    "tests"
  ],
}

We will be adding in four new elements in between the comma we added and the closing curly bracket to ensure we have valid JSON.

Add the following

  "version": "0.0.1",
  "framework": ">=5.0",
  "component": "helloWorld",
  "displayName": "Hello World"

The end of bower.json will now look like this

  "ignore": [
    "**/.*",
    "node_modules",
    "bower_components",
    "src/plugins",
    "test",
    "tests"
  ],
  "version": "0.0.1",
  "framework": ">=5.0",
  "component": "helloWorld",
  "displayName": "Hello World"
}

Adapt follows the Asynchronous module definition (AMD) specification and utilises RequireJS and Backbone for plugin architecture.

Add the following to js/adapt-helloWorld.js

define([
    'core/js/adapt',
    'core/js/views/componentView',
    'core/js/models/componentModel'
], function(Adapt, ComponentView, ComponentModel) {

var HelloWorldView = ComponentView.extend({
    postRender: function() {
        this.setReadyStatus();
        this.setupInviewCompletion();
    }
});

    
    var HelloWorldModel = ComponentModel.extend({
        // Implement your component model
    });

    return Adapt.register('helloWorld', {
        model: HelloWorldModel,
        view: HelloWorldView
    });

});

The first 5 lines use RequireJS to include the module we need to create our plugin.

We then create two variables for the view and the model that extend their respective component bases.

Inside ComponentView.extend we need to add a postRender method that calls two Adapt functions. Without these two calls the course will not load.

The last part of the file registers our plugin with Adapt, passing the view and model variables to it.

We’ll now create a basic template file to add some output.

In the adapt-helloWorld directory create a new directory called templates and inside that create a file called helloWorld.hbs

This is a Handlebars template file which is the templating engine used throughout Adapt. https://handlebarsjs.com/

Add the following to helloWorld.hbs

<div class="component__inner helloWorld__inner">
    {{> component this}}
    <h1>Hello World</h1>
</div>

The wrapper div follows some naming conventions used in other plugin template files.

The second line uses a Handlebars partials, you can read more about those on the official Handlebars site. https://handlebarsjs.com/guide/#partials

Then for good measure we say Hello World in a H1, as it’s very important.

The last thing we need to do to make this a valid Adapt component is to add a properties.schema file. According to the Adapt wiki “properties.schema is a JSON file that is provided by a plug-in. It is the point of contact between the authoring tool, the plug-in, and the course author who configures it.”

You can read more about it’s uses at https://github.com/adaptlearning/adapt_authoring/wiki/Properties-Schema

As we are only making a simple plugin our schema file will also be quite simple. In the adapt-helloWorld directory create the properties.schema file and add the following to it.

{
  "type":"object",
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "http://jsonschema.net",
  "$ref": "http://localhost/plugins/content/component/model.schema",
  "properties":{
    "_supportedLayout": {
      "type": "string",
      "required": true,
      "enum": ["full-width", "half-width", "both"],
      "default": "both",
      "editorOnly": true
    }
  }
}

The main section to note here is the properties _supportedLayout which includes the three options, inside the enum element, that Adapt uses to layout components.

We are now at the point where we can see our component in action. We will add our component to an existing block.

In your text editor open src/course/en/components.json

After the opening square bracket add

{
    "_id":"c-04",
    "_parentId":"b-05",
    "_type":"component",
    "_component":"helloWorld",
    "_classes":""
},

This will add the helloWorld component to the first block.

If we now run the build and server command again

grunt build
grunt server

And navigate to the Presentation Components page you will see a nice Hello World.

The plugin can also be used in the Adapt Authoring Tool. All we need to do is create a zip file of the adapt-helloWorld directory and then in the Authoring Tool navigate to Plugin Management there will be a green button in the left minute Upload Plugin.

That concludes the introduction to the building blocks of an Adapt plugin.

Adapt Authoring Tool Hello World Part 4: Adding assessment results

Now that we have a course setup and the user can answer some questions and get feedback we’ll add an assessment result to let them now how they did.

In the Adapt Authoring Tool go into our Hello World course and then choose Manage extensions from the left menu.

In the Manage extensions page click the green Add button to the right of Assessment. You should now have two enabled extensions

  1. Assessment
  2. Tutor

Now return to the Course structure and double click on the Take the test and say “Hello World” page.

In the article titled Hello World Test click the cog icon and choose Edit. Scroll down to the section titled Extensions and click on Assessment to expand it.

Update the fields with the following

Enabled: checked

Assessment Name: Hello World Assessment

Pass mark: 50

Show Feedback: checked

Show Marking: checked

Now click the green Save button in the left hand menu which will return us to the Page structure page.

Click Add article at the bottom of the main content area. Change the Article title to Assessment Results and also click the Unlink from title icon next to Display Title. Delete the contents of the Display Title field as we do not want it appearing for the users. Click the green Save button on the left hand menu.

Repeat these steps for the Assessment Block. After that your page should look like the following image.

Add a component to the Assessment block. From the list choose Assessment Results and Add full.

In the Assessment Results Component update the following fields

Title: Assessment Results

Set completion on: pass

Assessment Name: Hello World Assessment

Feedback Text:

{{{feedback}}}

You got a score {{{score}}} out of {{{maxScore}}}

The Feedback Text contains Handlebars syntax that outputs the feedback and a dynamic score that the user obtained.

Still in the Component edit settings we need to add three bands to determine the pass scores.

Under Bands click the blue Add button.

For the first band leave the score at 0 and set the Feedback to

You failed

Then click the blue Ok button

Add two more bands with the following settings

Score: 1
Feedback: You passed with half of the questions correct

Score: 2
Feedback: Well done you said Hello World

You should now have three bands as shown in the below image

Click the green Save button in the left hand menu.

Back on the Page Structure page click the green Preview course button in the left menu. Answer the two questions, try a combination of both correct, neither correct and only one correct and you will see the different fail or pass scores and feedback.

We have now completed a course using the Adapt Authoring Tool.

Adapt Authoring Tool Hello World Part 2: Course creation and introductory text

As I mentioned in the overview page I won’t be covering the installation of the Adapt Authoring Tool as the documentation covers it thoroughly.

With the Authoring Tool started navigate to the Dashboard which will probably be at http://localhost:5000 if you have followed the installation defaults.

If this is the first time starting it up the Dashboard will be blank.

Click the green Add new course button in the top left.

This takes you to the General settings for the course. Set the following values

Title

Hello World

Subtitle

Welcome to the Adapt Authoring Tool Hello World elearning course.

Body

Why are we saying Hello to the World?

Hello World! Is often the simplest tutorial when learning to create computer programs. Just because we’re using a Graphical User Interface (GUI) to create this course doesn’t mean we can’t stick with convention.

Everything else we will leave as the defaults.

Click the green Save button in the top left which will take you to the Course structure page.

On the Course structure page you will see a single page titled New Menu/Page Title. Click on the cog icon in the top left of the New Menu/Page Title box and select Edit.

Set the title to 

Take the test and say “Hello World”

Then click the green Save button in the top left.

We are now in a position to preview our course so far. Click the green Preview course button in the top left. This will open up a new tab with our course menu page.

In the next post we will look at adding some questions to our course.

Adapt Authoring Tool Hello World Part 1: Storyboard

Like most development that requires logic, whether this is created through code or a user interface, it’s best to have a plan of what you will be producing rather than diving in and ending up with a result that is hard to maintain.

Even though this elearning course is fairly simple we’ll create a storyboard to refer to throughout its creation.

For this I have used Pages and exported it as a PDF. You can download the PDF version and the other assets used in this tutorial as a zip file.

I’ve chosen to keep the storyboard simple here by just using a text document but if you have a Google there are a lot of very good storyboard authoring tools available.

Now we have a storyboard to follow the next post will cover creating the course with introductory text.

Adapt Authoring Tool Hello World

I’ve created a small series of blog posts showing how you can create a simple Adapt elearning course using the Adapt Authoring Tool. These posts assume you have already installed the Authoring Tool. If you have not then please follow the very comprehensive installation instructions.

To start off we will create a storyboard that will guide our development of the course.

Further posts will cover