How should I make complex, sequential events in javascript

Question

I'm working on an interactive tutorial-tool for JavaScript. The core of the tool is the script of the tutorial. The script will trigger various functions that run animations, speaker-voices load new pages etc. Three sample calls(most tutorials will have 10-100s of calls, so a neat overview of the calls is highly desired:

wrap(); //wrap the page in an iframe
playsound('media/welcome') //playing a sound (duh)
highlight('[name=firstname]'); //animation that highlights an element.
playsound('media/welcome2');
loadpage(page2); //loading a new page

All calls have something in common: they have non-normal-triggers. In this simple script for example, the second call should be triggered once the iframe in the first call is loaded. The third script is triggered once the sound is complete (ie delay). The fourth function should be triggered once the animation is complete. The fifth event should be triggered on an event (for example a click).

A technical solution to this would be to call the function in the callback of the previous function, this has the potential to get pretty messy. What I like with a solution wherer the functions are called lite this is that someone with a little bit of brains, but no coding experience could hammer up a script of their own. How would you solve this? I'm pretty new to javascript so if you could be explicit i'd appreciate it.

Answer 1

I'd use a per-built solution. There is bound be one that fits your needs. Something simple like jTour or if that doesn't cover it something a little more complex like Scriptio. Some of the answers to this question may also be of interest to you.

Edit If you don't want to use a preexisting solution, I'd do something like this:

var runTutorial = (function () {

    // The command object holds all the different commands that can
    // be used by someone for the tutorial. Each of these commands
    // will recive a callback set as their `this`. This
    // callback should be called by your commands when they are done
    // running. The person making the tutorial won't need to know
    // about the callback, the code will handle that.
    var commands = {
        wrap: function () {
            //wrap the page in an iframe
            this();
        },
        playsound: function (soundPath, soundLength) {
            //playing a sound (duh)
            setTimeout(this, soundLength);
        },
        highlight: function (selector) {
            //animation that highlights an element.
            //I'm using jQuery UI for the animation here,
            // but most animation libraries should provide
            // a callback for when the animation is done similarly
            $(selector).effect('highlight', 'slow', this);
        },
        loadpage: function (pageUrl) {
            //loading a new page
            setTimeout(this, 500);
        },
        waitForClick: function () {
            // when we go into the click handler `this` will no
            // longer be availble to us since we will be in a
            // different context, save `this` into `that` so
            // we can call it later.
            var that = this;
            $(document).one('click', function () {
                that();
            });
        }
    },
    // This function takes an array of commands
    // and runs them in sequence. Each item in the
    // array should be an array with the command name
    // as the first item and any arguments it should be
    // called with following as the rest of the items.
    runTutorial = function (commandList) {
        var nextCommand = function () {
            if (commandList.length > 0) {
                var args = commandList.shift();

                // remove the command name
                // from the argument list
                cmd = args.shift(1);

                // call the command, setting nextCommand as `this`
                commands[cmd].apply(nextCommand, args);
            }
        }

        nextCommand();
    };

    return runTutorial;

}()); 

$('#tutorialbutton').click(function() {
    runTutorial([
        ['playsound', 'media/welcome', 1000],
        ['highlight', '[name=firstname]'],
        ['playsound', 'media/welcome2', 1500],
        ['waitForClick'],
        ['loadpage', page2],
        ['playsound', 'media/page2', 100]
    ]);
});

The runTutorial function takes a simple array containing the commands in the order they should be run, along with their parameters. No need to bother the person writing the script with callbacks, runTutorial handles that for them. This has some big advantages over a system that requires the writer to manage callbacks. You don't need an unique name for each line in the script as you do with explicit callbacks, nor endless nesting of anonymous functions. You don't need to rewire anything to change the order that the commands are played in, you just physically rearrange them in the array.

jsfiddle you can play with

Each of your commands will need to wait for its action to be done before it calls its callback (aka this). I simulate this in the fiddle using setTimeout. For instance, if you are using jQuery's .animate for highlight, it provides a complete handler that fires when the animation is done, just stick this (with out the invocation parentheses ()) there. If you are using jQuery UI, it has a built-in 'highlight' effect, so you could implement it like this:

highlight: function (selector) {
    //animation that highlights an element.
    $(selector).effect('highlight', 'slow', this);
},

Most other libraries that provide animations should provide a similar callback option you can use.

Controlling the callback for the sounds may be harder depending on how you are playing them. If the method you are using doesn't provide a callback or a way of polling it to see if it is done yet you might just have to add another parameter to playsound that takes the length of the sound in ms and then waits that long before proceeding:

playsound: function (soundPath, soundLength) {
    //playing a sound (duh)
    setTimeout(this, soundLength);
},

Answer 2

Callbacks are your best bet, I think. They don't have to be messy (though it's certainly possible to make them completely incomprehensible). You could create each function to accept a callback, then use a structure like this to call them in sequence in a readable way:

var loadingSequence = {
    start : function() { wrap(this.playsound); },
    playsound : function() { playsound('media/welcome', this.highlight); },
    highlight : function() { highlight('[name=firstname]', this.playsound2); },
    playsound2 : function() { playsound('media/welcome2', this.loadpage); },
    loadpage : function()  { loadpage(page2); }
};

loadingSequence.start();