I did some tests a while ago of what element the scrollTop is set on, and because I can not find any clear overview of when the view port is what elsewhere, I guess I might as well publish the results here:

The testcase (quirks mode version).

Hopefully the WebKit folks will fix this inconsistency sometime soon, because the way it is now makes it kind of hard to implement a reliable future-proof generic getViewPort() method.

Probably the most robust way to determine the X and Y coordinates of a mouse event within the page is to leverage the non-standard pageX and pageY properties that most browsers support, and fall back to using clientX and clientY otherwise:

if ('pageX' in event && 'pageY' in event) {
    return new Point(event.pageX, event.pageY);
} else {
    var oDocument = (event.target || event.srcElement).ownerDocument;
    var oViewport = oDocument.compatMode == 'BackCompat' ?
                        oDocument.body : oDocument.documentElement;
    return new Point(
        oViewport.scrollLeft + event.clientX,
        oViewport.scrollTop + event.clientY
    );
}

p.s. relating to my previous post, note that I do use feature detection here for pageX and pageY. Didn’t mean to say feature detection is useless, just that it is not always the right solution, unlike what is preached by some.

Here I make an assumption that pageX, when/if implemented in IE, will be implemented correctly. Actually, given that this is a non-standardised property, perhaps it is not the most safe assumption to make. But then again, the property seems so simple, what could possibly go wrong. Right? Right? *Prepares to revisit this code snippet once IE9 is released…* :)

Except that browsers tend to implement their new features in a broken way. D’oh.

The node.children.tags() method is a good example. Originally an IE-ism/feature, which can be useful for a slight performance optimisation. Along comes Safari with support for tags() but returning nodes from the entire document instead of just the child nodes.

Firefox then decides to implement the children collection as well, however without tags() method and thus incompletely, again breaking my feature detection. And finally Opera goes in for the kill by throwing an exception when tags() is used in a document parsed as XHTML (iirc).

So after having to fix this stupid optimisation in my Selectors implementation three times, what did I end up doing? Right,

if (browser_ie)
   return node.children.tags(name);

Another example of feature detection gone awry we had at Backbase when IE8 introduced JSON support. IE8 manages to serialise XML DOMStrings (e.g. retrieved from getAttribute()) to null instead of "". Had we used browser detection instead of feature detection, the issue would not have occurred.

Feature detection is overrated. Because of this kind of crap I went back to (a sensible form of) browser detection, with the much more workable presumption that once implemented, browsers will not remove or break existing functionality. Yes, when the browser gets native support for whatever you want to use, it runs a little slower than possible initially. But in exchange you get the opportunity to explicitly test the feature before using it it.

Now I’m not saying feature detection is never good, there are cases where what you want to use is relatively simple, standardised and often-used on the web, like the addEventListener() method, and for such things feature detection is probably a safe bet. But be careful, and do realise that the history of browsers has shown that they very very much like to implement their new APIs and technologies in a broken way the first time around.

And there is of course the one golden rule: never depend on broken behaviour.

It is possible to produce OOP class-like definitions using JavaScript functions and prototypes. What follows is a description of syntax, best practices and oddities of this. The syntax used here uses no external libraries.

This syntax is also picked up by Eclipse’s JSDT plugin, which will provide you with a convenient object outline, code completion and more. JSDT is packaged with Eclipse EE by default.

Creating classes

JavaScript classes and methods are created in the following manner:

var MyClass = function() {
    // constructor
};

MyClass.prototype.myMethod = function() {
    // method
};

MyClass.myStaticMethod = function() {
    // static method
};

Convention for class names is to start with an upper-case letter (CamelCase), and members start with a lower-case letter (camelCase).

You instantiate an object using the new operator, e.g. return new MyClass();.

Documenting classes

Class and member documentation is created using JSDoc annotations, like so:

/**
 * Constructor description
 * @param bOption The first parameter
 * @class
 * Class description
 */
var MyClass = function(bOption) {
    // constructor
};

