Eddie Hinkle

Learning Adapt, Part One: Introduction to the Adapt Framework

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:

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.

  1. npm install adapt-cli -git

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

  1. 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:

  1. cd "Test Course"

To build the course, use:

  1. grunt build

To view the course, use:

  1. 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:

  1. 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:

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.


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.


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

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

Content Object Attributes


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

  1. {
  2. "_id":"a-50",
  3. "_parentId":"co-25",
  4. "_type":"article",
  5. "_classes":"",
  6. "title":"Article first title",
  7. "body":"Body text for article"
  8. }

Article Attributes


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

  1. {
  2. "_id":"b-150",
  3. "_parentId":"a-50",
  4. "_type":"block",
  5. "_classes":"",
  6. "title":"Title of first block",
  7. "body":"Body text for block"
  8. }

Article Attributes


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:

  1. {
  2. "_id":"c-200",
  3. "_parentId":"b-150",
  4. "_type":"component",
  5. "_component":"text",
  6. "_classes":"",
  7. "_layout":"left",
  8. "title":"Title of our very first component",
  9. "body":"Whoo - if we get this rendering we've made the big time"
  10. }

Component Attributes

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.

posted using quill.p3k.io


Please note: This site is in an active redesign. Some things might be a little off 🧐