Adapt Learning Community: JSON data to and from Adapt

Hey,

We've (Dennis, Rob and myself) been having some discussions around JSON structure and how Adapt should load and manage the data for the course. We've come across three ways of doing this and would like to discuss these with the wider community. All three result in the same models and collections so this is more about how Adapt loads the data and how the data is split up into files. (What I mean by this is: models will still have direct access to their children and parent, also each model will be pushed to its corresponding collection e.g. an article model will still be placed into a collection of articles).

The first thing to clear up is the concept of menus. Currently, and this is only setup this way because of our in-house approach to building courses, we have "Modules", "Topics" and "Pages" as a menu tree structure. (See attached menus.pdf for a rough diagram). As a user who isn't familiar with custom routers or making the router navigate to another place because they would like the course to go to a page and not to a menu of modules, we've realised that our current setup doesn't work.

This can be solved by not naming menu items ("modules", "topics" etc) and by simply having a collection of menuItems that are based on hierarchy through their parentId and their children. This would then mean that users can navigate based upon their content and not a set menu structure enforced by Adapt. Example of this is when you reach a topics menu and one topic goes to a list of pages and another goes straight to a page - Custom code is needed to build this.

How does this affect the course.json file?

Well, it would mean that we don't put the menu items in the course.json file. Instead they live in their own menu.json or structure.json (which is something used in our Flash framework). This then allows the menu data to be sortable and abstracted away from preset structure.

So what about the main course.json?

In theory we would be left with articles, blocks and components as pages would be menu items.

This is where we have three options (I say three...one doesn't really work and I'll explain later).

Approach 1: Keep remaining data in a nested tree structure like course.json currently sits

Approach 2: Move all three object types into seperate json files, this would leave us with articles.json, blocks.json and components.json.

Approach 3: Bootstrap data into Adapt.

Approach 3 doesn't really work as it's harder to swap out data per languages, pushing this type of file out of an editor that could potentially be working in JSON format seems like an unnecessary step and if we were to use this data somewhere else, bootstrapped is normal in JS form so the data layer is removed and can't be reused. The term bootstrapping is meant to allow access to data on page load - we do not need this functionality, so we would only be adding complexity where it's not required.

So let's look at Approach 1 and 2 more closely.

Approach 1 - pros:

- One http request.
- Easy to create child collections.
- Already has tree structure of course from article level down.
- Overall - Advantages at init.

Approach 2 - pros:

- Easy to drop into collections. Native loading of an object into a collection means less parsing.
- Although there's more http requests, they are simple get requests that can all happen at the same time.
- Easier to store in ADAPT for security as Adapt would take care of Data stores and not the models distributing them to collections.
- Easier to pull out of a BSON/JSON based document database.

My initial thought when re-architecting the framework, I thought I would keep it the same tree structure. But from discussions and realising that menu items are objects and not a set tree structure I started to think about smaller JSON files. Not only is there less scope to mess up the JSON files from the editor, it's actually easier to get this data out of a document based database.

