Programming tips: Writing code in Storyline for eLearning

There is always a time in our development phase where we need to add some extra fancy elements or interactions to our eLearning projects. Even though Storyline usually provides us with all the tools we need to produce our eLearning modules, sometimes it falls short on some of the things we want to do and then, we need to make use of other software, such as Adobe Flash.

However, and unfortunately for non-programming people, communication between those external tools and Storyline is not as straight forward as we would like it to be.

On the other hand, Storyline offers an API (Application Programming Interface) to help us while integrating interactions made on other software into our modules. This API consists of a group of Javascript functions that will let us retrieve and modify objects, usually Storyline variables.

I am aware that thinking about coding something in Javascript (or any other programming language) may be scary for some people, but I like to believe that regardless of the language, we can all code something, given that one of the most important things is logic, and as far as I am concerned, all human beings are logical, too.

In this article, I describe several tips that may help you use the Storyline API and even, introduce you to the coding world.

Avoid writing code whenever possible

As much as I love programming, I also love to avoid it when it is not necessary. It may sound contradictory, but before jumping into writing code and scratch your head for hours, make sure you have a legitimate reason to do it.

Usually, when you have to develop a module in Storyline, you have a reference, like a script or a storyboard describing all the interactions on screen (If you don’t have this, I strongly recommend you create a storyboard before developing a module), evaluate them and figure out if what you have to do is possible through the tools offered by Storyline.

There is a specific situation that I have experienced, in which I definitely use the Javascript API to enable my interaction, and this is, adding a button on the player to show a layer with closed captions when there is audio present.

Understanding the API

If you have decided to use Javascript on your project because you deem it necessary, or, well, because you want to try it, you need to understand how the API works, or at least have an overview of the things you can accomplish with it.

As I mentioned before, the API is a group of functions (provided by Storyline when you publish your module) that you can use to modify objects within the project, i.e variables. Yes, you can modify the value of variables using Javascript and (Spoiler alert) you can have triggers of actions happening when the value of those variables changes.

On the picture above, we can see a simplified version of how the API works. First, your Javascript code, will ask the API to retrieve the value of a specific variable from the Storyline module. Then, when that value becomes available to your code, you can modify it, changing its value to a different one or even making math operations if your variable is a number. Remember that Storyline works with 3 types of variables: Text, numbers and Booleans (true or false).

Once you have done everything you needed with that value, you can post or submit your results to the same or another variable that matches the type of your new value. To do that, you just ask the API to send that value to a specific variable within your Storyline module.

Creating the Javascript code

Now it’s time to actually write the Javascript code within Storyline to execute the desire actions.

Let’s say you have a layer that will show up when you click a button on the player (Like the resources button you can add). When you create this button on the player window, you have fewer options under the “Action” drop down menu as if you were creating an object directly on one slide. One of the options is to “Execute Javascript”. Once you create the action, you can edit the Javascript code linked to this button on a pop-up window that looks like a notepad.

The advantage of the API is that it is available right away when you create the action, meaning that you don’t have to “include” or “import” any programming libraries, like you would do with ActionScript 3 or C#, for example.

Let’s also say, that you have already setup a variable that will toggle the visibility of your layer, and it is called “myToggle” and it is a Boolean variable with a False value by default. The idea is that the layer becomes visible when myToggle changes to True and hides again when it changes to False (This is the logic you would use to create the triggers on the slide).

The first thing you have to do, is to make sure the variables are accessible from your Javascript code, and this is done by adding the following line of code:

var player = GetPlayer();

This line of code is simply creating a temporary variable that will retrieve and store all the functions that will help you modify variables within Storyline.

You can change a variable’s value by using the following line of code, if it’s a text:

player.SetVar(“myVariable”, “Lorem Ipsum”);

or if it’s a number:

player.SetVar(“myVariable”, 25);

The sintax of the “SetVar” function is very simple, the first parameter refers to the variable you created in Storyline and that you want to modify (This parameter should always be inside quotation marks), and the second parameter is the actual value you want to assign to that variable; if it is a text, the text should always be inside quotation marks, otherwise, if it’s a number or a Boolean, the quotation marks are discarded.

However, in the example we are following to create the Javascript code, we can’t really assign a value right away, since we first want to know if myToggle is true or false (if the layer is visible or not). To achieve this, we can use the following code to know the current value of myToggle:

var toggleValue = player.GetVar(“myToggle”);

The sintax of the “GetVar” function is even simpler than the “SetVar” function, it only needs one paremeter and it is the name of the variable you want to retrieve, always using quotation marks, and it is assigned to a temporary variable created in our Javascript code because, well, since we are retrieving a value, we need to store it somewhere.

Please note that this function, retrieves the value of the specified variable and not the variable itself, meaning that whatever we do with this value, doesn’t necessarily affect the variable within Storyline, unless we tell the API to do so (which is done with the “SetVar” function).

Now that we have the current value of myToggle, we can decide whether to change it to False or to True. We could use a conditional here, but in my experience it doesn’t work as well as the following code:

toggleValue = !toggleValue;

Wow, the previous line of code looks a bit scary, doesn’t it? Let me explain it (or a least try) so that it is clearer.

Since the value we just retrieved is a Boolean, meaning that we have either True or False, we can apply something called Boolean Operators, and in this case in particular, the exclamation mark preceding “toggleValue” is a negation of the value stored within that variable. This negation, simply changes the value between True or False depending on the current value, so if you say that something is NOT False, then it is true, and if something is NOT True, then it is false.

Looking at the line of code, without the name of the variable on the second half of the equation, and assuming that the current value is False, we would see something like this:

toggleValue = !False;

Which in common tongue, that line of code is read “toggleValue equals to NOT False”, so as a consequence, we are instructing Javascript to assign the value of True, because saying NOT False is the same as saying True.

With the line of code “toggleValue = !toggleValue;” we are ensuring that whatever the value we retrieved (true or false), it will always assign the contrary value.

Finally, after modifying the value, we need to send it back to Storyline and assign it the the “myToggle” variable. This can be done by using the function we reviewed earlier:

player.SetVar(“myToggle”, toggleValue);

The previous code is asking the API to assign the value stored in the variable “toggleValue”, to our variable in Storyline “myToggle”.

And with this, our layer should be showing up and hiding when we click on the button we added to the player.

Testing your interaction

Unfortunately, all the code we created on the previous section, is not available on preview within Storyline, because all the Javascript is blocked for security reasons.

In consequence, we have 2 different options (that I can think of) to test our customized Javascript code:

1. We can actually publish our module and upload it either to our LMS or our webserver, that way it is possible to test our interaction live.
2. Another option, if you don’t have a web server available nor a LMS, is to install a local server, like Xampp, and test it locally.

It could be a bit time consuming, but it is worth since the interactions created this way can improve the engagement of our modules.

I know using Javascript at first could be somewhat confusing or it could terrify you, if you are not used to code, but in the end it is rewarding to give it a shot when producing your eLearning modules.