This is the first part of a series of tutorials on developing plugins for the Adapt Framework. In this part, we are going to take a look at a general overview of the Adapt Framework, how to set it up and how it all comes together.

Adapt is made up of two products: The Adapt Framework and the Adapt Authoring Tool. The Adapt Framework is a JSON-based, component framework for building responsive html courses. The Adapt Authoring Tool is a Node.js based tool for building Adapt Framework courses through a visual interface. For more information reference the Adapt Docs.

The Adapt Framework is made up of plugins that work together and fit into 4 different categories:

  • Components: These are small widgets that allow the user to engage with the material they are learning. Examples include: Text, Images, Multiple Choice Questions, etc.
  • Extensions: These add additional functionality outside of the core functionality that is provided through the Adapt Framework. This functionality are things like: Adding a course score, Assessments, Google Analytics, Using Local Browser Storage
  • Themes: This allows you to define a custom set of css or LESS styles. It also allows you to add custom assets, fonts, javascript and handlebar templates to define how your components feel and behave.
  • Menus: A menu plugin defines how a user can navigate through the course. These include: The traditional box menu, a single-page course with no menu, a carousel-style menu, even making different menus for different content sections.

Getting Started

Before you can develop plugins for use with the Adapt Framework or the Adapt Authoring Tool, you need to install the Adapt CLI. You’ll need Node.js/NPM already installed.

npm install adapt-cli -git

Once that Adapt CLI is installed, we can create our first course in our current directory:

adapt create course "Test Course"

You’ll need to confirm the type (course), the course name, and the git branch. Then your adapt course will be created.

After the course is finished creating, you can enter the directory: cd "Test Course"

To build the course, use: grunt build

To view the course, use: grunt server

Anytime you make changes to the course, you’ll need to rebuild and re-run the server.

You’ll see the default course theme with the box menu.

While we won’t be creating any new plugins in this lesson, when you want to change the theme or the menu used for this course, you can do so with the following command:

grunt build --theme=adapt-new-theme --menu=adapt-new-menu

The Anatomy of an Adapt Course

Within the adapt course source files Test Build/src/, the folders that we care about are:

  • components: Contains all adapt components for our course.
  • course: Contains all course configuration and content within JSON files.
  • extensions: Contains all adapt extensions for our course.
  • menu: Contains the adapt menu for our course.
  • theme: Contains the adapt theme for our course.

In future lessons, we’ll deal with the components, extensions, menu, and theme folders in future lessons. For this lesson, we’ll limit our focus to the course folder.

Config

Within the course folder, you’ll find a config.json file for course-wide settings. While you won’t need to edit many of the settings in here for developing plugins.

Languages

The folders inside of course folder are language-specific data for your course. For example, yours will probably contain a en folder for the english data and assets.

Course data

The course data file is a JSON file that allows you to define the title (the browser document title), the displayTitle (used in certain menus), as well as course-wide global content such as description, body, _buttons titles. There is also a _globals section for global strings that can be referenced from plugins such as a theme template file. In fact, all of the course.json is available as root level properties in the template file.

Content Objects

The content objects section is made up of page items and menu items. Menu itesm will take you to a sub-menu for further navigation. Page items will direct you to an article (which will be further defined in the next section).

Page Item

{
    "_id":"co-05",
    "_parentId":"course",
    "_type":"page",
    "_classes":"",
    "title":"Demo page",
    "body":"This page should contain a working Adapt page will all core bundled components and plugins working.",
    "graphic": {
        "alt": "alt text",
        "src": "course/en/images/origami-menu-one.jpg"
    },
    "linkText":"View"
}
{
    "_id":"co-10",
    "_parentId":"course",
    "_type":"menu",
    "_classes":"",
    "title":"Demo menu",
    "body":"This menu item contains a sub-menu",
    "graphic": {
        "alt": "alt text",
        "src": "course/en/images/origami-menu-one.jpg"
    },
    "linkText":"Go to submenu"
}

Content Object Attributes

  • _id The _id attribute of a content object will always start with the letters ‘co’ and a dash. It will be followed by a 2 digit number. The number should go from small to large based on the order that you want for the menu items.
  • _parentId is going to be course if you want it to be the root level of the menu or the _id of the menu content object that you want this object to be nested under.
  • _type will be either page or menu
  • title, body, graphic all are self documenting.
  • linkText contains the text for the link/button of the menu item.

