sideshow 0.4.1

data/src/step/step_details_panel.js

@@ -0,0 +1,87 @@
+    /**
+    The panel that holds step description, is positionated over the biggest remaining space among the four parts of a composite mask
+
+    @class DetailsPanel
+    @@singleton
+    @extends FadableItem
+    **/
+    var DetailsPanel = jazz.Class().extending(FadableItem).singleton;
+
+    /**
+    An object holding dimension information for the Details Panel
+
+    @@field dimension
+    @type Object
+    **/
+    DetailsPanel.field("dimension", {});
+
+    /**
+    An object holding positioning information for the Details Panel
+
+    @@field position
+    @type Object
+    **/
+    DetailsPanel.field("position", {});
+
+    /**
+    Renders the Details Panel
+
+    @method render
+    **/
+    DetailsPanel.method("render", function() {
+        this.$el = $("<div>")
+            .addClass("sideshow-details-panel")
+            .addClass("sideshow-hidden");
+        this.callSuper("render");
+    });
+
+    /**
+    Positionates the panel automatically, calculating the biggest available area and putting the panel over there
+
+    @method positionate
+    **/
+    DetailsPanel.method("positionate", function() {
+        var parts = Mask.CompositeMask.singleInstance.parts;
+
+        //Considering the four parts surrounding the current subject, gets the biggest one
+        var sortedSides = [
+            [parts.top, "height"],
+            [parts.right, "width"],
+            [parts.bottom, "height"],
+            [parts.left, "width"]
+        ].sort(function(a, b) {
+            return a[0].dimension[a[1]] - b[0].dimension[b[1]];
+        });
+
+        var biggestSide = sortedSides.slice(-1)[0];
+
+        for(var i = 2; i > 0; i--){
+            var side = sortedSides[i];
+            var dimension = side[0].dimension;
+            if(dimension.width > 250 && dimension.height > 250){
+                if((dimension.width + dimension.height) > ((biggestSide[0].dimension.width + biggestSide[0].dimension.height) * 2))
+                    biggestSide = side;
+            }
+        }
+
+        if (biggestSide[1] == "width") {
+            this.$el
+                .css("left", biggestSide[0].position.x).css("top", 0)
+                .css("height", Screen.dimension.height).css("width", biggestSide[0].dimension.width);
+        } else {
+            this.$el
+                .css("left", 0).css("top", biggestSide[0].position.y)
+                .css("height", biggestSide[0].dimension.height).css("width", Screen.dimension.width);
+        }
+
+        this.dimension = {
+            width: parsePxValue(this.$el.css("width")),
+            height: parsePxValue(this.$el.css("height"))
+        };
+
+        this.position = {
+            x: parsePxValue(this.$el.css("left")),
+            y: parsePxValue(this.$el.css("top"))
+        };
+    });
+

data/src/step/subject.js