Also from discussions with Ryan, smaller separate JSON files could be used else where. (I'm thinking a mobile app could take just the components and display them without the need for all the other nested data). If we have a structured tree JSON we're tied into using that content in it's current form.

I also spoke with Kev, another developer at Kineo about our Flash framework and how that takes in data. Although the layout and nested structure is slightly different as we have articles, blocks and components, the data is pulled in as collections of screens. Which would be collections of components in Adapt terms. Each topic (Adapt's "page") has it's own data file - similar to having separate json files.

So here's the information and research - please discuss and by all means add more pros and cons to the list.

Thanks,

Daryl

Hi all.

Thanks for raising this Daryl; loads of interesting points to discuss.

With regard to our Flash framework, essentially the way that it works is that the framework displays the first bit of content which has "sibling" bits of content.

To use Adapt's terminology: if there was only one page in a course, upon navigating to the course, Adapt would display that page. The page's articles are the siblings.

If there were two pages in a course, Adapt would display a menu containing those two pages as clickable items. The pages themselves are the siblings.

If there were multiple topics, each with one or more pages, Adapt would display a menu of topics. The topics are the siblings. Clicking a topic would either take you to the page (if that topic only had one page) or a menu or pages (if that topic has multiple pages).

I think this approach is very flexible, as it allows an infinite number of nested layers (I'm sure learning design would have something to say about that!), but will show you the most relevant content, never asking the user to select a content item if that is the only item there is. It'd be great if Adapt could do something similar, meaning, as Daryl suggests above, the author of the content need only specify the structure of the course in a separate file, and the framework can take care of whether to display a menu, a content item, or whatever.

Cheers,

Kev

Show parent | Reply

Hi Daryl,Great write-up. Summarises the issues nicely.

From the point of view of the editor, Approach 2. works really well - it simplifies the authoring tool export process, and I really think the separation of navigation items from content items is an important change to make.

Approach 1. is nice from some perspectives, but feels a little like putting all your eggs in one basket.

I'm eager to see how both 1 and 2 work in less than ideal conditions, though - say with poor network connectivity on the client end, or heavy server load and also on devices with a not-so-great javascript implementation. I don't expect there'll be any real difference between the two, but it's always nice to have some data.

Cheers,

Dennis

Show parent | Reply

I can explain a bit about how we manage this in our mobile app json formats. I'm afraid I'm busy today, but will try to put it up tomorrow.

In the meantime, could you explain what you mean by "Bootstrap data into Adapt." I don't understand that option.

Show parent | Reply

Bootstrapping would mean putting the data into the course. This could either be done as a javascript file or put into the HTML file in a script tag.

The reason why I wrote this approach off is the data needs to be interchangeable based upon language selection and also this data is then wedded to Adapt and not useable as a data format.

I'd really like to hear how you're doing this for a mobile approach, may help us decide. I'm currently in the process of creating two demos using approach 1 and approach 2, which I will test and post back the results.

Thanks,

Daryl

Show parent | Reply

Another possible pro for option 2 is locking and completion might be easier to manage. I tihnk there will always have to be a relationship between the nav and the content as each referenced page in the nav will have to be uniquely addressable in the content.

The page might also have to contain information about where it sits in the nav structure, so when I finish the page what menu do I show and so on.

Overall I think option 2 leaves the main content json file cleaner and easier to read, with the nav nesting complexity separated out

In the example included, the first row would have 6 level 1 links
The second example would have 3 links at level 1, 3 links at level 2 and 2 links at level 3

Im not sure how instructional design people would like this as you could technically have individual and grouped pages on the same level.

Show parent | Reply

Hi Mark,

If I understand the diagram correctly then I think in the vast majority of instances ID's would be fine with what is proposed.

That said, for instances where you have the single page sitting at the same level as the grouped pages an option for a landing page would be great. Allows us to create the impression of a hierarchy even when one isn't there. From my discussions with Daryl this would seem quite a simple undertaking.

Cheers,

Paul

Show parent | Reply

for our mobile apps we split all content up into screens (which i guess matches to pages in adapt - we avoided pages as the word page is loaded with different meanings). Each screen contains all the relevant content elements required to render itself.

The app's navigation is a separate file which is simply a list of "screens" in an order - essentially a course outline. A screen need not appear in a course outline, and if that happens then it will typically appear as a "modal" view (the slide-up view used in iPhone apps).

There are various screen types, we've defined I think 15, of which navigation is one. We've also defined a section index screen which allows us to create sub-indexes (or menus if you like).

The beauty of this approach is that a screen can appear in several locations in the navigation, or can be referenced from several screens giving us flexibility in how the flow through the app works.

We also have a manifest file which defines what is the navigation json file and what is the first screen to load (so I can if I want jump straight to a content screen rather than a homescreen type page)

So relating that to your proposed structure, I think that would suggest that each page in course.json was a separate file (or object actually, as I suspect for adapt in its current architecture minimising the content json files loaded over the network is advantageous).

Modules, Topics and Pages are essentially instances of the sub-index content type (and we could define multiple types to suit multiple navigational approaches), and course.json would require a field which allows us to define the start page (which could be a module, topic, page or article).

With regards the second half of the post, I think there's a little bit of conflation between authoring and publishing and between files and objects. Since we're going to be processing the content from the authoring environment when we publish it to the viewing environment we can essentially do whatever is best for performance. That means that we can bootstrap the content if we like (with a switch built in for language if necessary), or we can have it as one file (for minimising http requests) or as multiple files or indeed a mixture of all three - bootstrap for speed of access but provide a course.json if plugins require it.

Show parent | Reply

Hey Ryan,

Our "pages" (which I totally agree should change) consist of multiple articles, blocks and components. From your discussion above it seems as though you have one interactive component per screen?

I have already started to implement the changes to Modules, Topics and Pages and are now ContentObjects. These will be structured based upon who their parent is and who their children are.

Thanks,

Daryl

Show parent | Reply

Yes, that's true, at present we only have one interactive element per screen, so I think that makes our "screens" map more closely to your "articles" - in that they encompass one learning "thought" (as I imagine it).

There's no reason why a screen couldn't contain multiple interactives though...

/me wanders off to mis-use some "more" quotes.

Show parent | Reply

Hi,

just chucking in my two pennies worth about the philosophy behind Adapt from a content structure perspective.

The plan was to organise content into chunks which were as big or as small as the subject demanded. Navigation therefore becomes a meaningful event for the learner rather than as an event which is required because the ID has run out of room.

This obviously needs to be balanced with the risk of bombarding learners with too much information and achieving the same failings with the click next model - no mental representation of the relationship between content.

Interestingly we've failed in applying this in most instances and designers have whacked entire topics onto a page.

One of the thoughts you mention could be one of our chunks - typically 3 or 4 blocks with perhaps between 5 and 7 components. This would tick all the ID boxes around memory and cognitive load.

Show parent | Reply

Yes, I also think of those chunks as learning journeys (because that's what we called them in the last place). You'd expect to complete one of those in one sitting, or to have an opportunity to reflect at the end of it before jumping into the next piece. Which works very well on a mobile device because you might do only that journey/chunk/thought then go do something else, coming back to the app the next day to continue.

Show parent | Reply

Agreed. Bite-sized sequences (perhaps 5 minutes or so in length) that deal with one key idea, principle etc that correlates to one of the learning objectives and which can standalone, but which can also be structured in a variety of ways to build larger sequences of learning.

Show parent | Reply