Articles

An article is a grouping of related blocks. You are able to give the article a title and body text as well as add classes to the article to allow for changes in the theme depending on what article you are displaying.

You will define article items within the article.json file.

Article Item

{
    "_id":"a-50",
    "_parentId":"co-25",
    "_type":"article",
    "_classes":"",
    "title":"Article first title",
    "body":"Body text for article"
}

Article Attributes

  • _id The _id attribute of an article will always start with the letter ‘a’ and a dash. It will be followed by a 2 digit number. The number should go from small to large based on the order that you want for the article items.
  • _parentId The _parentId will be the _id of the Content Object that you wish do have the article displayed under.
  • _type will be article
  • _classes will be a string of css classes seperated by a space just like if you were adding them in a class="" html attribute
  • title, body will appear at the top of the article before any blocks are displayed.

Blocks

a note on layout and blocks: Blocks are at the center of Adapt Course Navigation. By default, blocks are arranged in what is called the Deep Scroll layout. This means that each block is arranged stacked below the last one creating a long scrollable page. You can also mark an article’s blocks as having Block Slider functionality, which means for that article, the blocks will become carousel-like in that you see one block at a time, and that the other blocks are offscreen either to the right or to the left, ready to be scrolled onscreen at the right time. Finally, you can make the entire page into the Block Slider layout, where you can transition to the left or right and journey through a horizontal lesson rather than a vertical lesson.

You will define block items within the blocks.json file.

Block Item

{
    "_id":"b-150",
    "_parentId":"a-50",
    "_type":"block",
    "_classes":"",
    "title":"Title of first block",
    "body":"Body text for block"
}

Article Attributes

  • _id The _id attribute of an block will always start with the letter ‘b’ and a dash. It will be followed by a 3 digit number. The number should go from small to large based on the order that you want for the block items. Often times you can find a way to associate the block number with it’s parent number.
  • _parentId The _parentId will be the _id of the Article that you wish do have the block displayed within.
  • _type will be block
  • _classes will be a string of css classes seperated by a space just like if you were adding them in a class="" html attribute
  • title, body will appear at the top of the block before any components are displayed.

Components

A component is an individualized piece of functionality. You can have 1-2 components in a block. If you have 1 component it be be full-size or half-size. If you have 2 components in the same block, they both must be half-size. If a component is half-size you define whether it is the left component or the right component. As per standard responsive design rules, when the block is displayed on a mobile device, it stacks the components on top of each other, the left component on the top of the right component.

Components are the baseline of Adapt. They can be as simple as a text section or as complex as a mini-quiz or a game (like we developed for Google, GG-04). You’ll noice that a component is considered a plugin, but an article and a block are not. That is because to really change the behavior of an article or a block you need to use an extension or a theme.

Component Item

Here is a basic component JSON: { "_id":"c-200", "_parentId":"b-150", "_type":"component", "_component":"text", "_classes":"", "_layout":"left", "title":"Title of our very first component", "body":"Whoo - if we get this rendering we've made the big time" }

Component Attributes

  • _id The _id attribute of a component will always start with the letter ‘c’ and a dash. It will be followed by a 3 digit number. The number should go from small to large based on the order that you want for the component items. Often times you can find a way to associate the component number with it’s parent number.
  • _parentId The _parentId will be the _id of the Block that you wish do have the block displayed within.
  • _type will be component
  • _component will be the type of component that this JSON represents.
  • _layout will either be left, right, or full.
  • _classes will be a string of css classes seperated by a space just like if you were adding them in a class="" html attribute
  • title, body will appear at the top of the component.

The Complexity of Component JSON

Okay, now forget everything you just learned about component JSON! Well not the whole thing, but it’s definitely a bit trickier.

The component attributes above are actually the base attributes, however every custom component actually has it’s own attributes added and defined, so depending on what component is listed in the _component attribute, you’ll want to add or remove new attributes. Because of this, when developing a component plugin authors are supposed to include an example.json file. This file is for you to be able to look at it and understand what attributes you have to add for this component to work. To further explain this, I have included links to some different component’s example.json files:

From Here On…

So now you have a basic understanding of how the Adapt Framework builds courses. This is needed so that you can create components, extensions, themes and menus that are good citizens within the adapt community. The next lesson will be on Building a Custom Component.