@@ -0,0 +1,100 @@
+    /**
+    The current subject (the object being shown by the current wizard)
+
+    @class Subject
+    @static
+    **/
+    var Subject = {};
+
+    /**
+    The current subject jQuery wrapped DOM element 
+
+    @@field obj
+    @static
+    @type Object
+    **/
+    Subject.obj = null;
+
+    /**
+    The current subject dimension information
+
+    @@field position
+    @static
+    @type Object
+    **/
+    Subject.dimension = {};
+
+    /**
+    The current subject positioning information
+
+    @@field position
+    @static
+    @type Object
+    **/
+    Subject.position = {};
+
+    /**
+    The current subject border radius information
+
+    @@field borderRadius
+    @static
+    @type Object
+    **/
+    Subject.borderRadius = {};
+
+    /**
+    Checks if the object has changed since the last checking
+
+    @method hasChanged
+    @return boolean
+    **/
+    Subject.hasChanged = function() {
+        if (!this.obj) return false;
+
+        return (this.obj.offset().left - $window.scrollLeft() !== this.position.x) ||
+            (this.obj.offset().top - $window.scrollTop() !== this.position.y) ||
+            (this.obj.outerWidth() !== this.dimension.width) ||
+            (this.obj.outerHeight() !== this.dimension.height) ||
+            (parsePxValue(this.obj.css("border-top-left-radius")) !== this.borderRadius.leftTop) ||
+            (parsePxValue(this.obj.css("border-top-right-radius")) !== this.borderRadius.rightTop) ||
+            (parsePxValue(this.obj.css("border-bottom-left-radius")) !== this.borderRadius.leftBottom) ||
+            (parsePxValue(this.obj.css("border-bottom-right-radius")) !== this.borderRadius.rightBottom) ||
+            Screen.hasChanged();
+    };
+
+    /**
+    Updates the information about the suject
+
+    @method updateInfo
+    @param {Object} config                                Dimension, positioning and border radius information
+    **/
+    Subject.updateInfo = function(config) {
+        if (config === undefined) {
+            this.position.x = this.obj.offset().left - $window.scrollLeft();
+            this.position.y = this.obj.offset().top - $window.scrollTop();
+            this.dimension.width = this.obj.outerWidth();
+            this.dimension.height = this.obj.outerHeight();
+            this.borderRadius.leftTop = parsePxValue(this.obj.css("border-top-left-radius"));
+            this.borderRadius.rightTop = parsePxValue(this.obj.css("border-top-right-radius"));
+            this.borderRadius.leftBottom = parsePxValue(this.obj.css("border-bottom-left-radius"));
+            this.borderRadius.rightBottom = parsePxValue(this.obj.css("border-bottom-right-radius"));
+        } else {
+            this.position.x = config.position.x;
+            this.position.y = config.position.y;
+            this.dimension.width = config.dimension.width;
+            this.dimension.height = config.dimension.height;
+            this.borderRadius.leftTop = config.borderRadius.leftTop;
+            this.borderRadius.rightTop = config.borderRadius.rightTop;
+            this.borderRadius.leftBottom = config.borderRadius.leftBottom;
+            this.borderRadius.rightBottom = config.borderRadius.rightBottom;
+        }
+
+        Screen.updateInfo();
+    };  
+
+    Subject.isSubjectVisible = function(position, dimension){
+        if((position.y + dimension.height) > $window.height() || position.y < 0){
+            return false;
+        }
+        return true;
+    };

data/src/wizard/wizard.js

