Plugin Compatibility

Tom Taylor edited this page Sep 25, 2016 · 3 revisions
Clone this wiki locally

Introduction

This is a short guide to creating an plugin that is compatible with the Adapt authoring tool.

The tool supports component, extension, theme, and menu plugin types (although only components and extensions are currently configurable in the tool).

Developing a compatible plugin

The first step is to write the code (if this is your first time, it might be a good idea to follow our guide for creating a standard Adapt framework plugin).

To allow your plugin to be installed in the authoring tool, you need to take a few extra steps:

1. Update your bower.json

Make sure that you define the following two attributes are in your bower.json:

Name

You need to add a displayName attribute. This is the user-friendly name for your plugin as it will appear in the editor. Note that this value doesn't necessarily have to be unique, but may make the experience confusing for the end user if it matches the displayName of another plugin.

Type

The tool will need to know what type of plugin you have created (i.e. component, extension menu, or theme).

This is specified in the JSON using the type itself as the key, with your plugin's unique name (i.e. not its displayName) as the value. If you have registered your plugin using Adapt's CLI, this should be the value passed to Adapt.register.

For example:

"theme": "adapt-contrib-vanilla"

2. Add a properties.schema file

To allow your plugin to expose attributes to the user for editing, you must define those attributes in a json-schema file named properties.schema.

$ref

To allow your schema to inherit certain properties from pre-defined authoring tool schemas, make sure you set the $ref value to point to the correct schema for your plugin type:

  • Components: http://localhost/plugins/content/component/model.schema
  • Themes: http://localhost/plugins/content/theme/model.schema
  • Menus: http://localhost/plugins/content/menu/model.schema
  • Extensions: (not required)

Custom attributes

Besides the $ref, your properties.schema file is otherwise a standard json schema file which defines the attributes that will be added to the course JSON output and read by your plugin.

If you're new to properties.schema files, head over to our introductory wiki page for an overview.

See below for links to some examples of properties.schema files for core plugins:

Publish a specific version of your plugin

The authoring tool uses the Semver version syntax to determine the release order of plugins. Therefore, if you want to upload your plugin to the tool, it must have a valid version attribute in both the package.json and bower.json files (and preferably also a corresponding tag attached to your git repository -- GitHub have written some nice instructions on how to do this).

Updating your plugin

If you want to upload a new version of your plugin, you must make sure to bump the version number in the package.json and bower.json files, or the authoring tool will give you an error.