GSoC 2018: Interactive Demo Apps: Behind the Scenes & Under the Hood
How do you do (the things that you do)?
What a great question. Since you’re so eager to find out, today I will let you in on a secret.
Demo apps
Previously on my Google Summer of Code journey, I built a few demo apps for part 1 of the OOUI tutorial, which teaches the basics of working with an internal tool, developed and used by Wikimedia for its various projects. The demo apps are interactive. They accompany the user when building the tutorial app, demonstrating different stages of its development.
In part 2, more advanced functionality is introduced. I expected the part 2 demo apps to be more complex and a bit more challenging to build, being based on more than one JavaScript file this time. I didn’t actually have to keep that separation behind the scenes, but I chose to, because it looked like a good way to maintain readability. It also really payed off in the end, because I ended up using inheritance.
All in all, revamping and editing part 2 of the OOUI ToDo App tutorial didn’t take long, probably because I did all the ground work in advance when I was working on part 1 — things like setting up syntax highlighting for code snippets, creating CSS layout for a basic tutorial page and for demo ToDo apps, and choosing how to embed my demo apps. So yeah, I expected the interactive demo apps themselves to be the challenging part, but even that went pretty smoothly.
Note that the whole thing is quite meta: building interactive demo apps for tutorials for a library, using that same library. Also in the works: write a tutorial on how to add a new tutorial.
Of course, it’s not really that weird. The true weirdness lies behind the scenes, or under the hood, or wherever you hide stuff. Because the code that the tutorial user is instructed to write is actually not exactly the same as the live demo code — it’s very similar, but it’s divided into more parts.
In the tutorial, the user is asked to create an init.js file and one class, a ToDoItemWidget.js file. Towards the end, they are asked to add another class, ToDoListWidget.js. The tutorial itself includes 4–5 interactive demo apps, that demonstrate different stages of the app’s functionality and appearance. The user/learner is instructed to update those files as coding progresses. Behind the scenes, though, the demos are built in a different way. The files for each demo app are comprised of the code that’s been added at that stage only.
Demo #1 shows a small change that has to do with allocating space for displaying information about ToDo items. After that, ToDoItemWidget.js is added to the project. You can see its first version in the code snippet below. This new class, or widget, is currently empty. It inherits from (or: is based on) the built-in OOUI OptionWidget class. This is the very basic OOUI widget construct:
Next in the tutorial, the user is asked to modify this class and extend its functionality. For each change in the class, there is an interactive demo that illustrates its appearance and behavior. I would like to walk you through the way I implemented those modification, and talk about how that code differs from the code that the user is instructed to write.
So let’s see. Demo #2 is when we first include the ToDoItemWidget in a demo app. However, we’ll number it ToDoItemWidget2, to match the demo app’s number and the rest of the demo #2 files. This version includes functionality for showing when each ToDo Item was created. I omitted some code — it’s just some manipulations for formatting date and time, that were needed because JavaScript is not very good at that kind of stuff.
At this point, the demo app code and the tutorial code are still the same, except for the class name, which is ToDoItemWidget2 in Demo #2 files (behind the scenes).
But the next time the user is asked to add code to their ToDoItemWidget.js file, the behind the scenes code is significantly different. The user will edit the file we just saw and add in some new functionality.
Behind the scenes, however, the new code is written in a brand new file, named ToDoItemWidget3.js, which inherits the previous version, ToDoItemWidget2.js.
The inheritance is declared and implemented in line 14 in the code snippet below. As you can see in the new class below, there’s less code in it, compared to the previous one, and yet it can do more, since it includes the long (censored) time formatting function without ever needing to repeat it.
And it goes on this way in the next versions. Demo #3 adds in a ‘Delete’ button and Demo #4 styles it, positioning it to the right. And just like in stages #2 and #3, clicking an item makes its creation time appear in the info bar at the bottom. Demo #5 implements the actual delete event. Since Demo #4 and #5 look the same, I will just show you one of them:
What now?
Now I have a working MVP for this project, which is pretty cool, considering I just recently started working on it. As the project awaits review from OOUI team members, I’m making plans for additional features and enhancements, including:
- Add a dropdown menu to the top bar
- Make the page footer responsive
- Add support for dynamic loading of tutorials
With only two weeks left to go, I really I hope to have enough time to add those in. In any case, I would love to continue developing and supporting this project after the GSoC program ends.
And I know the next post is going to be the last, but I hope to keep on blogging, just sort of blog off into the sunset. I was thinking of writing tutorials for my own side projects, for one.
But that’s for another time.