@@ -0,0 +1,395 @@
+    /**
+    Represents a tutorial
+
+    @class Wizard
+    @@initializer
+    @param {Object} wizardConfig                          The wizard configuration object                        
+    **/
+    var Wizard = jazz.Class(function(wizardConfig) {
+        this.name = wizardConfig.name;
+        this.title = wizardConfig.title;
+        this.description = wizardConfig.description;
+        this.estimatedTime = wizardConfig.estimatedTime;
+        this.affects = wizardConfig.affects;
+        this.preparation = wizardConfig.preparation;
+        this.listeners = wizardConfig.listeners;
+        this.showStepPosition = wizardConfig.showStepPosition;
+        this.relatedWizards = wizardConfig.relatedWizards;
+    });
+
+    /**
+    A function to prepare the environment for running a wizard (e.g. redirecting to some screen)
+
+    @@field preparation
+    @type Function
+    **/
+    Wizard.field("preparation");
+
+    /**
+    An object with listeners to this wizard (e.g. beforeWizardStarts, afterWizardEnds)
+
+    @@field listeners
+    @type Object
+    **/
+    Wizard.field("listeners");
+
+    /**
+    A configuration flag that defines if the step position (e.g. 2/10, 3/15, 12/12) will be shown
+
+    @@field showStepPosition
+    @type boolean
+    **/
+    Wizard.field("showStepPosition");
+
+    /**
+    An array with related wizards names. These wizards are listed after the ending of the current wizard.
+
+    @@field relatedWizards
+    @type Array
+    **/
+    Wizard.field("relatedWizards");
+
+    /**
+    The wizard unique name (used internally as an identifier)
+
+    @@field name
+    @type String
+    **/
+    Wizard.field("name");
+
+    /**
+    The wizard title (will be shown in the list of available wizards)
+
+    @@field title
+    @type String
+    **/
+    Wizard.field("title");
+
+    /**
+    The wizard description (will be shown in the list of available wizards)
+
+    @@field description
+    @type String
+    **/
+    Wizard.field("description");
+
+    /**
+    The wizard estimated completion time (will be shown in the list of available wizards)
+
+    @@field estimatedTime
+    @type String
+    **/
+    Wizard.field("estimatedTime");
+
+    /**
+    A collection of rules to infer whether a wizard should be available in a specific screen
+
+    @@field affects
+    @type Array
+    **/
+    Wizard.field("affects");
+
+    /**
+    The sequence of steps for this wizard
+
+    @@field storyline
+    @private
+    @type Object
+    **/
+    Wizard.field("_storyline");
+
+    /**
+    Points to the current step object in a playing wizard
+
+    @@field currentStep
+    @type Object
+    **/
+    Wizard.field("currentStep");
+
+    /**
+    Sets the storyline for the wizard
+
+    @method storyLine
+    **/
+    Wizard.method("storyLine", function(storyline) {
+        this._storyline = storyline;
+    });
+
+    /**
+    Runs the wizard
+
+    @method play
+    **/
+    Wizard.method("play", function() {
+        var wiz = this;
+
+        Polling.enqueue("check_composite_mask_subject_changes", function() {
+            Mask.CompositeMask.singleInstance.pollForSubjectChanges();
+        });
+
+        Polling.enqueue("check_arrow_changes", function() {
+            Arrows.pollForArrowsChanges(true);
+        });
+
+        //Checks if the wizard has a storyline
+        if (!this._storyline) throw new SSException("201", "A wizard needs to have a storyline.");
+        var steps = this._storyline.steps;
+
+        //Checks if the storyline has at least one step
+        if (steps.length === 0) throw new SSException("202", "A storyline must have at least one step.");
+
+        DetailsPanel.singleInstance.render();
+
+        StepDescription.singleInstance.render();
+
+        var listeners = this.listeners;
+        if (listeners && listeners.beforeWizardStarts) listeners.beforeWizardStarts();
+
+        flags.changingStep = true;
+        this.showStep(steps[0], function() {
+            //Releases the polling for checking any changes in the current subject
+            //flags.lockMaskUpdate = false;
+
+            //Register the function that checks the completing of a step in the polling queue
+            Polling.enqueue("check_completed_step", function() {
+                wiz.pollForCheckCompletedStep();
+            });
+        });
+
+        Mask.CompositeMask.singleInstance.fadeIn();
+    });
+
+    /**
+    Shows a specific step
+
+    @method showStep
+    @param {Object} step                                  The step to be shown
+    @param {Function} callback                            A callback function to be called
+    **/
+    Wizard.method("showStep", function(step, callback) {
+        var wizard = this;
+        flags.skippingStep = false;
+
+        Arrows.clear();
+
+        if (this.currentStep && this.currentStep.listeners && this.currentStep.listeners.afterStep)
+            this.currentStep.listeners.afterStep();
+
+        function skipStep(wiz) {
+            flags.skippingStep = true;
+            wizard.next();
+        }
+
+        if (step && step.listeners && step.listeners.beforeStep)
+            step.listeners.beforeStep();
+
+        //The shown step is, of course, the current
+        this.currentStep = step;
+
+        //If the step has a skipIf evaluator and it evaluates to true, we'll skip to the next step!
+        if (step.skipIf && step.skipIf())
+            skipStep(this);
+
+        if (flags.changingStep && !flags.skippingStep) {
+            //Sets the current subject and updates its dimension and position
+            if (step.subject)
+                SS.setSubject(step.subject);
+            else
+                SS.setEmptySubject();
+            //Updates the mask
+            Mask.CompositeMask.singleInstance.update(Subject.position, Subject.dimension, Subject.borderRadius);
+
+            var sm = Mask.SubjectMask.singleInstance;
+            sm.fadeOut(function() {
+                if (step.lockSubject) sm.show(true);
+            });
+            //The details panel (that wraps the step description and arrow) is shown
+            DetailsPanel.singleInstance.show();
+            //Repositionate the details panel depending on the remaining space in the screen
+            DetailsPanel.singleInstance.positionate();
+            //Sets the description properties (text, title and step position)
+            var description = StepDescription.singleInstance;
+            var text = step.text;
+            text = text instanceof Function ? SS.heredoc(text) : text;
+            if (step.format == "markdown") {
+                description.setHTML(new markdown.Converter().makeHtml(text));
+            } else
+                description.setText(text);
+
+            description.setTitle(step.title);
+            description.setStepPosition((this.getStepPosition() + 1) + "/" + this._storyline.steps.length);
+            //If this step doesn't have its own passing conditions/evaluators, or the flag "showNextButton" is true, then, the button is visible
+            if (step.showNextButton || step.autoContinue === false || !(step.completingConditions && step.completingConditions.length > 0)) {
+                var nextStep = this._storyline.steps[this.getStepPosition() + 1];
+                if (nextStep) {
+                    description.nextButton.setText(getString(strings.next) + ": " + this._storyline.steps[this.getStepPosition() + 1].title);
+                } else {
+                    description.nextButton.setText(getString(strings.finishWizard));
+                }
+                description.nextButton.show();
+
+                if (step.autoContinue === false) description.nextButton.disable();
+            } else {
+                description.nextButton.hide();
+            }
+
+            if (step.targets && step.targets.length > 0) {
+                Arrows.setTargets(step.targets);
+                Arrows.render();
+                Arrows.positionate();
+                Arrows.fadeIn();
+            }
+
+            //Step Description is shown, but is transparent yet (since we need to know its dimension to positionate it properly)
+            description.show(true);
+            if(!Mask.CompositeMask.singleInstance.scrollIfNecessary(Subject.position, Subject.dimension)){
+                description.positionate();
+                //Do a simple fade in for the description box
+                description.fadeIn();
+            }
+            
+
+            //If a callback is passed, call it    
+            if (callback) callback();
+            flags.changingStep = false;
+        }
+    });
+
+    /**
+    Shows the next step of the wizard
+
+    @method next 
+    @param {Function} callback                            A callback function to be called
+    **/
+    Wizard.method("next", function(callback, nextStep) {
+        if (!flags.changingStep || flags.skippingStep) {
+            flags.changingStep = true;
+            var currentStep = this.currentStep;
+            nextStep = nextStep || this._storyline.steps[this.getStepPosition(this.currentStep) + 1];
+            var self = this;
+
+            this.hideStep(function() {
+                if (nextStep) self.showStep(nextStep, function() {
+                    if (callback) callback();
+                });
+                else {
+                    if (currentStep && currentStep.listeners && currentStep.listeners.afterStep)
+                        currentStep.listeners.afterStep();
+
+                    var completedWizard = currentWizard;
+                    currentWizard = null;
+                    var listeners = self.listeners;
+                    if (listeners && listeners.afterWizardEnds) listeners.afterWizardEnds();
+
+                    if (!SS.showRelatedWizardsList(completedWizard)) SS.close();
+                }
+            });
+        }
+    });
+
+    /**
+    Hides the step
+
+    @method hideStep
+    @param {Function} callback                            A callback function to be called in the ending of the hiding process
+    **/
+    Wizard.method("hideStep", function(callback) {
+        StepDescription.singleInstance.fadeOut(function() {
+            DetailsPanel.singleInstance.hide();
+        });
+        Arrows.fadeOut();
+        Mask.SubjectMask.singleInstance.update(Subject.position, Subject.dimension, Subject.borderRadius);
+        Mask.SubjectMask.singleInstance.fadeIn(callback);
+    });
+
+    /**
+    Returns the position of the step passed as argument or (by default) the current step
+
+    @method getStepPosition
+    @param {Object} step                                  The step object to get position
+    **/
+    Wizard.method("getStepPosition", function(step) {
+        return this._storyline.steps.indexOf(step || this.currentStep);
+    });
+
+    /**
+    Checks if a wizard should be shown in the current context (running each evaluator defined for this wizard)
+
+    @method isEligible
+    @return {boolean}                                     A boolean indicating if this wizard should be available in the current context
+    **/
+    Wizard.method("isEligible", function() {
+        var l = global.location;
+
+        function isEqual(a, b, caseSensitive) {
+            return (caseSensitive) ? a === b : a.toLowerCase() === b.toLowerCase();
+        }
+
+        for (var c = 0; c < this.affects.length; c++) {
+            var condition = this.affects[c];
+            if (condition instanceof Function) {
+                if (condition()) return true;
+            } else if (condition instanceof Object) {
+                if ("route" in condition) {
+                    var route = l.pathname + l.search + l.hash;
+                    if (isEqual(route, condition.route, condition.caseSensitive)) return true;
+                }
+
+                if ("hash" in condition) {
+                    if (isEqual(location.hash, condition.hash, condition.caseSensitive)) return true;
+                }
+
+                if ("url" in condition) {
+                    if (isEqual(location.href, condition.url, condition.caseSensitive)) return true;
+                }
+            }
+        }
+        return false;
+    });
+
+    /**
+    Checks if the current user already watched this wizard
+
+    @method isAlreadyWatched
+    @return {boolean}                                     A boolean indicating if the user watched this wizard
+    @@todo Implement this method...
+    **/
+    Wizard.method("isAlreadyWatched", function() {
+        //ToDo
+        return false;
+    });
+
+    /**
+    A Polling function to check if the current step is completed
+
+    @method pollForCheckCompletedStep
+    **/
+    Wizard.method("pollForCheckCompletedStep", function() {
+        var conditions = this.currentStep.completingConditions;
+        if (conditions && conditions.length > 0 && !flags.skippingStep) {
+            var completed = true;
+            for (var fn = 0; fn < conditions.length; fn++) {
+                var completingCondition = conditions[fn];
+                if (!completingCondition()) completed = false;
+            }
+
+            if (completed) {
+                if (this.currentStep.autoContinue === false) StepDescription.singleInstance.nextButton.enable();
+                else currentWizard.next();
+            }
+        }
+    });
+
+
+    Wizard.method("prepareAndPlay", function(){
+        currentWizard = this;
+
+        if (!this.isEligible()) {
+            if (this.preparation)
+                this.preparation(function() {
+                    currentWizard.play();
+                });
+            else
+                throw new SSException("203", "This wizard is not eligible neither has a preparation function.");
+        } else this.play();
+    });