/**
 * Method description
 * @param {Array} oList The first parameter
 * @return {boolean} The result
 */
MyClass.prototype.doSomething = function(oList) {
    // method
};

It is recommended to create these always. The example’s method documentation also shows optional type annotations.

Creating class properties

Class properties should always be initialised in the constructor, so that you can use the constructor as a reference of which properties the object has, and so that the object is always in a defined state:

var MyClass = function() {
    this.myProperty = null;
};

MyClass.prototype.getMyProperty = function() {
    return this.myProperty;
};

MyClass.prototype.setMyProperty = function(oValue) {
    return this.myProperty = oValue;
};

Properties should generally be considered private, unless explicitly mentioned as public in the @class annotation. The reason for this is that JavaScript does not have property getters and setters (in all browsers), so Java’s methodology of creating getSomething() and setSomething() getter/setter methods is adopted. Accessor methods are essential to be able to deal with changing requirements, refactoring and performance optimisation in a straightforward manner and without compatibility problems.

Guideline for public properties: sometimes for convenience you want to make an exception. If you really must, direct references to other objects (Action.record) or primitive types (Channel.id, Field.value) are candidates for consideration. Avoid accessing arrays and hash maps directly though, so that you can easily change and optimise the implementation underneath. When in doubt you should use accessor methods.

Properties can also be defined directly on the prototype, however this is not recommended. Example:

var MyClass = function() {
};

MyClass.prototype.firstProperty  = null;               // okay (but beware!)
MyClass.prototype.secondProperty = 100;                // okay (but beware!)
MyClass.prototype.thirdProperty  = new OtherClass();   // bad

The reason why this is not recommended is because when a property is defined on the prototype, it will only be instantiated once. For null or primitive types (string, number, bool) this is not a problem. However for objects like in the third example, the OtherClass instance will not be unique for each new MyClass instance and be shared, risking unforeseen problems. Therefore, in order to not confuse those not aware of this detail, I consider this pattern as a whole bad practice.

Although not being recommended, the example provided above is given to provide better understanding of how JavaScript objects work, and for that occasional case where you really want to draw out that last bit of JavaScript performance.

Extending classes

To inherit from another class you need a small extend() utility function:

var MyClass = function() {
    MyBaseClass.call(this);    // call super
};

MyClass = extend(MyBaseClass, MyClass);

MyClass.prototype.doSomething = function(sArgument) {
    MyBaseClass.prototype.doSomething.call(this, sArgument);    // call super
};

/**
 * Class extension utility function
 * @param cBase The base class
 * @param fConstructor The constructor function for the new class
 */
function extend(cBase, fConstructor) {
    var cPrototype = new Function;
    cPrototype.prototype = cBase.prototype;
    fConstructor.prototype = new cPrototype;
    fConstructor.prototype.constructor = fConstructor;
    return fConstructor;
}

Here, MyClass inherits from MyBaseClass, and MyClass’s constructor invokes the parent object’s constructor. The doSomething() method shows how to call a base method.

You can check whether something is an instance of a certain class using the instanceof operator, e.g. return new MyClass() instanceof MyBaseClass ? 'yes' : 'no';.

Namespacing

Usually, an object will be ‘namespaced’ like so:

myNamespace = new function() {
    
    var MyClass = function() {
    };
    
    // export
    this.MyClass = MyClass;
    
};

Here a global myNamespace namespace object is created, and at the end the local MyClass class is exported as a member of the namespace object.

1. Reduced risk of breaking the trunk

Today I left an hour later than I liked to, because I had checked in some changes which turned out to be broken. Since Wednesday is my day off, I could not fix the problem first thing the next morning, and leaving it the way it was would be a big inconvenience to my colleagues.

The underlying problem is that with SVN, every time you check in it ends up in the shared repository. Because the trunk needs to be kept in a working state, this requires a lot of testing effort for every check-in. In practice, this testing often doesn’t happen thoroughly enough, and sometimes a broken change slips through.

