Adapt Learning Community: Folder structure parser...

I had an idea to maybe have something thats a little monolithic and seperate out the structure using folders with json objects and html stubs nested as they are related and then having a grunt (or perhaps gulp for speed) run over them and build the main json objects as a pre-build step.

Easier to edit the HTML bits...

This would mean i can see unfolded HTML which is what you inject into the handlebar templates, all i'd need to do really is just pipe minified html from that file into the JSON stub, inject in parent id (ergo folder names) then append that stub to the JSON file it belongs to.

Disclaimer

Speed might be the only thing, but i think gulp will probably help a lot there (grunt-gulp task is pretty good). It should fit neatly into before the testing tasks which check the JSON validity.

First Steps

I'll try it out in the demo git first, see if it works at all, if so i'll share and at least some people might like it as an alternative. Probably next week some time.

Seeing it is probably understanding i guess...

I forked and branched the idea here. Let me know if anyone things this is a good or bad idea themselves ;)

https://github.com/KevCJones/adapt_framework/tree/structure

Notes

I've converted the demo content as it was into a folder (withing course/en) called structure aka hence the branch name...

Folders have a naming convention prefix :

co - contentObject
a - article
b - block
c - component

Every folder will contain a single json file which relates the the object itself, this json file is combined on build into the respective JSON.

The folder name dictates the id of the json object which goes inside it. (Auto done on build)

The parent folder will be the parentID of the object (Auto done on build - will walk folder structure if you've subfoldered e.g. html-stubs/ would be ignored and it would walk up the chain to something with a recognised prefix)

This does mean you can give json and html stubs more meaningful names to make the navigation of folders easier (in the readability sense)

I think it also makes it nice in that if you want readable folder names, you can have those too, just making sure your folders order correctly, there is nothing stopping you from adding more meta to the end of the folder name e.g. article-1-intro-to-topic, and this would become the id used in the JSON files it generates.

Finally the reason i did this to begin with, easier to edit HTML text in the JSON files was a little clumsy for my tastes so....

I've also created a notation for injecting text content e.g. HTML text into any JSON value attribute, which is an optional way to keep your text in a seperate file next to the json object, this could be handy if its :

long
heavily styled e.g. html tag hell
needs someone more designer-minded to edit markup but leave json alone
translations/localising large body

One new bonus with all of this was the ease of restructuring, i just copy folders and to new locations e.g. move a block to another article can be done via folders not via searching for ID's in a long file... i like that anyway ;)

As said, feedback welcome. Can pull req this back in should people see value in it, just let me know. Its still a ways though from being tested fully, i'm sure it could be broke with something nasty like comments in HTML or the likes...

NB - if you get a [bad] Karma npm install, a temp fix is to just delete the karma folder in node_modules and run npm install karma again from root. It will fix it... not sure why.

Show parent | Reply

The buzz is just palpable ;-) but i don't mind haha, its for me and my team but it doesn't hurt me to share.

For those of you who want to try it out but NOT have to manually install it via git, i have made a fork of the CLI which you can install over your current one.

To install adapt-cli that builds my own forked version :

npm install git+https://github.com/KevCJones/adapt-cli.git -g

Nothing changed except the URL of the repo it uses...

adapt create "myCourseName"

will generate you a course which has my structure folder in the course/en folder using the seperated building blocks stuff above. To uninstall/undo just run this, it will remove mine and put back the original.

npm uninstall adapt-cli -g && npm install adapt-cli -g

Show parent | Reply

Hi Kevin,

thank you for sharing and apologies for not responding sooner. We're quite excited by the work you have done but haven't had enough time to review it properly yet, I'm afraid. We'll respond from the core team as soon as we've had a chance to try the code out.

In the meantime, thank you again for sharing your work here. It's very much appreciated!

Sven

Show parent | Reply

Hi Kevin,

we've taken the time to have a proper look and think it's a very useful addition for 'folder readability', as you say. I also thought your explanation and documentation on this thread is great.

We won't be able to incorporate it into core, I'm afraid, as the way it works conflicts with how we are building the authoring tool. It's a useful addition regardless and think the best way to provide it is as a fork via your Github account.

Thanks again for sharing and offering the code back!

Sven

Show parent | Reply

Thanks Sven, glad you liked. I sort of knew what i was doing had little chance to be compatible with your authoring tool. I guess for me, it was just an interim option while i wait to see that released.

I was also doing it as a way to learn as i go ;)

Show parent | Reply

Cheers, Kevin. You building and sharing things is very encouraging for us, too, so please keep 'em coming :-)

All the best,
Sven

Show parent | Reply

Hi Kevin,

This looks really cool. Here Sponge UK we are looking at ways that we could integrating this into our production system.

Also, You can set the environment variable ADAPT_FRAMEWORK to 'https://github.com/KevCJones/adapt_framework' to get adapt-cli to use your fork instead of the default.

Keep up the good work, man.

Chris

Show parent | Reply

Hey Chris,

Aaaah i saw the reference to ADAPT_FRAMEWORK environment variable but thought it was referring to something in adapt i hadn't learnt yet, didn't realise it was referring to the system level ones. Cheers, good to know.

It's good to know it's already 'possibly useful' to someone else.

Show parent | Reply