data/src/wizard/wizard_control_variables.js

@@ -0,0 +1,95 @@
+    /**
+    Stores the variables used in step evaluators 
+
+    @class ControlVariables
+    @static
+    **/
+    SS.ControlVariables = {};
+
+    /**
+    Sets a variable value
+
+    @method set
+    @param {String} name                                  The variable name
+    @param {String} value                                 The variable value
+    @return {String}                                      A formatted key=value pair representing the defined variable 
+    **/
+    SS.ControlVariables.set = function(name, value) {
+        var variable = {};
+        if (this.isDefined(name)) {
+            variable = this.getNameValuePair(name);
+        } else controlVariables.push(variable);
+
+        variable.name = name;
+        variable.value = value;
+        return name + "=" + value;
+    };
+
+    /**
+    Sets a variable if not defined yet
+
+    @method setIfUndefined
+    @param {String} name                                  The variable name
+    @param {String} value                                 The variable value
+    @return {String}                                      A formatted key=value pair representing the defined variable 
+    **/
+    SS.ControlVariables.setIfUndefined = function(name, value) {
+        if (!this.isDefined(name)) return this.set(name, value);
+    };
+
+    /**
+    Checks if some variable is already defined
+
+    @method isDefined
+    @param {String} name                                  The variable name
+    @return {boolean}                                     A boolean indicating if the variable is already defined
+    **/
+    SS.ControlVariables.isDefined = function(name) {
+        return this.getNameValuePair(name) !== undefined;
+    };
+
+    /**
+    Gets a variable value
+
+    @method get
+    @param {String} name                                  The variable name
+    @return {any}                                         The variable value
+    **/
+    SS.ControlVariables.get = function(name) {
+        var pair = this.getNameValuePair(name);
+        return pair ? pair.value : undefined;
+    };
+
+    /**
+    Gets a pair with name and value 
+
+    @method getNameValuePair
+    @param {String} name                                  The variable name
+    @return {Object}                                      A pair with the variable name and value
+    **/
+    SS.ControlVariables.getNameValuePair = function(name) {
+        for (var i = 0; i < controlVariables.length; i++) {
+            var variable = controlVariables[i];
+            if (variable.name === name) return variable;
+        }
+    };
+
+    /**
+    Remove some variable from the control variables collection
+
+    @method remove
+    @param {String} name                                  The variable name
+    @return {Object}                                      A pair with the removed variable name and value
+    **/
+    SS.ControlVariables.remove = function(name) {
+        return controlVariables.splice(controlVariables.indexOf(this.getNameValuePair(name)), 1);
+    };
+
+    /**
+    Clear the control variables collection 
+
+    @method clear
+    **/
+    SS.ControlVariables.clear = function() {
+        controlVariables = [];
+    };