Adapt Learning Community: Component Development

Hi there

I am having a go at developing a custom component and as recommended on the forum, I have taken an existing component (mcq) to use as a starting point.

I have a basic understanding of Backbone/Underscore/Handlebars so kind of hope to improve on this as I proceed.

I want to try and get a better understanding of some of the basic elements as follows:

The mcq has a less file with a filename "mcq.less" in a "less" folder.

Can I confirm the less file needs to be in a folder titled "less" and that the less file needs to have the same prefix as the "component" property in the bower.json file?

Similarly, the mcq has a handlebars file with a filename "mcq.hbs" in a "templates" folder.

Can I confirm the handlebars file needs to be in a folder titled "templates" and that the handlebars file need to have the same prefix as the "component" property in the bower.json file?

Essentially it would appear Adapt automatically picks up on the less and hbs files if they are in the correct folders and have the correct filenames. I have seen some components that have more than one file in the less and templates folders - I am assuming in this scenario, there needs to be a reference to these additional .less and .hbs files somewhere?

Can you explain what the following element is in the handlebars file?

I have seen the following wiki page but it didn't make it clear what this element does.

https://github.com/adaptlearning/adapt_framework/wiki/Developing-plugins

If there is any additional info on developing plugins that you can point me to it would be really appreciated.

Thanks

Paul

Hi Paul,

I am not an expert, but may be I can answer some of your questions. The first thing you have to keep in mind is, that there are two kinds of components: Presentation components (which extends ComponentView) and question components (which extends QuestionView). I would highly recommend to start with the first, because they are much easier to code. I suggest to have a look at the adapt-contrib-text component as a starting point.

The file- and folder-structure mentioned in the wiki-page is expected by grunt (the build tool of ADAPT) and should not be changed. Essentially a component needs 3 files (as far as I know):

~/js/adapt-mycomponent.js (-> linked in bower.json!)
~/less/mycomponent.less
~/templates/mycomponent.hbs

The {{> component this}} in the *.hbs-file is a hendlebar partial (https://handlebarsjs.com/guide/partials.html). It is responsible for the output of the "standard content" (Title, body-text etc) which all components have in common and are defined in components.json.

Unfortunately, documentation is quite sparse and some things are outdated. Perhaps these links could help:

- https://github.com/adaptlearning/adapt_framework/wiki/Developers-guide:-components

- https://github.com/adaptlearning/adapt_framework/wiki/Adapt-v5

- important: https://github.com/adaptlearning/adapt_framework/wiki/Adapt-v5

Good luck!

Show parent | Reply

As we're now moving to use ES6+ it might be a good idea to have a look at the pull requests that show the conversion to that syntax.

ES6 Text component: https://github.com/adaptlearning/adapt-contrib-text/pull/56/files

ES6 Accordion component: https://github.com/adaptlearning/adapt-contrib-accordion/pull/96/files

FYI the handlebars file can be named anything you like. Adapt assumes you want it to have the same name as the component so if you want to use something different you'll need to use the template property to tell it the name you actually want to use.

I'd echo what Rainer says about components - the easiest to start with are ones like blank, text & graphic. Then you've got the interactive presentation components like narrative, hot graphic and accordion that all handle a collection of items the learner can move through. Then there's the media component which is a bit of an odd beast - it uses a third party library (mediaelementjs) which was needed back when we still supported IE8 as it had good support for non-HTML5 video via Flash/Silverlight. Now it's showing its age a bit and really needs to be replaced with something that doesn't require 3rd party code.

As Adapt started out quite early on (React had only just come out around that time) there's a fair bit in there that looks quite old/clunky/weird. We're very much aware of this and slowly trying to sort that out. Which goes some way towards explaining why the documentation's a bit lacking (also we're just rubbish at doing documentation).

Show parent | Reply

Thank you Matt - that is reassuring to hear you back up Rainer.

Oh my I need to get up to speed with ES6 too by the sounds of things. The links you sent will be really useful. If you have any other documentation on this conversion process please let me know.

That is really interesting to know about the template file name though I see no reason to need to change it from the same name as the component for now.

