DomTaskPlayer · MattSnider.com

This is a continuation of the article Project - AutoPlayDom. The project was renamed to DomTaskPlayer, because the new name is semantically more correct, as the object plays through a series of Dom related tasks. The full source code is available at http://www.mattsnider.com/assets/js/widget/DomTaskPlayer.js. The source code has drastically changed from last week, as supporting backwards navigation through the already played DomTasks, required a massive redesign of the code.

For starters the "DomTaskPlayer.add" method has changed, to accept a collection of step objects, which will contain task objects, which will contain action objects:

Example 1: A Step Object

var step = {
	_isValid: false, // used internally, updated after first next call
	name: , // what this step is
	tasks: [ // an array of tasks
		{ // task
			action: [
				{fx: function() {}, method: , params: [], reverseMethod: , reverseFx: function() {}}, // action
				…
			],
			search: [
				{fx: function() {}, method: , params: []}, // action
				…
			],
			reverse: [] // internally managed
		},
		…
	]
};

A step object is a collection of task objects and a name to label the step. The task object is a collection of search action objects (to find the node(s) to apply actions to), and a collection of action action objects (actually describing how to change the nodes found when searching). There is no limit to the number of tasks per step and actions per task. When the "DomTaskPlayer.next" method is called an internal collection of action objects are attached to the reverse list, explaining how to reverse the current step.

The next and previous methods have been simplified, delegating the work to smaller more targeted internal assertion and action functions.

Example 2: DomTaskPlayer.next

next: function() {
    // go to the next position
    if (_that.hasNext()) {
        _index += 1;

        var step = _steps[_index];

        // already validated and found nodes, no need to assert
        if (step._isValid) {
            _array_walk(step.tasks, function(task) { // iterate on the tasks
                _array_walk(task.action, _execute_action); // iterate on the actions
            });
        }
        else {
            _array_walk(step.tasks, function(task) { // iterate on the tasks
                _assert_valid_task(task);

                var tobj = {};

                _array_walk(task.search, _execute_search, tobj);

                _array_walk(task.action, function(action) { // iterate on the actions
                    _assert_valid_action(action); // validates and/or sets action.fx; assures action.params is an array
                    _assert_user_reversible(action); // user fx is reversible
                    action.nodes = tobj.nodes;
                    _execute_action(action);
                });
            });

            step._isValid = true;
        }

        _that.onStepChange.fire([step, next]);
    }
},

This method first asserts that there is a next step available, then grabs the step from the internal step array. If the step has the internal variable _isValid set to true, then the method knows that it has previously already validated this step and can skip the search actions, executing the action tasks on cached DOM nodes. Otherwise, it iterates through each task and asserts that the tasks are valid. Afterwards, it searches the DOM using the search action objects, producing an object with key nodes. Then it iterates on the action action objects and asserts they are valid and reversible. If no errors have been thrown, terminating the flow, then the method actually executes the action objects. As each action object is executed, the internal methods create the reverse actions, which will be used with the previous method.

In addition, to supporting previous and the massive revisions to next, there is now a build-in, public method initKeyListeners that hijacks the arrow keys (and a - left arrow, s - down arrow, d - right arrow, w - up arrow) to call one of the public action methods of DomTaskPlayer (previous, stop, next, play). The developer can require that any combination of Ctrl, Alt, or Shift be pressed as well, so not to be obtrusive.

Example 3: DomTaskPlayer.initKeyListeners

initKeyListeners: function(forceCtrl, forceShift, forceAlt) {
    _YE.on(document, keydown, function(e) {
        if (forceCtrl && ! e.ctrlKey) {return;} // may trigger browser events
        if (forceShift && ! e.shiftKey) {return;}
        if (forceAlt && ! e.altKey) {return;}

        _YE.preventDefault(e); // stop browser events

        switch (_YE.getCharCode(e)) {
            case _YK.DOWN:
            case 83: // s
                _that.stop();
            break;

            case _YK.LEFT:
            case 65: // a
                _that.previous();
            break;

            case _YK.RIGHT:
            case 68: // d
                _that.next();
            break;

            case _YK.UP:
            case 87: // w
                _that.play();
            break;

            default: // do nothing
        }
    });
    _that.initKeyListeners = function() {};
},

At the end of initKeyListeners the method is set to empty function, thereby preventing the developer from accidentally attaching these key listeners more than once. This method can be called anytime after the DomTaskPlayer object has been initialized and it is recommended that at least two special keys be set to true, such as Shift and Ctrl:

Example 4: Calling initKeyListeners

yourDomTaskPlayerObject.initKeyListeners(true, true);

In Example 4, the user will need to hold Shift + Ctrl + ArrowKey to trigger the desired method.

Most importantly, this tool is easy to use; see Dom Task Player Test Page. Although easy to use, this tool is very complicated, please let me know if something does not work for you or are having trouble getting it working.

Lastly, please keep in mind that order of operations are very important with tasks, so if you first apply a class that changes the background, then change the background with a style directly in the same step object, then the reverse operation will be confused and apply the wrong background color.