Ian Luckraft Web Development

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.