I am really impressed with what I have seen of this tool already and you guys have proven it has a very active community too. Thank you.

Show parent | Reply

Oh my I need to get up to speed with ES6 too by the sounds of things

It's certainly worth getting up to speed with some of the basics because we're going to be using it more and more. I would say the key things to look at initially are (in what I think is order of importance as regards working with Adapt):

using let and const instead of var
Arrow functions AKA function expressions
Template strings
Classes
Default parameters
Rest parameters
Spread syntax
async/await
modules (we're still using AMD but will be shifting over to ES6 style probably in the next release)
destructuring assignment

It's also highly likely we'll be starting to use React within Adapt, so worth reading up about that framework too if you have a bit of spare time!

Show parent | Reply

You are spoiling me Matt - thank you for all this help getting me up and running.

I have lots to read and learn. I think I came across those arrow functions before recently and found the syntax really weird. Guess I will get used to it.

So with your next release, does that mean any custom plugins would need to be rewritten in ES6 to enable them to work in this next release?

React is definitely more up to date that Backbone - shame as I had spent some time looking at Vue but I am sure the principles are fairly similar. I hope!

Show parent | Reply

So with your next release, does that mean any custom plugins would need to be rewritten in ES6 to enable them to work in this next release?

Not at all. We made quite a breaking change in Adapt v5 and we really want to avoid having to do so again! So even when we switch from AMD modules to ES6 ones, we'll still allow for AMD modules so that we don't break compatibility with 3rd party plugins.

(because we have to support IE11, all the code gets 'transpiled' down to ES5 anyway... so ES6 is really there just to be used when it makes for neater code)

Show parent | Reply

Essentially a component needs 3 files (as far as I know)

Strictly speaking, your component doesn't need to have a .less file. The Blank component doesn't have one.

Show parent | Reply

Thanks Matt. I will take a look at the blank component - it sounds like a really good one to give me an example of a bare minimum component.

Show parent | Reply

Thank you very much Rainer - your reply has been really really helpful.

Doh yes of course that makes sense now that it is a partial. I have used these a lot in Umbraco so should have known.

The documentation does seem a bit hit and miss but I understand developers would much rather write code than write documentation:)

That is a great suggestion to try a presentation component first though I have just got a bare bones Question Component working.

I stripped everything out then was stuck for ages as even though the plugin loaded fine in the authoring tool, I was getting the page loading screen not disappearing. I realised after a lot of head scratching I needed to add this.setReadyStatus(); in my onQuestionRendered function.

It does make sense to dumb things down a bit and try a simple presentation component as I imagine the Question component is a lot more complex.

Thank you for the reply.

Paul

Show parent | Reply

I'd also recommend you do the majority of your initial development in the Framework as the find-issue-debug-fix cycle is a lot quicker. Once you've got it working in the Framework as well as you can then try it in the authoring tool.

Show parent | Reply

Ah OK that sounds sensible. I did manage to install the authoring tool without any problem but I hear what you are saying. I feel like I have changed the version number about a million times today and re-uploaded my test plugin to the authoring tool. At least if I now know I can get a plugin into the authoring tool so I will feel more confident when I finish developing a plugin.

Show parent | Reply

I feel like I have changed the version number about a million times today and re-uploaded my test plugin to the authoring tool.

And that's one of the many reasons why it's so much easier developing in the FW first!

Show parent | Reply

adapt-question-component.pdf

You're welcome!

I've made almost the same mistakes you did. And coding for framework only and for ATT are not equivalent skills (things work slightly different). As Matt says, I would start with the framework.

For your convenience I added a cheat sheet I've made for myself that illustrates the basic functions and workflow of a question-component. Pay attention, that the functions are spread over the model- and the view-files, respectively. Please be aware, that I am not shure, if it is complete, but it served me well. May be its useful.

Show parent | Reply

Thank you very much Rainer. I am just getting things set up to develop on the framework. I am sure once I get the workflow sorted it will be much simpler.

That PDF looks really useful - things like this would be great to have on the WIKI pages.

Many thanks

Paul

Show parent | Reply