With Mercurial, you commit your changes to a local repository that is not shared, and every once in a while you synchronise your local repository with the shared (trunk) repository. This relieves you of a lot of testing effort, as you only need to test thoroughly before sharing your changes with the main repository, rather than for each individual check-in.

In this case after finding that there still were some issues, I could’ve simply gone home without synchronising my latest set of changes with the server.

2. Narrowing down the source of problems

Usually I make small incremental commits. By doing this I keep the amount of uncommitted changes low, so that I can easily compare my current code with the last working state in the version control system.

At a certain point though I was working on a big change, and I had to hold back on committing intermediate results because I knew it wasn’t fully functional yet, after all we can’t have the trunk in a broken state. Yet because of this, every time something did not work any more it was very hard to find what changes exactly caused it.

Since with Mercurial commits are not shared with the main repository until you tell it to, I could’ve continued to do small commits, and saved myself a lot of debugging headaches.

3. Checking in the parts that are ready

One thing I always miss terribly when working with SVN is the ability to commit partial changes. Now admittedly this is strictly speaking not a Mercurial feature. Nevertheless TortoiseHg, the Windows and Linux shell extension for Mercurial, is the only tool I know of that has this feature.

Often you have some changes that you would like to commit, but you also have some other changes that are not ready yet. A pretty tedious process usually follows: you make copies of the changed files, revert the files, compare them with the copies and copy over the changes that you want to commit. Then you commit those changes and copy back the original files.

With TortoiseHg this is all much simpler. In the commit window you can activate and deactivate individual changes within files, and thus only select the changes that you want to commit. This would have been convenient when I took a break from refactoring to fix a bug that a colleague reported.

In summary, where Mercurial really outshines SVN is working on several things at once and making small, manageable commits. It also reduces testing and debugging overhead, and lessens the risk of broken changes ending up on the trunk.

Sounds compelling to me! :)

Let’s start with function. First we need to clarify the difference between a function declaration and a function expression. A function is called a function declaration when it appears like so:

function aaa() {}

A function is a function expression when it is used as part of an expression. Makes sense, no? :) Some examples:

var bbb = function() {}

ccc = function ddd() {}

Now before the JavaScript interpreter runs any code, it will start with gathering all function declarations. It creates local variables with their names, and assigns the compiled function objects to them. This means that function declarations can be called before they are declared, while function expressions can not.

Next, the interpreter will gather all var statements and create local variables for them. It will not initialize them yet though, the value will be undefined until the var statement is reached in normal execution of the code, which begins after this.

For example, the following code looks like it may have some issues. ccc is called before it’s defined, and you would think that if it is called ccc alerts “bbb is function”, not undefined. And if var aaa appears after the assignment, would aaa not be set on the global object instead of locally?

function test() {
    
    ccc();
    
    aaa = true;
    
    var bbb = function() {
        alert('window.aaa is ' + window.aaa); // alerts “window.aaa is undefined”
    };
    
    function ccc() {
        alert('bbb is ' + bbb); // alerts “bbb is undefined”
    }
    
    var aaa;
    
    bbb();
    
}

In reality this code is executed as if it were this:

function test() {
    
    var ccc = function() {
        alert('bbb is ' + bbb); // alerts “bbb is undefined”
    };
    
    var bbb = undefined;
    var aaa = undefined;
    
    ccc();
    
    aaa = true;
    
    bbb = function() {
        alert('window.aaa is ' + window.aaa); // alerts “window.aaa is undefined”
    };
    
    bbb();
    
}

So first ccc is defined as a local variable, then it is assigned the corresponding function object, then variables bbb and aaa are created and set to undefined, and after that the body continues to execute in code order, executing ccc (which is now available), assigning aaa and bbb their values and executing the latter.

Because of this you can do things in JavaScript which seem odd at first, but in practice are often very convenient, especially in combination with closures.

If you want to look up the details, see section 10.5 “Declaration Binding Instantiation” of the ECMAScript 5 specification.