Programming tips: Modifying Storyline eLearning modules’ variables from Adobe Flash

As part of our series of tutorials, regarding extended functionality in Storyline by using Javascript and/or assets created in external tools, I want to jump in to a more advanced topic that will ultimately take our eLearning modules to the next level.

Let’s say you created in Adobe Flash a very fancy navigation bar with play, next slide and previous slide buttons, with some beautiful animations and states for the buttons that could hardly be done directly in Storyline, and now you are wondering how you will be able to actually control the module with that externally developed asset.

One option, and probably the simplest, is to import the flash object into your Storyline project and then cover the clickable areas with hotspots. While effective, because they will easily trigger the actions you want, this hotspots will also interfere with the states of your buttons, like the hover and clicked states. This happens because your hotspots are basically covering your Flash object and, in consequence, this object is not receiving any mouse inputs.

Another option is to have variables in Storyline that, modified by the Flash object, will drive the eLearning module, pausing and resuming the timeline, and going to the next or previous slide. In this tutorial, I want to show you how to achieve this by only using 2 variables in Storyline, that way we can also explore a bit more about triggers on the slides.

Just a heads up, since we will be using ActionScript 3 in Flash, we will have to do a bit more with coding compared to the first 2 tutorials.

Setting up the environment in Storyline

Let’s start by setting up the environment within Storyline, that way when we jump to coding in Flash, we will already know what to modify in our eLearning module.

The first step is to create 2 variables in Storyline that, as I mentioned before, will affect our module, pausing it or resuming it, and making it navigate to different slides. This variables could be as follows:

• pauseModule: This variable is a Boolean or True/False and its default value is set to False.
• navigateTo: This variable is Text variable and it’s default value is set to blank.

The second step is to create the triggers on the slide that will actually affect it. This triggers could be as follows:

1. The first trigger should pause the timeline when ‘pauseModule’ changes to True.
2. The second trigger should resume the timeline when ‘pauseModule’ changes to False.
3. The third trigger should make the module jump to the next slide if ‘navigateTo’ changes to the value “next”.
4. The fourth trigger should make the module jump to the previous slide if ‘navigateTo’ changes to the value “prev”.
5. The fifth trigger should reset the value of ‘navigateTo’ to blank when the timeline of the slide starts.

Note: On the third and fourth triggers, the comparison to the values “next” and “prev” shouldn’t be case sensitive, that way we can ensure that inputs like “Next” or “PREV” have the same effect on the module.

Extending a bit further our work in Storyline, we can easily create a Master slide and implement this triggers in there, that way we don’t have to repeat this process n-times throughout our module.

Controlling our eLearning module with AS3

Now that we have set our variables and triggers in Storyline, it is time to go to Flash and create the code that will activate those triggers.

Let’s assume we have created 3 buttons and they are as follows:

• A play/pause button called ‘playPauseBtn’
• A next button called ‘nextBtn’
• A previous button called ‘prevBtn’

With that in mind, let’s create our code in AS3. In this part, I will explain each line of code so that we all have a clear understanding of what they do.

The first step is to import the libraries related to the events of the mouse (e.g. Click event) and related to the communication of our Flash object with Storyline.

import flash.events.MouseEvent;

import flash.external.ExternalInterface;

The ExternalInterface library will allow us to call Javascript functions that are external to our Flash object, and the MouseEvent library, will capture the mouse input on our buttons.

var playPause:Boolean = false;

var navigateTo:String = “”;

In the lines of code above we are defining the same two variables we defined in Storyline, the ‘playPause’ variable relates to the ‘pauseModule’ variable and will indicate whether to play or pause the timeline of our eLearning module; the ‘navigateTo’ variable will determine if the module has to navigate to the next or previous slide from the current slide. These variables will be modified by the functions linked to the following event listeners:

playPauseBtn.addEventListener(MouseEvent.CLICK, controlTimeline);

nextBtn.addEventListener(MouseEvent.CLICK, navigateNext);

prevBtn.addEventListener(MouseEvent.CLICK, navigatePrev);

In essence, an event listener, is a function that will be executed when an event happens, in this case, the controlTimeline function will be executed when the playPauseBtn is clicked, and the navigateNext and navigatePrev functions will be executed when the next or previous buttons are clicked, respectively.

Now let’s see how these 3 functions are defined, starting with the controlTimeline function:

 

function controlTimeline(evt:MouseEvent):void{

                playPause = !playPause;

                ExternalInterface.call(“GetPlayer.SetVar”, “pauseModule”, playPause);

}

We will take a more in-depth look at the structure of AS3 in a future tutorial, in the meantime, let’s understand what the previous function is doing.

Basically, what the contolTimeline function does is to toggle the value of the variable playPause between True and False, as explained on a previous tutorial (link to the first programming tips article), and then it executes our beloved Javascript function “SetVar” (please refer to the first programming tips article for a better understanding of this function) by passing the two necessary parameters.

 

function navigateNext(evt:MouseEvent):void{

                navigateTo = “next”;

                ExternalInterface.call(“GetPlayer.SetVar”, “navigateTo”, navigateTo);

}

 

function navigatePrev(evt:MouseEvent):void{

                navigateTo = “prev”;

                ExternalInterface.call(“GetPlayer.SetVar”, “navigateTo”, navigateTo);

}

And finally, the previous functions will indicate the eLearning module to navigate forward or backwards by changing the value of the variable ‘navigateTo’ to “next” or “prev”.

Before finishing the tutorial, let’s remember that this interaction can’t be tested locally within storyline and, as indicated on the first programming tips tutorial, we would need to make use of other tools to verify if our customized code is working.

If you want to know more about Javascript and ActionsScript 3 applied to eLearning or about how to use other tools, such as software for 2D or 3D animation to enrich the outcome of your products, don’t forget to visit our blog or our website at www.pathwaystrainingandelearning.ca.

Programming tips: Accessing LMS functions using the Javascript API in Storyline for eLearning modules

Continuing with the programming tips we started in the previous post, regarding how to write code in Storyline for eLearning modules, let’s continue this time with a little bit more of an advanced coding.

To summarize, we now know that our eLearning modules, when published from Storyline, come with a set of Javascript libraries that allows assets developed in external tools (e.g. Adobe Flash) to communicate with our modules and modify variables.

We also know about the reporting capabilities Storyline has, meaning that all the quiz questions you create in the modules, have the option to be graded and then reported to the LMS.

However, learning may not be as simple as creating slide questions with multiple answer questions, drag and drops or matching sequences, and sometimes we are required to develop this interactions somewhere else, so what happens when you want those interactions to be part of your eLearning module’s grade?

Well, thankfully we are able to manually report that score to our LMS, using Storyline’s Javascript functionality.

Storing the activities’ points and converting it to a percentage

Let’s say we have developed 6 interactivities in Adobe Flash and all of them send a point value to Storyline after they have been completed by the learner (This will be covered in another tutorial). To store this value in Storyline, let’s create 6 Number variables as follows:

• Activity1
• Activity2
• Activity3
• Activity4
• Activity5
• Activity6

And set all of them to a default value of 0.

Now, after all the slides with the activities, let’s create another slide that will work as our results slide, calculating the percentage achieved by the learner on the previous activities. On this slide, we can use a Javascript code that looks something similar to this:

var player = GetPlayer();

var act1 = player.GetVar(“Activity1”);

var act2 = player.GetVar(“Activity2”);

var act3 = player.GetVar(“Activity3”);

var act4 = player.GetVar(“Activity4”);

var act5 = player.GetVar(“Activity5”);

var act6 = player.GetVar(“Activity6”);

var scoreTotal = act1 + act2 + act3 + act4 + act5 + act6;

var percentage = scoreTotal * 100 /60;

 

Looks a little bit complicated? Well, let me explain it.

On the first 7 lines of code, we first get the Javascript API from the player and then get and store all the six variables containing the values reported by the activities. Then we have the following line of code:

var scoreTotal = act1 + act2 + act3 + act4 + act5 + act6;

In this line, we are only finding the total achieved by the learner after going through all the 6 interactions. Finally, we see this:

var percentage = scoreTotal * 100 /60;

This is just a simple ratio that allows us to translate the achieved points by the learner into a percentage. Let’s assume we have only 6 of these interactions and each one of them awards the learner 10 points if completed correctly, thus the value of 60.

If we do the math, let’s say the learner scored a total of 40 points, then percentage will be 66.7% (rounding up to the nearest decimal).

Reporting the score to the LMS

Now that we have the percentage we want to report, we can now report it to our LMS. Thankfully, Storyline allows us to communicate manually by providing a set of functions that we can use to report score or completion.

We achieve that by adding the following lines of code after calculating the percentage:

var lmsAPI = parent;

lmsAPI.SetScore(percentage, 100, 0);

What the previous 2 lines of code do, is that first, we get the LMS API provided by Storyline, and then we use the “SetScore” function to report the percentage to our LMS. If you notice, this function takes 3 parameters:

• The first value is the percentage achieved by the learner
• The second value is the maximum score that can be reported, 100 in this case, because we are talking about percentages
• And the third value is the minimum score that can be reported, 0 in this case.

After adding this Javascript code to your project, you can now rest assured that your elearning module will report a score, even if those values don’t come directly from Storyline, but they come from activities or interactions you developed in an external tool.

If you want to know more about Javascript applied to eLearning or about how to use other tools, such as software for 2D or 3D animation to enrich the outcome of your products, don’t forget to visit our blog or our website at www.pathwaystrainingandelearning.ca.

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.