The next item I need to address is object events. I have a mechanism for attaching event handlers to DOM objects, so when the user clicks a button, or changes the value of a text box, or does some other interaction with a DOM element, the View can handle that event. But then the View will need to fire its own event to notify a Controller object (yet to be created) that the user is attempting to accomplish some task.

For example, the user might click a Search button, or press the Enter key on a text box, both of which might fire the View’s “onSearch” event. A Controller listening for this event could then initiate the search. When the search is complete, the Controller could fire an event to indicate that the results are available. Maybe an “onSearchResults” event or something. Models will also need to fire events to notify other objects when data is loaded, changed, etc.

In fact, I figure there are very few objects that won’t need to fire events. Therefore, I decided to include events and event handling as a basic core functionality of all classes. This means revisiting the Class function and making some enhancements.

Here is the original Class function. If you are unfamiliar with it, you might want to review the original series about creating the Class object. It’s probably not necessary, but it might help you understand the changes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

LivingMachines.Class = function(init) {
 
	// Create constructor function that will check if we are inheriting, 
	// then call real constructor
	var cstr = function() {
		if (arguments[0] === inheriting) return;
		this.construct.apply(this, arguments);
	};
 
	// If we are inheriting, copy the prototype, otherwise assign a new prototype
	if (init.inherits) {
		cstr.prototype = new init.inherits(inheriting);
		cstr.base = init.inherits.prototype;
		delete init.inherits;	// Keeps it from being added to the prototype later
	};
 
	// Copy init properties to the prototype (adds/overrides base class methods)
	for (var p in init)
		cstr.prototype[p] = init[p];
 
	// Return the constructor function (this is the class)
	return cstr;
 
};

The basic premise here is that I only need to add the event methods to a base class. Any descendant classes will then automatically inherit those methods. As I see it, the methods will be createEvent (to add an event to the class), listenTo (to add an event handler to an event), unlistenTo (to remove an event handler from an event, and yes I know that “unlisten” not a real word, but it works), and fire (to execute all event handlers that are attached to an event).

Since I am going to allow multiple event handlers, I will need an array to hold the handlers (which are just functions that will be executed when the event is fired). I decided to create an object, called events, that will hold an array for each event of the class. This will be an instance object, and so will need to be added to the constructor (line 7, below).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

LivingMachines.Class = function(init) {
 
	// Create constructor function that will check if we are inheriting, 
	// then call real constructor
	var cstr = function() {
		if (arguments[0] === inheriting) return;
		this.events = { };    // To hold our arrays of event handlers
		this.construct.apply(this, arguments);
	};
 
	// If we are inheriting, copy the prototype, otherwise assign a new prototype
	if (init.inherits) {
		cstr.prototype = new init.inherits(inheriting);
		cstr.base = init.inherits.prototype;
		delete init.inherits;	// Keeps it from being added to the prototype later
	};
 
	// Copy init properties to the prototype (adds/overrides base class methods)
	for (var p in init)
		cstr.prototype[p] = init[p];
 
	// Return the constructor function (this is the class)
	return cstr;
 
};

Next, I need to add the event methods. Since all classes will have event capabilities, I simply need to add event methods to the class’s prototype if this is a base class, that is, if this is a class that is not inherited from any other class. This will ensure that all top-level classes have event capabilities, and those capabilities will pass on to all descendant classes through inheritance.

If a class inherits from another class, then the inherits property of the init argument will be set, and I’m already checking for it (line 12). So, I simply need to add an else to the if, and add the event methods there (lines 17-47, below).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

LivingMachines.Class = function(init) {
 
    // Create constructor function that will check if we are inheriting, 
    // then call real constructor
    var cstr = function() {
        if (arguments[0] === inheriting) return;
        this.events = { };    // To hold our arrays of event handlers
        this.construct.apply(this, arguments);
    };
 
	// If we are inheriting, copy the prototype, otherwise assign a new prototype
    if (init.inherits) {
        cstr.prototype = new init.inherits(inheriting);
        cstr.base = init.inherits.prototype;
        delete init.inherits;	// Keeps it from being added to the prototype later
    }
    else {
 
        // Since we are not inheriting, then we must add event methods,
        // otherwise they will be included via inheritance.
 
        cstr.prototype.createEvents = function(/* event */) {
            for(var i = 0, len = arguments.length; i < len; i++)
                this.events[arguments[i]] = [ ];
        };
 
        cstr.prototype.listenTo = function(obj, event, handler) {
            obj.events[event].push( { handler: handler, scope: this } );
        };
 
        cstr.prototype.unlistenTo = function(obj, event, handler) {
            var ev = obj.events[event];
            // Loop down, just in case handler was added multiple times (and will be removed multiple times)
            for (var i = ev.length - 1; i >= 0; i--) {
                if (ev[i].handler === handler)
                    ev.splice(i, 1);     // Deletes one element starting at index i
            }
        };
 
        cstr.prototype.fire = function(event, data) {
            var handlers = this.events[event];
            for (var i = 0, len = handlers.length; i < len; i++) {
                var h = handlers[i];
                h.handler.call(h.scope, this, data);
            }
        }
    }
 
    // Copy init properties to the prototype (adds/overrides base class methods)
    for (var p in init)
        cstr.prototype[p] = init[p];
 
    // Return the constructor function (this is the class)
    return cstr;
 
};

The first event method, createEvents (line 22) takes a variable number of arguments. Each argument is the name of an event to be added to the class. It simply loops through each argument (line 23) and adds the name of the event to the events object (line 24). Each event is initialized to an empty array, and it’s these arrays that will hold all the handlers for a particular event.

The createEvents method should be called from the construct method of a class. I had to do it this way since each event handlers array has to be associated with a class instance, and not the class itself. So, for example, executing createEvents('onSave', 'onCancel') will add onSave and onCancel as properties to the events object (the one added in line 7). These properties are initialized as empty arrays. Since these are instance properties, each instance of the class can have a different set of handlers.

The listenTo method (line 27) is used to add an event handler to the appropriate event handler array. It takes three arguments, obj (the object that has the event to listen to), event (the name of the event to listen to), and handler (the function that will handle the event). It then adds the handler to the given event handlers array of the object that has the event (line 28). Note that this is actually pushing the handler function and this as a scope object into the handlers array. I will talk about why I am doing this when I describe the fire method.

The unlistenTo method (line 31) is used to remove a specific event handler from the list of handlers. It takes three arguments, obj (the object that has the event we are no longer interested in), event (the name of the event that the handler is to be removed from), and handler (the previously added function that is to be removed). This method first grabs the handlers list for the given event (line 32). Next, it loops backward through the handlers list (line 34). I typically loop backwards when removing items from a list. The reason is that I don’t have to adjust the index after an item is removed. If I’m on index 3, then whether or not I remove the item at index 3, the next index is always 2. If I were to loop forward, and I removed the item at index 3, then the next item to check is still index 3 (since the item at index 4 has moved down to 3). I also would need to adjust the stop index since the size of the array changed. When you loop backward, the stop index is always 0. Anyway, enough of that digression… It loops backward through the handlers list and if the function passed in matches one in the list (line 35) then it is removed (line 36). You can delete an array element with the delete keyword, but that will leave a gap in the array indexes, whereas using splice reindexes the array. Hence my use of splice over delete.

The last event method is the fire method (line 40). It takes two arguments, event (the event to be fired) and data (an object containing any data about the event). This method loops through all of the event handlers for the given event (line 42) and executes each one (line 44). This is where we need to be concerned with scope. If I were to simply call the handler function, then the this variable inside that function would point to the current object. That is, the this variable inside the handler function would point to the object that is firing the event. But what I really want is for the this variable inside the handler function to point to the object that is handling the event. That’s why I pass in the this variable as the scope object to the listenTo method when the handler is set up (line 28). Then, in the fire method, I can call the handler using that scope object, ensuring that the this variable in the handler is set to the object handling the event (line 44).

Here is a simple example of how to use this event mechanism.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

var VariableSwitch = LivingMachines.Class({
    construct: function() {
        this.switchId = 'A';
        this.level = 0;
        createEvents('onLevelChanged');
    },
 
    set: function(level) {
        this.level = level;
        this.fire('onLevelChanged', level);
    }
});
 
var LightBulb = LivingMachines.Class({
    construct: function(sender, level) {
        this.brightness = 0;
    },
 
    setBrightness: function(sender, level) {
        this.brightness = level;
        alert('Brightness was set by switch ' + sender.switchId);
    }
});
 
var variableSwitch = new VariableSwitch();
var lightBulb = new LightBulb();
 
lightBulb.listenTo(variableSwitch, 'onLevelChanged', lightBulb.setBrightness);
 
variableSwitch.set(5);

I’m creating two sample classes here. The first is VariableSwitch (line 1-12). It has an switchId property so we can tell which switch it is (line 3), a level property to indicate the current level of the switch (line 4) and an onLevelChanged event that will be fired when the switch level is changed (line 5). This class also has one method, set (line 8), that will change the level of the switch (line 9) and fire the onLevelChanged event (line 10).

The second class is LightBulb (line 14-23). It has a single property, brightness (line 16) to indicate the current brightness of the bulb. It also has one method, setBrightness (line 19) that will set the brightness property to a given level (line 20) and alert the ID of the switch that caused the brightness to change (line 21). This function is an event handler. Notice the two arguments. sender is the object that sent the event, which will be an instance of VariableSwitch in our case, and level is the data object of the event.

Next I create an instance of VariableSwitch and LightBulb (lines 25 and 26). Then I attach the event handler (line 28). The lightBulb object will listen to the onLevelChanged event of the variableSwitch object. The lightBulb.setBrightness method will be executed when the event is fired.

Finally, I set the level of the variableSwitch (line 30) object. This will cause the onLevelChanged event to be fired, and the setBrightness event handler method will be executed, alerting that “Brightness was set by switch A”.

And voilà, JavaScript classes now have event capabilities.

So, I have some functions that will add DOM elements to the page, allowing me to build a View. Now, to allow the user to interact with the View, I need to add event handlers to the DOM elements.

There are basically three ways of doing this, one for W3C-compliant browsers, one for Internet Explorer, and one using browser-independent JavaScript. Personally, I prefer to use the lowest-common denominator when writing JavaScript. If I can avoid if blocks that cycle through browser-specific code, I’ll be much happier.

Browsers that follow the W3C standards (such as Firefox) use the addEventListener function to attach handlers to DOM elements. IE uses the attachEvent function instead. There are some differences between these two, but both allow for multiple handlers to be attached to a single event through multiple calls to the browser-appropriate function. The IE version, however, has one serious drawback: the this variable in the handler function always refers to the window object, rather than the DOM element that the handler is attached to like the other attachment mechanisms do. So while I could easily use browser detection to determine which function to use to attach handlers, I would still be stuck with the limitations of IE when that version was used.

The browser-agnostic version is to simply attach a handler function to the appropriate JavaScript event property directly. For example,

1
2
3
4

var btn = document.getElementById('submitButton');
btn.onclick = function() {
    alert('I have been clicked!');
};

The major drawback to this method is that you can only attach one function to the event. This is a limitation easily gotten around, however, unlike IE’s inability to give us a useful this variable in the handler. The benefit to this method is that it works on all browsers (even IE will give us a correct this variable inside the handler if we use this mechanism).

Now another drawback to event handling in general is the fact that the this variable will always point to the DOM element that the handler is attached to. Yeah, I know I said it’s a drawback when it doesn’t point to the element, but while it is useful to know this information, it does make event handling a bit misleading when using object-oriented programming. Consider the following:

1
2
3
4
5
6
7
8

var OkButton = {
    okClicked: false,
    handleClick: function() {
        this.okClicked = true;
    }
};
 
document.getElementById('ok-button').onclick = OkButton.handleClick;

Here I’m declaring a new object called OkButton (line 1). It has a property called okClicked (line 2) which should be set to true when the OK button is clicked. There is a handleClick function (line 3) which will be executed when the OK button is clicked, and will set the okClicked property to true (line 4). Line 8 attaches the handleClick function to the OK button.

Look carefully at line 4. What does the this variable refer to? Intuitively you would expect that it refers to the OkButton object, right? After all, that is typically what we use this for. But in this case, because the handleClick function is being executed from an event, the this variable will refer to the DOM element that the handler is attached to, not to the object that the handler function belongs to. This, to me, is a bit misleading and confusing. To make matters worse, if you call OkButton.handleClick directly, then the this variable will point to the OkButton object (since it was not executed from an event). Ugh, I hate ambiguity.

I would like to change all that, so that I can write JavaScript that is more intuitive and less ambiguous. I want the this variable to always refer to the object, not the DOM element, though I don’t want to lose the reference to the DOM element since it will be useful to have. I also want to be able to attach multiple handlers to a single event.

I have two functions to make that happen. One to attach an event to a DOM element, and another to dispatch an event to one or more event handlers.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

LivingMachines.View = LivingMachines.Class({
 
    /* ... Lots of code excluded here for brevity ... */
 
    addDomHandler: function(elem, event, fn)
    {
        var ev = '_'+event;       // Add underscore to event name (e.g. _onmousedown, _onkeypress, _onclick)
        if (!elem[ev])
            elem[ev] = [ ];
        elem[ev].push(scopedFn(this, fn));
        elem[event] = this.dispatchDomEvent;
    },
 
    dispatchDomEvent: function(ev)
    {
        // "ev" is the event object
        // "this" is the element that this event handler is attached to
        // "elem" is the element that initiated the event (will be a child of "this", or might be "this")
 
        ev = ev || window.event;                      // IE uses global window.event
        var elem = ev.target || ev.srcElement;        // IE uses ev.srcElement
        var handlers = this['_on'+ev.type];           // e.g. ev.type = mousedown, keyup, click, etc.
        var result = true;
        for (var i = 0, len = handlers.length; i < len; i++) {
            result = handlers[i](this, elem, ev) && result;
        }
        return result;
    }
 
});

Obviously, these functions are part of the View class (line 1).

The first function is the addDomHandler method (line 5). This is used to attach an event handler function to a DOM element event. It takes three arguments. elem is the DOM element that we want to attach the event to. event is the name of the event (onclick, onmousedown, etc). These event names must match to DOM element events, so they must be in all lowercase letters. And fn is the handler function to be executed. If you want to add more than one handler to an event, you will need to call addDomHandler once for each handler to be added.

When the addDomHandler function is executed, it first adds an underscore to the event name (line7). So “onclick” becomes “_onclick”, for example. It then checks to see if the underscored name is a property of the DOM element (line 8). If it isn’t it creates the property as an empty array (line 9). This is the property that the handlers will be added to. This is what allows multiple handlers on a single event.

Next, the event handler function is pushed onto the handlers array property that was just created (line 10). The scopedFn function is part of the JavaScript Extensions I created several months ago. Basically, it ensures that a function is always executed in the scope of a given object. In other words, it ensures that the this variable in a function always points to a certain object. In this case, that object is the View (the this argument, which points to the View, is passed in to scopedFn). This is how the this argument in the handler is always guaranteed to reference the View object, and never the DOM element. Don’t worry, we’ll still have access to that DOM element. You’ll see how in a moment.

The final step this function does is to attach an event handler named dispatchDomEvent to the event itself (line 11). Note that we are using the event name that was passed in (not the underscored version). This is the actual event of the DOM element, the one that gets fired when the event occurs.

So at this point, we have a DOM element that has a property (such as “_onclick”, “_onmousedown”, “_onkeypress”, etc.) that is an array of scope-corrected handler functions. The DOM element’s event property (such as “onclick”, “onmousedown”, “onkeypress”, etc.) will execute the dispatchDomEvent method.

Now let’s take a look at what happens when an event is fired, causing the dispatchDomEvent to be executed. Remember, it will be executed when an event is fired. First, it get the correct event object. In most browsers, an event object is passed directly into the function (line 14). In Internet Explorer, the window object contains the event information. I’m using the OR syntax to get the correct value for ev (line 20). When an OR is executed, if the first expression has a value (is not null, undefined, an empty string or zero) then that value is returned from the OR operation and the second expression is never evaluated. If, however, the first expression evaluates to a “nothing” value, then the second expression is evaluated and returned from the OR operation. This ensures that the ev variable always points to the event object, regardless where it comes from.

Next, it grabs the target or source element (line 21). This is the element that the user interacted with, not necessarily the element that the handler is attached to. Why is that? Because events bubble. For example, we can attach an event handler to a DIV element. If the user clicks on an element within that DIV element, the event will bubble up the DOM hierarchy until it finds an event handler. In this case, the one attached to the DIV. So the handler attached to the DIV will be executed, but the source of the event is the element that the user actually clicked on. Most browsers keep this source element in the target property of the event object. Internet Explorer keeps it in the srcElement property. We use the same OR technique as before to get the correct source element.

Next, the function gets a pointer to the event handlers array that was added to the DOM element in the addDomHandler function (line 22).

Events can return true or false. If they return false, it will prevent the default action from happening for a given element. For example, a form submit button, when clicked, will submit the form unless the JavaScript onclick event handler function returns false. This will allow us to submit a form via AJAX, for example. Because we have multiple event handlers attached to the event, we need to track the value they each return. If any one of them returns false, then the dispatchDomEvent function (which is the function actually attached to the event) should return false as well. The result variable allows tracking of the event handler results (line 23).

Finally, it loops through all the handler functions (line 24). Remember that these are all scope-corrected functions, so when they execute, the this variable in each will point to the View object. However, since the dispatchDomEvent method is executed from an event, the this variable in that function (the one we’re looking at right now) will point to the DOM element that the handler was attached to. This is important as we look at actual execution of the handler functions (line 25). handlers points to the array of event handlers, and i is the looping index used to access each in turn. Since each array element points to a function, we can execute it using parenthesis, just like we do any function: handlers[i]( /* arguments */ ). The this variable is passed in as the first argument to the handler function. Remember, it points to the DOM element that the dispatchDomEvent function is attached to. The next argument passed in is the element that initiated the event. That is, the element that the user actually interacted with. The last argument passed in is the ev (event) object. Note that the function is ANDed with the current result value. If any event handler function returns false, then result will be permanently set to false for the remainder of the loop.

The last thing the function does is return the value of result (line 27).

Looking at how the event handler functions are executed, this means that event handler functions should have the following format:

1
2
3
4
5
6
7
8
9
10
11

MyView = LivingMachines.Class({
 
    inherits: LivingMachines.View,
 
    handlerFn: function(sender, source, ev) {
        // "sender" is the DOM element that the handler was attached to (the element that sent the event)
        // "source" is the DOM element that the user interacted with (the source of the event)
        // "ev" is the event object
        // "this" points to an instance of MyView
    }
});

And there you have it. An event handlers mechanism that allows multiple event handlers to be attached to a single event, corrects the this variable to always point to the View object, and gives us access to the DOM element that the handler is attached to and the DOM element that initiated the event.

Creating DOM elements like text and password INPUTs, BUTTONs and TEXTAREAs is pretty simple. Creating a SELECT element, however, proved to be a little more tricky thanks to a quirk in the Opera browser.

Let’s look at a SELECT tag. It’s pretty simple, really. It has a SELECT tag with a number of OPTION tags inside it.

1
2
3
4
5

<select id="colors" name="rgb_color">
    <option value="r">Red</option>
    <option value="g" selected="true">Green</option>
    <option value="b">Blue</option>
</select>

Each OPTION tag has a value attribute. If this particular SELECT element was submitted from a FORM, it would send to the server the name ‘rgb_color’ with the value ‘g’, since that’s the option that is currently selected.

From this example, it would seem that I could create a SELECT element, then add the OPTION elements to it with the selected attribute set for the appropriate option. Using the View’s DOM rendering functions, that would look something like this (in View.js).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

select: function(id, selected, options, props)
{
    if (!props) props = { };
    props.id = id;
 
    var optionElements = [ ];
 
    if (options) {
 
        for (var value in options) {
 
            var optionProps = {
                selected: value == selected,
                value: value
            };
 
            optionElements.push( this.createElement('option', optionProps, [options[value]]) );
        }
    }
 
    return this.createElement('select', props, optionElements); 
}

The first argument is the id of the SELECT element. The selected argument is the value of the currently selected OPTION element. This will allow us to set an option as already selected. The options argument is an object that defines which OPTIONs are displayed in the SELECT drop down list. The last argument is any additional properties to be set on the SELECT element. So, to create the SELECT element in our example above, we would make the following call.

1
2
3
4
5

myView.select('colors', 'g', {
    r: 'Red',
    g: 'Green',
    b: 'Blue'
}, { name: 'rgb_color' } );

When the select method is executed with the arguments in this call, it will loop through each of the options (lines 10 to 18 in the select function source code, above) and create an optionProps object for that option (lines 12 to 15). The optionProps object contains the value (which is the property name in the options object, ‘r’, ‘g’ or ‘b’ in this example) and the selected property, which is set to true if the selected argument matches the value of the current option. Next, it uses the createElement method to create the OPTION element (line 17), passing in the option text as a child (so that it appears between the OPTION’s open and close tags). The third argument of createElement expects an array, which is why the argument is surrounded in square brackets. Finally, the new option is added to the optionElements array using the array’s push function.

Now that the OPTION elements are created, the only thing left to do is create the SELECT element, and add the OPTION elements to it. Using the createElement function, this is very simple (line 21).

And it works like a charm in all browsers except Opera. For some reason, Opera does not like the selected property for the OPTION element. I’ve tried different variations, but none seem to work.

The solution is to use the selectedIndex property of the SELECT element. This is supported by all browsers.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

select: function(id, selected, options, props)
{
    if (!props) props = { };
    props.id = id;
 
    var optionElements = [ ];
    var selectedIndex = 0;
 
    if (options) {
 
        for (var value in options) {
 
            var optionProps = {
                //selected: value == selected,  // Not supported by Opera
                value: value
            };
 
            if (value == selected)
                selectedIndex = optionElements.length;
 
            optionElements.push( this.createElement('option', optionProps, [options[value]]) );
        }
    }
 
    var sel = this.createElement('select', props, optionElements);
    sel.selectedIndex = selectedIndex;
 
    return sel;
}

Line 7 adds a new variable to track the selected OPTION element, and is defaulted to zero (the first OPTION element). In line 14, I’ve removed the selected property, as it will not be used. Line 18 checks if the current option’s value matches the selected argument and, if it does, sets the selectedIndex appropriately (line 19). Line 25 creates the SELECT element, and line 26 sets the selectedIndex of the SELECT element. I have to set the selectedIndex after creating the element since the current version of createElement applies the props object before the child OPTION elements are added, and you can’t set selectedIndex when there are no OPTION elements. If this were not the case, if the props object was applied to the element after all OPTION elements were added, then I could just add selectedIndex to the props object. Hmm. Maybe a change to createElement is in order.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

createElement: function(tag, props, elements)
{
    // Create the element
    var elem = document.createElement(tag);
 
    // MOVE THIS BLOCK DOWN TO LINE 24
    //window.copy(props, elem, function(data) {
    //    if (data.prop == 'cssFloat' && !elem.cssFloat)
    //        data.prop = 'styleFloat';
    //});
 
    // Add any inner element to the newly created DOM object        
    if (elements) {
 
        for (var i = 0, len = elements.length; i < len; i++) {
            if (isString(elements[i]))
                elem.appendChild(this.element(elements[i]));
            else if (elements[i])   // Make sure not null or undefined
                elem.appendChild(elements[i]);
        }
    }
 
    // Apply the properties to the element, correct property names where necessary (Globals.js)
    window.copy(props, elem, function(data) {
        if (data.prop == 'cssFloat' && !elem.cssFloat)
            data.prop = 'styleFloat';
    });
 
    // Lastly, return our new DOM element
    return elem;
}

That’s better. Now the props object will be applied after all child elements have been added. All unit tests still pass with this change. Will it break something else or cause problems in the future? Maybe. But for now, it simplifies the code for the select method, since I no longer need to track selectedIndex separately. Instead, I can update it in the props object directly. This also allows the selectedIndex property to be passed in to the props argument and have it be set correctly. That gives another option for setting the currently selected option other than the selected argument.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

select: function(id, selected, options, props)
{
    if (!props) props = { };
    props.id = id;
 
    var optionElements = [ ];
 
    if (options) {
 
        for (var value in options) {
 
            var optionProps = {
                value: value
            };
 
            if (value == selected)
                props.selectedIndex = optionElements.length;
 
            optionElements.push( this.createElement('option', optionProps, [options[value]]) );
        }
    }
 
    return this.createElement('select', props, optionElements);
}

Note that the selectedIndex variable has been removed. If the option value and the selected argument values match, then line 17 sets the selectedIndex property of the props object. Thanks to JavaScript’s mutable objects, if this property doesn’t already exist, it will be created. Line 23 is the call to the createElement method to create the SELECT element and set the properties.

If you compare the original version (the one that didn’t work with Opera) to this version, one line of code was deleted and two were added, for a net result of one additional line of code. Not too bad when trying to correct browser incompatibilities.

So, there’s the final version for now. Of course, this does not support multiple option selects. That’s for another time, I think.

I’ve made another slight, but significant, change to the way in which DOM elements are created by the View. Going back to my original approach of building DOM elements from HTML strings, it made sense to refer directly to HTML and CSS attributes. But now that I’m creating DOM elements directly through document.createElement, there is no need to use HTML attributes, and I can just use the DOM element properties.

The first change, then, was to rename attribs (attributes) in all DOM element rendering functions to props (properties).

Next, I updated the view’s createElement function (in View.js, not document.createElement). This is the original version.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

createElement: function(tag, attribs, elements)
{
    // Create the element
    var elem = document.createElement(tag);
 
    // Add the attributes to the element. HTML attribute names do not always match
    // the name that the DOM uses, so we check for them here.  This may not be all
    // of them yet!
    for (var a in attribs) {
        attr = a.toLowerCase();
        if (attr == 'class')
            elem.className = attribs[a];
        else if (attr == 'for')
            elem.htmlFor = attribs[a];
        else
            elem.setAttribute(a, attribs[a]);
    }
 
    // Add any inner element to the newly created DOM object        
    if (elements) {
 
        for (var i = 0, len = elements.length; i < len; i++) {
            if (isString(elements[i]))
                elem.appendChild(this.element(elements[i]));
            else if (elements[i])   // Make sure not null or undefined
                elem.appendChild(elements[i]);
        }
    }
 
    // Lastly, return our new DOM element
    return elem;
}

In the new version (below) note that the second argument has been changed from attribs to props. It now expects DOM element property names, not HTML attribute names. This means I need to use names like className instead of class, and htmlFor instead of for. Since this function no longer has to do attribute name to property name conversions (since I’m now passing it property names and not attribute names), lines 6 through 10 (lines 6 through 17 in the original version) have been updated to use the copy function (in Globals.js, part of the JavaScript Extensions). I’ll explain that third argument to the copy function, the anonymous function with the data argument, in a moment.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

createElement: function(tag, props, elements)
{
    // Create the element
    var elem = document.createElement(tag);
 
    // Apply the properties to the element, correct property names where necessary (Globals.js)
    window.copy(props, elem, function(data) {
        if (data.prop == 'cssFloat' && !elem.cssFloat)
            data.prop = 'styleFloat';
    });
 
    // Add any inner element to the newly created DOM object        
    if (elements) {
 
        for (var i = 0, len = elements.length; i < len; i++) {
            if (isString(elements[i]))
                elem.appendChild(this.element(elements[i]));
            else if (elements[i])   // Make sure not null or undefined
                elem.appendChild(elements[i]);
        }
    }
 
    // Lastly, return our new DOM element
    return elem;
}

There are some special cases to handle when copying properties, so I needed to alter the copy function, too. These special cases are due to browser differences. Like the fact that all browsers use the style.cssFloat property, but IE uses style.styleFloat. If I’m going to use the copy function, a change is required to handle these special scenarios. But since the copy function is an extension, I want to keep the change generic.

The copy function originally took two arguments. The first was the source object, and the second was the destination object. Now, there is a third argument. This argument is a function that will be called for every property in the source object just before it is added to the destination object. This allows the property name, value or data type to be changed before it is copied to the destination object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

window.copy = function(src, dest, fn)
{
    if (!dest) 
        dest = {};
    for (var prop in src) {
        var value = src[prop];
        var type = window.typeOf(value);
        if (fn) {
            var data = { prop: prop, value: value, type: type };
            fn(data);
            prop = data.prop;
            value = data.value;
            type = data.type;
        }
        if (type == 'object') {
            if (!dest[prop])
                dest[prop] = {};
            window.copy(value, dest[prop]);
        }
        else if (type == 'date') {
            dest[prop] = new Date(value.getTime());
        }
        else if (type == 'array') {
            dest[prop] = value.slice();
        }
        else {
            dest[prop] = value;
        }
    };
 
    return dest;
};

Lines 8 through 14 check if a callback function (fn) was passed in and, if so, creates an object that has three properties: the property name, value and data type. This data object is then passed to the callback function. Why use an object, rather than passing the values in as three separate arguments? Because objects are passed by reference. This means that the callback function data object points to the same data object as the copy function, so changing a value in the callback function also changes that value in the copy function (since both are pointing to the same data object). If I was passing in three separate arguments, they would be local only to the callback function, so changing their values would not change them in the copy function.

If you look back at the modified code for the View’s createElement function above, you’ll see that the callback function checks to see if the property is cssFloat and, if it is, checks to see if that property exists in the DOM element. If it doesn’t, it means we are running in IE and must use the styleFloat property name. In that case, it changes the property name.

So adding the callback function to copy allows me to change property names to suit different browsers, but still keep the copy function generic.

The other advantage to using the copy function that that it handles nested objects. So, specifying styles can be done with a props object like the following passed to the View’s createElement function. Note that these are DOM element property names, not CSS attribute names.

1
2
3
4
5
6
7
8

{
    id: 'someId',
    style: {
        display: 'block',
        backgroundColor: '#cccccc',
        cssFloat: 'right'
    }
}

So, not any major changes here, but they are significant from the perspective of using the View. It also simplifies the View’s createElement function a little more, but still keeps it flexible.

If you recall from my first stab at creating the MVC View, I had a method of the View class called tag that would take some arguments and create a DOM element from them. This tag method would be called from higher-level methods designed to make creating a DOM element for the View easier. For example, the form method below (also a member of the View class) is used to create a FORM element. The tag method is called in line 9, and it does the actual work of creating the FORM element:

1
2
3
4
5
6
7
8
9
10

form: function(id, url, method, attribs /*, elements*/)
{
    if (!attribs) attribs = { };
 
    attribs.id = id;
    attribs.action = url;
    attribs.method = method;
 
    return this.tag('<form %a></form>', attribs, this.extractArgs(arguments, 4));
}

Now, let me explain a few things. First, I had envisioned calling tag with more options, like this:

1

return this.tag('<form id="%i" action="%v" %a>%e</form>', id, url, attribs, elements);

The %i would be replace with the id, %v would be the value (the url argument in this example), %a would be additional attributes, and %e would be the other elements contained by this element. All elements would include these arguments, so an INPUT element would be created something like this:

1

return this.tag('<input id="%i" value="%v" %a />', id, value, attribs, null);

What I realized, however, was that %i and %v were superfluous, and could be eliminated. Since these were just attributes, they could simply be added as part of %a. And this is exactly what I did in the first version of the tag function that I posted.

The %e I realized would require me to work strictly with HTML strings. In other words, I could replace the %e with an HTML string, but not with an actual DOM element (I can’t insert an object into the format string). The better plan, I figured, was to convert any HTML strings into DOM elements, then add the DOM elements to the containing element created by the tag method. That gave me more flexibility with what I passed as elements to the tag method. I could pass in an HTML string and convert it, or just pass in a DOM element. It also eliminated the need for the %e. Hence it was also dropped in the previous version of the tag method.

That left a much simpler structure, though it still had its roots in working with HTML strings. The attributes were expected to be passed into the tag method as an object of name/value pairs. That object would then be converted into an attributes string, and the %a in the format argument would be replaced with it. So essentially, a call to the tag method, like in line 9 below…

1
2
3
4
5
6
7
8
9
10

text: function(id, value, attribs) 
{
    if (!attribs) attribs = { };
 
    attribs.type = 'text';
    attribs.id = id;
    attribs.value = value;
 
    return this.tag('<input %a />', attribs);
},

…would result in the following code being executed inside the tag method…

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// Convert the attribs object to an HTML string.
var attribsHtml = '';
var singleAttrib = '.compact.checked.declare.readonly.disabled.selected.defer.ismap.nohref.noshade.nowrap.multiple.noresize.';
for (var a in attribs) {
    if (singleAttrib.indexOf('.' + a + '.') > -1) {
        if ((attribs[a] == 1) || (attribs[a] == true) || (attribs[a] == 'true') || (attribs[a] == a))
            attribsHtml += ' ' + a;
    }
    else {
        if (attribs[a]) // Make sure its not null.
            attribsHtml += ' ' + a + '="' + attribs[a] + '"';
    }
}
 
// Insert the attributes into the tag format
format = format.replace('%a', attribsHtml);

…which would create an attributes string (lines 1-13) that would then be inserted into the format argument at the %a position (line 16). In this particular example, this would result in an HTML string like the following:

1

format = '<input type="text" id="username" value="jdoe" />'

I could then take this HTML string, this complete tag, and convert it into a DOM element with a call to the element method. In fact, this is exactly what the tag method did next.

1
2

// Convert the HTML string to a DOM object
var elem = this.element(format);

So that’s where it stood as per my last post, and up until recently, it worked nicely.

However, I began working on a method to create a TABLE element. I got as far as attempting to create the TR and TD elements. Turns out, these cannot be created anywhere except inside a TABLE element, which meant creating them using the tag method was impossible. You see, the element method (which the tag method uses to actually create the DOM element) creates a DIV, sets the innerHTML of the DIV to the HTML string that was created, then extracts the DOM element that the browser created from the HTML. But TR and TD elements can’t sit inside a DIV element, so the browser (at least Firefox) will not create them using the element method.

I really dislike making special cases and wanted to avoid that if at all possible. In other words, I didn’t want to check if the tag passed in was a TR or a TD and then work some different magic to create them as DOM elements. I wanted to use the same mechanism, regardless of the element being created.

I could create the TABLE element as a single string, with all the TR and TD elements inside it, but that would mean separate code to create the attribute strings, or pulling the attribute string generating code into a separate method. It would also mean I could wind up concatenating a huge HTML string, depending on how big the table was. Also, in order to keep the same mechanism where the programmer could pass in HTML strings or DOM elements, I would potentially have to convert a DOM element (one that might appear in a table cell, for example) into a string so that I could build it into the table. The more I thought about it, the more convoluted the whole processes seemed.

It was at this point that I realized five things. First, all the tags had the same format: '<tag %a></tag>'. Only the tag name was different. Second, any element can be created using the document.createElement function, even if that element can only sit inside specific other elements (like TR and TD can only sit inside a TABLE element). Third, all you need is the tag name to use document.createElement. Fourth, attributes can be added directly to a DOM element; they don’t need to be name/value pair strings. Fifth, I really didn’t like the name “tag” for the method, since it does not describe what the method really does.

So, I set out to refactor the tag method. First, I changed the name of the method to createElement, which more accurately describes what it does. Next, I
renamed the first argument from format to tag. Now, it expects only a tag name, not a tag format. And %a is no longer needed.

1
2
3
4

// Original
tag: function(format, attribs, elements)
// New
createElement: function(tag, attribs, elements)

So, the part of the form method that calls the tag method changes, too.

1
2
3
4
5
6
7
8
9
10
11
12
13

form: function(id, url, method, attribs /*, elements*/)
{
    if (!attribs) attribs = { };
 
    attribs.id = id;
    attribs.action = url;
    attribs.method = method;
 
    // Original
    return this.tag('<form %a></form>', attribs, this.extractArgs(arguments, 4));
    // New
    return this.createElement('form', attribs, this.extractArgs(arguments, 4));
}

I still have concerns about the method name. I can see where some people would confuse the View’s createElement method for the document’s createElement function. They are not the same, but the name accurately describes what they do. So for now, I will leave it with the new name.

Incidentally, if you are not familiar with the extractArgs method, you can learn about it in my first post on creating the MVC view.

Finally, the tag method, now renamed to createElement, got some internal changes as well. It now uses the document.createElement function to create elements, and it adds attributes directly to the newly created DOM element. The following is the updated function in its entirety.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

createElement: function(tag, attribs, elements)
{
    // Create the element
    var elem = document.createElement(tag);
 
    // Add the attributes to the element. HTML attribute names do not always match
    // the name that the DOM uses, so we check for them here.  This may not be all
    // of them yet!
    for (var a in attribs) {
        attr = a.toLowerCase();
        if (attr == 'class')
            elem.className = attribs[a];
        else if (attr == 'for')
            elem.htmlFor = attribs[a];
        else
            elem.setAttribute(a, attribs[a]);
    }
 
    // Add any inner element to the newly created DOM object        
    if (elements) {
 
        for (var i = 0, len = elements.length; i < len; i++) {
            if (isString(elements[i]))
                elem.appendChild(this.element(elements[i]));
            else if (elements[i])   // Make sure not null or undefined
                elem.appendChild(elements[i]);
        }
    }
 
    // Lastly, return our new DOM element
    return elem;
}

First, it creates the DOM element (line 4). Then it adds the attributes to the element (lines 6-17). It is expected that these attributes are passed in with names that map to HTML attributes. The DOM property names may be different. For example, the HTML class attribute maps to the DOM element className property. I haven’t gone through all of the attributes yet, so this is probably not a complete list. As a bonus, now that I’m not creating a string of attributes, the code is much simpler.

The rest of the method is the same as the original, and uses the element method where necessary to convert HTML strings into DOM elements. I think this will be fine since it is unlikely that we will be passing HTML strings in for inner elements that cannot be created inside a DIV element. The table rendering method takes care of creating those elements that can only appear inside a TABLE element, and anything that we might pass in to be created inside a TD element should be able to be created inside a DIV, just the way the element method does it.

In my next post, I’ll take a closer look at that table method that started this whole refactoring process. For those who are interested in taking a look at it now, it’s available if you download the source code.

One final note. The test scripts for this are by no means complete and are, quite frankly, rather sloppy at the moment. I’ll get them cleaned up soon.

But, alas, I don’t always do it. Like when I posted the code for my first stab at creating the MVC View. Turns out, there was a problem running the code on Internet Explorer.

The problem was with generating the unique id for the View when one was not given in the constructor. The initContainer function would generate a unique id for you using the getTime function, like so:

1
2

if (!elem) 
    elem = 'view' + (new Date()).getTime();

If elem was not passed in, or was passed in as null, then this would create a new date object and get the time. new Date() should return a new date object with the current date and time, since we are not passing in any arguments. The getTime function returns the number of milliseconds since January 1, 1970. Theoretically, then, each call to getTime should return a new number, since we will not be creating Views within one millisecond of each other. And this works just fine on all browsers except Internet Explorer. Seems IE always returns the same value for getTime. That is unless you get the value, then display it in an alert box. In that case it does function properly. But that’s not a very user-friendly solution.

So, I came up with a solution that uses a static class variable. After creating the LivingMachines.View class, I added a static variable called nextId (line 5).

1
2
3
4
5

LivingMachines.View = LivingMachines.Class({
    /* Lots of code excluded for brevity */
});
 
LivingMachines.View.nextId = 0;

I then use this static variable to create the unique id’s for my Views in initContainer.

1
2

if (!elem) 
    elem = 'view' + LivingMachines.View.nextId++;

This creates the View id by using the value of nextId, then incrementing that value by 1 so that it’s ready for the next View to be created (hence the name nextId and not currentId).

So, there you have it, static class variables and a fix for IE. And now I know to avoid getTime in IE.

I am currently working on expanding the View’s functionality, and now I have to go fix another IE problem that has cropped up with some of the new code that I am writing. Actually, since it’s after 1 am here, I probably need to go to bed.

OK, so here’s my first stab at creating an MVC View in JavaScript. It doesn’t do much yet (especially since I have no Controller or Model to integrate with), but I think you’ll get the idea of where I’m going with this. Whether its the right way to go or not remains to be seen. Anyway, here it goes.

I’m creating a View class, using the Class function I worked so diligently on a couple months back. Yeah, I’m finally putting that thing to some use.

1
2
3
4
5
6
7
8
9
10
11

LivingMachines.View = LivingMachines.Class({
 
    construct: function(elem, tag)
    {
        this.container = null;
        this.initContainer(elem, tag);
    },
 
    /* More code goes here */
 
});

The construct method is, of course, the constructor for the class. It simply creates a new property named container that points to the DOM element that will contain the view. Typically, this will probably be a DIV element. Incidentally, whenever I talk about an “element” I am always referring to a DOM element. Unless I’m talking about arrays, in which case I will be referring to an array element. If I’m talking about an array of DOM elements, I will always be sure to clarify. Got it? OK.

You’ll notice that the constructor takes two arguments, elem and tag. Both are optional. The first argument is the id of an existing or non-existing element, or the actual element itself, that is to be used as a container for the View. If we are passing in the id of an element to be used as a container, but no container element with that id exists, then the tag argument tells the View what type of element to create (DIV, FORM, SPAN, etc.). If no tag argument is passed in, then it assumes a DIV element. If the element does not exist, it will be created with the given id. If no id or tag is passed in, then a unique id is generated, a DIV is automatically created with that id, and the DIV is appended to the document body. In short, we have many ways to get a container for our View.

But the constructor does none of this. It just passes the arguments on to the initContainer method, and its this method does what I just described above. The constructor just takes all the credit. You create the View and viola, you have a container element for it. At some point I may separate these. Would you ever want to construct a View, then at some point in the future get the container for it? Maybe. Possibly. As I think about it, most probably. But I’m not making that change yet. Anyway, here’s the initContainer method. The code is pretty straight-forward, I think. Just remember that elem is either an id or a DOM element.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

initContainer: function(elem, tag)
{
    if ((elem != null) && (typeof elem == 'object'))  // null is considered an object. Go figure.
        this.container = elem;
    else
    {
        if (!elem) elem = 'view' + (new Date()).getTime();
        this.container = document.getElementById(elem);
        if (!this.container) 
        {
            if (!tag) tag = 'div';
            this.container = document.createElement(tag);
            this.container.setAttribute('id', elem);
            document.body.appendChild(this.container);
        }
    }
},

The code above first checks if elem is an object (line 3). If it is, then we assume the programmer knows what he or she is doing and has given us a valid DOM element, and we point the container to it (line 4). Otherwise, we assume elem is supposed to be an id. If it was not passed in, or is null, then we generate a unique id using the Date object (line 7). Next, we attempt to get the element (line 8). If we generated the id, or if the id does not have an associated element, then this will return null, so our container won’t have been set (line 9). So, we know we will need to create the container element ourselves. We check to see if a tag was passed in and, if not, set it to be a DIV (line 11). Again, we are assuming the programmer is intelligent and knows what a valid HTML tag is, so we’re not verifying the input. Then we create the container element (line 12), set the id attribute (line 13), and append it to the document body (line 14).

Now that I’m thinking about it (yes, perhaps I should have been thinking about it earlier in this process, like when I was writing the code…) there is a good chance we won’t want to append the container element to the document body, but rather to some other element. OK, that’s another one for later.

Another method of interest is render. Looks like this.

1
2
3

render: function() 
{
},

It’s not of interest because of its pithy code. No, it’s of interest because this is the method that we’ll call when we actually want to draw our View. This method must be overridden in descendant classes. And thanks to the Class function I worked so diligently on a couple months back, we can easily override it. But that’s for another post.

So, the next question then should be, what are we going to render? Well, I have a couple of methods to render a couple of things. Like forms, input boxes, labels, divs and a few others. Not a complete set yet, just a start. And no fancy data grids and stuff like that yet. Baby steps, baby steps.

Let’s look at the form method, since it’s more interesting than some of the others.

1
2
3
4
5
6
7
8
9
10

form: function(id, url, method, attribs /*, elements*/)
{
    if (!attribs) attribs = { };
 
    attribs.id = id;
    attribs.action = url;
    attribs.method = method;
 
    return this.tag('<form %a></form>', attribs, this.extractArgs(arguments, 4));
},

Yeah, I know, but I didn’t say it was interesting. I said it was more interesting than the other methods. Here’s the pattern you need to know for each of these types of element rendering methods. First, there are a series of arguments specific to the particular element we want to render. This is to make it easy to write. In this example they are id, url and method. Those arguments are followed by an optional attrib argument. This is a catch-all object of HTML attributes, given in name/value pairs. This is how we can render an element with any attributes we want. The remaining arguments are elements, and there may be any number of them. These may be actual DOM elements, or strings of HTML. These elements will be rendered inside the element we are creating. That’s why I said the form element was more interesting than the others. It has several unique arguments in the beginning, and forms always contain other elements (at least the useful ones do).

You can see that the first thing we do is simply take the first set of arguments and assign them to attributes (lines 3-7). The last line is where the money is. The tag method takes three arguments. The first is the HTML for the element that we are creating. The %a in this HTML will be replaced with the attributes. The attributes are given in the second argument as an object. The last argument is an array of DOM elements or HTML strings that are to be included inside the element that we are creating (a FORM element in this case).

OK, a brief aside about the extractArgs method. Every JavaScript function has a variable called arguments. This is an array, where each element in the array corresponds to the arguments that have been passed in to the function. So, the argument at position 0 is in arguments[0], the argument in position 1 is in arguments[1], etc. The funny thing about arguments is that it really isn’t an array at all. It just acts like one. But if you try to access any Array methods, like slice, arguments is revealed for what it is: an impostor. So, we want to get any DOM elements that have been passed in to the form method, so that we can pass them in, as an array, to the tag method. But we can’t simply call arguments.slice() since arguments has no slice method. Fortunately, we can use call to execute slice on arguments. (I talked about call, and its counterpart apply, in this post). That’s what extractArgs does. You pass it the arguments “array” and a start position, and it extracts all the arguments from the start position to the end of the arguments “array” and returns them as a real array.

1
2
3
4
5

extractArgs: function(args, start)
{
    // Convert the arguments to a real array, and extract only those elements we want.
    return Array.prototype.slice.call(args, start);
},

Now, back to that tag method. The tag method takes the HTML, the attributes, and the other elements, and returns a complete DOM element. And because it returns a DOM element, we can use these rendering methods (text, password, submit, etc.) as arguments to other rendering methods that can contain elements (form, div, span, etc). For example, here is what a View for a login might look like. Watch out, I like to use my parenthesis like curly braces!

1
2
3
4
5
6
7
8
9
10

this.div('login', null, 
    '<span>Login here:</span>',
    this.form('loginForm', 'url/to/post', 'post', { class: 'login-form' },
        this.label('Username: ', 'username'),
        this.text('username', 'Joe User'),
        this.label('Password: ', 'password'),
        this.password('password', 'Joes Password'),
        this.submit('Login')
    )
);

This is showing a couple of things. First, we are rendering a DIV (line 1). The id is ‘login’, and null is being passed in for attribs. The remaining arguments are DOM elements and/or HTML strings. That span string will be converted to a span element (line 2). Next we have the form rendering function (lines 3-9). This function returns a DOM element. Its first argument is the form id, then the url to post to, then the method to use when submitting the form. The next argument is the attribs, which is showing that we can add a class to the form attributes. The remaining arguments are DOM elements that are to be rendered inside the form element. Again, we are using our rendering functions to create those DOM elements.

So this is where it really does get interesting. Mildly, at least. This is where most of the work is done, in the tag method. Note that in this function, elements is expected to be an array (unlike in the other functions where the elements were passed in as individual arguments).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

tag: function(format, attribs, elements)
{
    // Convert the attribs object to an HTML string.
    var attribsHtml = '';
    var singleAttrib = '.compact.checked.declare.readonly.disabled.selected.defer.ismap.nohref.noshade.nowrap.multiple.noresize.';
    for (var a in attribs) {
        if (singleAttrib.indexOf('.' + a + '.') > -1) {
            if ((attribs[a] == 1) || (attribs[a] == true) || (attribs[a] == 'true') || (attribs[a] == a))
                attribsHtml += ' ' + a;
        }
        else {
            if (attribs[a]) // Make sure its not null.
                attribsHtml += ' ' + a + '="' + attribs[a] + '"';
        }
    }
 
    // Insert the attributes into the tag format
    format = format.replace('%a', attribsHtml);
 
    // Convert the HTML string to a DOM object
    var elem = this.element(format);
 
    // Add any inner element to the newly created DOM object        
    if (elements) {
 
        for (var i = 0, len = elements.length; i < len; i++) {
            if (isString(elements[i]))
                elem.appendChild(this.element(elements[i]));
            else
                elem.appendChild(elements[i]);
        }
    }
 
    // Lastly, return our new DOM element
    return elem;
},

The first thing we do is convert the attribs object into an attributes string suitable for inclusion in an HTML string (lines 3-15). I think you can figure out what the code is doing. Then, we replace the %a in the HTML format string with the attributes string we just created (line 18). Next, we convert the HTML string into a DOM object (line 21). The element method does that magic, and it’s really pretty simple. I know you’re as excited to look at it as I was writing it, but hold on for a minute, we’re not done with the tag method yet! Once we have the DOM element, we loop through the elements array and append each element there to our new element (lines 23-32). If the element is a string (checked using our isString extension function, just because we can, and we like to think we coded it for something) then it is converted to a DOM element using the element method (lines 27-28). If it is not a string, then we assume it is a DOM element and append it directly (line 30). Lastly, we return the new DOM element (line 35).

So, how do we convert those HTML strings to DOM elements? We let the browser do it for us, of course. What, you thought there was going to be some kind of hocus-pocus? I’m not that smart. Here it is, in all its glory.

1
2
3
4
5
6

element: function(html)
{
    var container = document.createElement('div');
    container.innerHTML = html;
    return container.childNodes[0];
},

First, we create a DIV element (line 1), then set the innerHTML to our HTML string (line 2). This will cause the browser to interpret the HTML and build us a DOM element. Then, we just grab the element and send it back (line 3). That’s it!

And I think that’s plenty for now. Of course, there is a unit test for this, too, but you’ll have to download the code to take a look at it.

Feedback is always appreciated!

Continuing with JavaScript extensions, I’ve created a set of extensions to the Date data type. These include some functions for date calculations, comparisons and formatting. I’ve also added a new function to the String data type that will convert a string into a Date object.

Extensions to the Date object

Let’s start with the simpler one first, the Date object. Most of the functions are pretty self-explanatory, but there are some notable things I should point out.

First, there are the static arrays that have been added to the Date data type.

1
2
3
4
5
6
7

Date.dayNames = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
Date.shortDayNames = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
Date.dayChars = ['S', 'M', 'T', 'W', 'T', 'F', 'S'];
 
Date.monthNames = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
Date.shortMonthNames = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
Date.monthChars = ['J', 'F', 'M', 'A', 'M', 'J', 'J', 'A', 'S', 'O', 'N', 'D'];

Lines 1 to 3 contain the names of the days of the week, and lines 5 to 7 contain the names of the months. You can override these to provide localized names and abbreviations.

These are used to convert a weekday number or month number to a string version. So, for example, I could use Date.monthNames[3] to get the value “April”. But sometimes I need to be able to go the other way as well, like when converting a date string to a Date object. The next block of code sets up for this type of conversion.

1
2
3
4
5
6

Date.monthNumbers = { };
Date.shortMonthNumbers = { };
for (var i = 0; i < 12; i++) {
  Date.monthNumbers[Date.monthNames[i]] = i;
  Date.shortMonthNumbers[Date.shortMonthNames[i]] = i;
}

The above code creates two objects, one for long month names and one for short month names. I saw no need to convert week day names to numbers, so those are not included here. Once the empty objects are set up, it loops through the month names, adding each one as a property to the empty month numbers objects, and setting its value to the corresponding month number. This allows me to look up a month number from the name by simply using Date.monthNumbers['January']. Remember that month numbers in JavaScript are zero-based, so January is 0, not 1. I’m doing this to make it easier and faster to convert month names to numbers. I’m using the loop to build the objects so that I only have to set the month names one time (in the arrays I created earlier). This loop uses those values, saving me from having to re-enter them. This means I can localize the date strings in one place.

Another function of note that I added is the copy function. When you assign one date variable to another, JavaScript creates a pointer to that date object. This means that both variables will point to the same date object, which is not always desirable. The copy function allows you to quickly create a copy of a date.

1
2
3

var d1 = new Date(2009, 03, 20);  // April 20, 2009
var d2 = d1;  // Creates pointer to d1
var d3 = d1.copy();  // Creates a copy of d1

The last function of interest is the toFormat function. This allows you to easily convert a Date object to a string representation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

Date.prototype.toFormat = function(format) 
{
    var pad = function(val) { 
        return (val > 9 ? '' : '0')+val; 
    };
    var result = '';
    for(var i = 0, len = format.length; i < len; i++) {
        var c = format.charAt(i);
        switch(c) {
            case 'Y': 
                result += this.getFullYear();
                break;
            case 'y': 
                result += (this.getFullYear()+'').substr(2,2);
                break;
            case 'M': 
                result += pad(this.getMonth()+1);
                break;
            case 'm': 
                result += this.getMonth()+1;
                break;
            case 'N':
                result += Date.monthNames[this.getMonth()];
                break;
            case 'n': 
                result += Date.shortMonthNames[this.getMonth()];
                break;
            case 'D': 
                result += pad(this.getDate());
                break;
            case 'd': 
                result += this.getDate();
                break;
            case 'W': 
                result += Date.dayNames[this.getDay()];
                break;
            case 'w': 
                result += Date.shortDayNames[this.getDay()];
                break;
            case 'H': 
                var hour = this.getHours() % 12;
                result += pad((hour ? hour : 12));
                break;
            case 'h': 
                var hour = this.getHours() % 12;
                result += (hour ? hour : 12);
                break;
            case 'R': 
                result += pad(this.getHours());
                break;
            case 'r': 
                result += this.getHours();
                break;
            case 'I': 
                result += pad(this.getMinutes());
                break;
            case 'i': 
                result += this.getMinutes().toString();
                break;
            case 'S': 
                result += pad(this.getSeconds());
                break;
            case 's':
                result += this.getSeconds().toString();
                break;
            case 'A': 
                result += (this.getHours() < 12 ? 'AM' : 'PM');
                break;
            case 'a': 
                result += (this.getHours() < 12 ? 'am' : 'pm');
                break;
            default:
                result += (c == '^' ? format.charAt(++i) : c);
        }
    }
    return result;
};

The function takes a single format string and replaces certain characters within that string with the actual date values. Lines 3 to 5 are a small function used to left pad a single digit with a zero. I’m using this version rather than the String.leftPad method (part of the string extensions) simply for performance reasons. This little pad function assumes that the source value is a number and uses type coercion to convert the value, padded or not, to a string. It will also only pad with a single digit. These assumptions make it faster than the String.leftPad method.

Next, the code simply loops through each character of the format string, looking for those special characters that it needs to replace with the date values. Those special characters are given in the following table:

1
2
3
4
5
6
7
8
9
10
11
12

var birthDate = new Date(1980, 0, 1);  // Januatry 1, 1980
 
// Alerts: January 1, 1980
alert(birthDate.toFormat('N, d, Y'));
 
// Alerts: 01/01/80
alert(birthDate.toFormat('M/D/y'));
 
// Alerts: Birthday is Jan 01 '80
alert(birthDate.toFormat("B^i^rt^h^d^a^y is n, D 'y"));
// This is probably a better way to do the above:
alert(String.toFormat('Birthday is %s', birthDate.toFormat("n, D 'y"));

Note that I decided to use the caret ^ for literals rather than the more typical backslash. This is because JavaScript already uses the backslash as an escape character. So, to insert a backslash into a JavaScript string you would always need to insert two backslashes, which I felt would be annoying, not very readable, and easy to forget. For example, you would have to enter a string such as ‘\\D\\ate: M/D/Y’. Each double backslash is interpreted by JavaScript as a single backslash. If you entered it as ‘\D\ate: M/D/Y’, then JavaScript would try to escape the first ‘D’ and the ‘a’.

The other included Date object extension functions are pretty self-explanatory, and the code should be fairly easy to interpret.

More Extensions to the String Object

I’ve also added a new function to the String object, toDate. This method will read the value of the string and convert it into a Date object. As you might imagine, this is a bit more complicated than converting a Date to a String. The basic premise is to use regular expressions to extract the parts of the string that represent the various date part that we are looking for. Once we have all the parts, we convert them as necessary into numeric values that we can use to create a Date object.

The first part of the function sets up a number of variables. I’ll discuss the Pos variables (yearPos, monthPos, dayPos, etc.) in a moment. Just note that they are all set to -1.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

    // Default values set to midnight Jan 1 of the current year.
    var year = new Date().getFullYear();
    var month = 0;
    var day = 1;
    var hours = 0;
    var minutes = 0;
    var seconds = 0;
 
    // Positions of each date element within the source string.  Use to know 
    // which backreference to check after a successful match.
    var yearPos = -1;
    var monthPos = -1;
    var dayPos = -1;
    var hoursPos = -1;
    var minutesPos = -1;
    var secondsPos = -1;
    var amPmPos = -1;
 
    var monthStyle = 'm';       // How we interpret the month, digits (M/m) or names (N/n)
    var hoursStyle = 'h';       // How we interpret the hours, 12-hour (h) or 24-hour (r)
 
    var position = 1;           // Position of the current date element (year, month, day, etc.) in the source string
    var pattern = '';           // Date pattern to be matched.
 
    // Remove extraneous whitespace from source string and format string.
    var str = this.replace(/\s+/g, ' ');
    format = format.replace(/\s+/g, ' ');

The Pos variables in lines 11 to 17 will be set to the position within the source string where a particular value is found. This will be used to retrieve the value from the matches array that is returned when the regular expression is executed. The last thing this block of code does is remove any extraneous whitespace from the source and format strings. I thought it would be safe to do that, and probably helpful when interpreting input from a user which may not be as clean as I would like.

The next block of code, shown below, loops through the format string and builds the regular expression string that will be used to extract the date values we need. This is where we set the value of the Pos variables (yearPos, monthPos, dayPos, etc.). Note that for ‘W’ and ‘w’ in the format string (weekday names) we will match them in the regular expression, just to ensure that the string is the correct format, but we don’t actually need them to create a Date object, so we will ignore their matched values. The format string uses the same notation as the Date.toFormat function discussed above.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

    // Loop throught the format string, and build the regex pattern
    // for extracting the date elements.
    for (var i = 0, len = format.length; i < len; i++) {
        var c = format.charAt(i)
        switch (c) {
            case 'Y' :
                pattern += '(\\d{4})';
                yearPos = position++;
                break;
            case 'y' :
                pattern += '(\\d{2})';
                yearPos = position++;
                break;
            case 'M' :
            case 'm' :
                pattern += '(\\d{1,2})';
                monthPos = position++;
                monthStyle = 'm'
                break;
            case 'N' :
                pattern += '(' + Date.monthNames.join('|') + ')';
                monthPos = position++;
                monthStyle = 'N';
                break;
            case 'n' :
                pattern += '(' + Date.shortMonthNames.join('|') + ')';
                monthPos = position++;
                monthStyle = 'n';
                break;
            case 'D' :
            case 'd' :
                pattern += '(\\d{1,2})';
                dayPos = position++;
                break;
            case 'W' : // We'll match W, but won't do anything with it.
                pattern += '(' + Date.dayNames.join('|') + ')';
                position++;
                break;
            case 'w' : // We'll match w, but won't do anything with it.
                pattern += '(' + Date.shortDayNames.join('|') + ')';
                position++;
                break;
            case 'H' :
            case 'h' :
                pattern += '(\\d{1,2})';
                hoursPos = position++;
                hoursStyle = 'h';
                break;
            case 'R' :
            case 'r' :
                pattern += '(\\d{1,2})';
                hoursPos = position++;
                hoursStyle = 'r';
                break;
            case 'I' :
            case 'i' :
                pattern += '(\\d{1,2})';
                minutesPos = position++;
                break;
            case 'S' :
            case 's' :
                pattern += '(\\d{1,2})';
                secondsPos = position++;
                break;
            case 'A' :
            case 'a' :
                pattern += '(AM|am|PM|pm)';
                amPmPos = position++;
                break;
            default :
                pattern += (c == '^' ? format.charAt(++i) : c);
        }
    }

At the end of all this, the pattern variable will contain our regular expression. We can then use that pattern to check the source string for matches. That’s what the next section of code does, below. If no match is found, we return null, meaning that the source string was not in the format we expected.

1
2
3
4

    // Pull out the date elements from the input string
    var matches = str.match(new RegExp(pattern));
    if (!matches)
        return null;

Next we have to interpret all of those parts. If one of the Pos variables has a value greater than -1, then we know that there should be a match for that field. The value will be stored in the matches array that was returned from the regular expression engine. The position of the value within that array is the value of the Pos variable. In other words, if yearPos > -1, then we can find the value of the year field at matches[yearPos].

Now, because we’ve used regular expressions, we know that if we were looking for a number, then we’ve got a number, and we won’t need to worry that we can’t convert it to an actual Number data type. The monthStyle is used to record whether we are looking for a month number or name. That’s the only value that could be returned as both a number or a name.

Where possible, we will also check the ranges of the values, to make certain that the date entered is valid.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

    // Now we have to interpret each of those parts...
 
    if (yearPos > -1) {
        year = parseInt(matches[yearPos], 10);
        year = (year < 50 ? year + 2000 : (year < 100 ? year + 1900 : year));
    }
 
    if (monthPos > -1) {
        switch (monthStyle) {
            case 'm':
                month = parseInt(matches[monthPos], 10) - 1;    // JavaScript months are zero based, user input generally is not.
                if (month > 11)
                    return null;
                break;
            case 'N': 
                month = parseInt(Date.monthNumbers[matches[monthPos]], 10);
                if (isNaN(month))
                    return null;
                break;
            case 'n':
                month = parseInt(Date.shortMonthNumbers[matches[monthPos]], 10);
                if (isNaN(month))
                    return null;
                break;
        }
    }
 
    if (dayPos > -1) {
        day = parseInt(matches[dayPos], 10);
        if ((day < 1) || (day > Date.daysInMonth(month, year)))
            return null;
    }
 
    if (hoursPos > -1) {
        hours = parseInt(matches[hoursPos], 10);
        if (hoursStyle == 'h' && (hours == 0 || hours > 12))
            return null;
        else if (hours > 23)
            return null;
    }
 
    if (minutesPos > -1) {
        minutes = parseInt(matches[minutesPos], 10);
        if (minutes > 59)
            return null;
    }
 
    if (secondsPos > -1) {
        seconds = parseInt(matches[secondsPos], 10);
        if (seconds > 59)
            return null;
    }
 
    // Convert 12-hour time, if used, to 24-hour time.
    if (amPmPos > -1) {
        var amPm = matches[amPmPos];
        if ((amPm == 'pm' || amPm == 'PM') && (hours < 12))
            hours += 12;
    }

An enhancement to this code would be to provide a specific error code and message for a date conversion failure. For example, month is out of range, or February does not have a 29th day in 1999. But that’s for another time.

The last thing to do is take all the values we’ve extracted from the string, and convert them to an actual Date object.

1

    return new Date(year, month, day, hours, minutes, seconds);

Of course, tests are included for all extension functions as well.

Date Extensions

Date.daysInMonth(month, year)
Returns the number of days in the current month and year. Note that the month is zero-based, so January = 0, February = 1, etc.

Date.prototype.copy()
Creates a copy of the current date object. Assigning one date variable to another simply points both variables to the same date object. This function is useful when you need a unique copy of the date object.

Date.prototype.getDayName()
Returns the full name of the day of the week.

Date.prototype.getShortDayName()
Returns the short name of the day of the week, typically in 3 characters.

Date.prototype.getDayChar()
Returns the single character representation of the day of the week.

Date.prototype.getMonthName()
Returns the full name of the month.

Date.prototype.getShortMonthName()
Returns the short name of the month, typically 3 characters.

Date.prototype.getMonthChar()
Returns the single character representation of the month.

Date.prototype.getMonthNumber()
Returns the normalized numeric representation of the month. (i.e. January = 1, February = 2, …, December = 12)

Date.prototype.daysInMonth()
Returns the number of days in the current month and year, adjusting February for leap years.

Date.prototype.addDays(offset)
Adds the given number of days to the date. To subtract days, pass in a negative value for offset.

Date.prototype.addMonths(offset)
Adds the given number of months to the date. To subtract months, pass in a negative value for offset.

Date.prototype.addYears(offset)
Adds the given number of years to the date. To subtract years, pass in a negative value for offset.

Date.prototype.addHours(offset)
Adds the given number of hours to the time portion of a date. To subtract time, pass in a negative value for offset.

Date.prototype.addMinutes(offset)
Adds the given number of minutes to the time portion of a date. To subtract time, pass in a negative value for offset.

Date.prototype.addSeconds(offset)
Adds the given number of seconds to the time portion of a date. To subtract time, pass in a negative value for offset.

Date.prototype.clearTime()
Clear the time portion of a date object.

Date.prototype.compareTo(date, ignoreTime)
Date comparison functions. If ignoreTime is true, then the time portion will be ignored during the comparison.

Date.prototype.isBefore(date, ignoreTime)
Returns true if this date is before another date.

Date.prototype.isAfter(date, ignoreTime)
Returns true if this date is after another date.

Date.prototype.equals(date, ignoreTime)
Returns true if this date is equal to another date.

Date.prototype.toFormat(format)
Return a date in the given format. Use ^ to force the use of a literal character.

String Extensions (showing new only)

String.prototype.toDate(format)
Attempts to convert a string into a date based on a given format. Fields will match either the long or short form, except in the case of the year, where the string must match either a 2-digit or 4-digit format. Ranges are checked. Day names are expected if they are included in the format string, but are otherwise ignored. Use ^ to force the use of a literal character. In other words, to have the character Y appear insead of the actual year, use ^Y.

As I mentioned in my previous post, I’m in the process of creating some JavaScript functions that extend the basic JavaScript data types. Well, I’ve create a few extensions for the String and Number data types. Also, since I’m building a JavaScript library, I went ahead and packaged the source code files into a library as well.

JavaScript Extensions

How do you extend the basic data types you ask? There are two ways. You can either create a static method, which is available from the from the data type itself, or a prototype method, which is available from all instances of that data type.

For example, the repeat function is a static method of the built-in JavaScript String class. It was created like this:

1
2
3
4
5
6
7

String.repeat = function(chr, count)
{
  var s = '';     
  for(var i = 0; i < count; i++) 
    s += chr;     
  return s;
}

You can then execute the repeat method like so:

1
2

var str = String.repeat('x', 5);
alert(str);  // Alerts: "xxxxx"

On the other hand, the rightPad function was created as a prototype method of the String class. If you recall from the Creating JavaScript Classes series, prototype methods are accessible from all object instances. This means any instance of a String will have this method.

1
2
3
4
5
6
7
8
9
10

String.prototype.rightPad = function(width, chr, trunc)
{
  var s = this.toString();
  var w = width - s.length;
  if (w > 0)
    s = s + String.repeat(chr, w);
  else if (trunc)
    s = s.substr(0, width);
  return s;
}

Now, there are two things to note in the above. First, the declaration uses String.prototype.rightPad to add the rightPad function to the prototype of the String class. Second, because the rightPad method is now available to a String object instance, the this variable is available in the function, and it will point to the current String instance.

Also of particular interest is line 3, which uses this.toString() to create a copy of the current string. It is this copy that is modified and returned by the function. This is common functionality in JavaScript, and I wanted to follow that same pattern here. For example, the replace method does not alter the string, but returns a new string with the replacements made.

The String extensions include basic string manipulation function like padding, trimming and formatting. I’ve also include a function to convert a string to a number, while considering how a user might enter a number. So these values could include thousands separators, currency symbols, or even fractions. I often find that users appreciate the ability to enter fractions rather than decimals. Its easier for a user to enter 1/8 rather than remembering or calculating the decimal value 0.125. And I’m a big believer that the user should not be calculating anything. That’s what the computer is for!

The Number extensions include a toFormat function that will take the number and convert it to a string. Again, this can take a number like 0.125 and convert it back to the fraction 1/8, if desired. I could have overridden the built-in toString function, but it has its own purpose that developers may still want to use, so I left it alone.

Here are some examples of using these extensions. To format a number, you can use:

1
2
3

var num = 1234.56;
var str = num.toFormat(3, true);
alert (str);  // Alerts: "1,234.560"

Or, if you want a fraction, set the first argument (the precision) to -1, like so:

1
2
3

var num = 1.333;
var str = num.toFormat(-1);
alert (str);  // Alerts: "1-1/3"

Using the string extensions, you can parse the fraction:

1
2
3

var str = '1-1/3';
var num = str.toNumber();
alert (num);  // Alerts: "1.3333"

To pad a string, use something like this:

1
2
3

var str = '123';
var pstr = str.leftPad('0', 5);
alert (pstr);  // Alerts: "00123"

Of course, you can chain all these functions, too:

1
2
3

var num = 123.4;
var str = num.toFormat(2).leftPad('*', 8);
alert (pstr);  // Alerts: "**123.40"

This is just a sample of the extensions that are included. All of them are pretty straight-forward, and the code is well-documented (in my opinion, let me know if you feel otherwise). And, of course, all of the unit tests are in there as well. Please keep in mind that these are first versions, so don’t expect perfection yet! I can already see where I’d like to make some additions and changes to these functions. I’m still in the early stages here, so I’ll try to keep things backward compatible. But that may not be possible. You’ve been warned!

JavaScript Library Framework

The other thing I did in this version is to package these extensions along with the Class function from the Creating JavaScript Classes series, into a actual library. I also added a namespace, and, come to think of it, I should probably also add a namespace function. Will add that to my list of things to do. Anyway, to use the Class function, you will now access it using LivingMachines.Class(). Otherwise, it’s usage is the same as previously described in the Creating JavaScript Classes series. Going forward, all additional code will be added to this new library package.

Well, I hope you find these useful and educational. This is only the start of the library, so make sure to subscribe to the RSS feed so that you can keep up to date on new developments. Next up, I’m going to work on some date formatting functions. This means I’ll be adding some functions to the Data data type, and to the String data type as well.

Included JavaScript Extension Functions

Here is a quick overview of the new JavaScript extensions included in this release. A quick look at the source code comments will give you more details on function usage. Eventually, I will get around to converting the documentation comments to online docs. I’ve got to investigate some of the tools that are out there for doing that, though.

String Extensions

String.repeat()
Repeats a character or string a given number of times.

String.prototype.trim()
Trims whitespace from the left and right sides of a string.

String.prototype.leftTrim()
Trims whitespace only from the left side of a string.

String.prototype.rightTrim()
Trims whitespace only from the right side of a string.

String.prototype.leftPad()
Pads the left side of a string with a given character to a given width.

String.prototype.rightPad()
Pads the right side of a string with a given character to a given width.

String.prototype.toFormat()
Takes a source string with value placeholders and replaces the placeholders with actual values.

String.prototype.toNumber()
Converts the string to a number.

Number Extensions

Number.prototype.toFormat()
Converts a number to a formatted string.

Number.prototype.gcd()
Calculates the greatest common divisor between this number and another number.

I’ve created a few JavaScript functions that I find tend to come in handy when programming. I call them “extensions” because they extend the base window object with additional functions. I debated on namespacing these, but find that either they are used often enough that having to type a namespace every time becomes annoying, or the code is more readable without the namespace. Also, these are functions that are useful in their own right, outside of any library, so namespacing them to a library didn’t seem right to me. (If you are not familiar with namespacing in JavaScript don’t worry about it. I’ll discuss it in an upcoming post.)

Documentation is included in the source code, but below is a quick reference, so you can see what’s in there. All of these functions are added to the global window object, so you can use them directly. For example, to copy a JavaScript object, you can use:

1
2
3
4
5
6
7
8

source = {
  firstName: 'Jane',
  lastName: 'Doe',
  birthDate: new Date(2000, 10, 15)
};
 
// Use the copy function to create a duplicate of source
var dest = copy(source);

Or, to check if an object is an array, you can use one of the following methods:

1
2
3
4
5
6
7

var arr = [1,2,3];
 
if (isArray(arr))
  alert('It is an array!');
 
if (typeOf(arr) == 'array')
  alert('It is an array!');

This is only a first pass at these functions. In an upcoming post, I will be adding more extensions to this library. This will include adding some useful functions to the basic data types like String, Number, Date and Array. More to come, so stay tuned.

typeOf(obj)

Same as the built-in typeof operator, but distinguishes
arrays and dates from objects.

Params:
obj {object} The object to get the type of.
Returns:
{string} The name of the type of the object.

isUndefined(obj)

Checks if the object passed in is undefined.

Params:
obj {object} The object to be checked.
Returns:
True if obj is undefined, and false otherwise.

isNull(obj)

Checks if the object passed in is null.

Params:
obj {object} The object to be checked.
Returns:
True if obj is null, and false otherwise.

isString(obj)

Checks if the type of object passed in is a string.

Params:
obj {object} The object to be checked.
Returns:
True if obj is a string, and false otherwise.

isNumber(obj)

Checks if the type of object passed in is a number.

Params:
obj {object} The object to be checked.
Returns:
True if obj is a number, and false otherwise.

isBoolean(obj)

Checks if the type of object passed in is a boolean.

Params:
obj {object} The object to be checked.
Returns:
True if obj is a boolean, and false otherwise.

isDate(obj)

Checks if the type of object passed in is a date. This function will
distinguish between an object and a date.

Params:
obj {object} The object to be checked.
Returns:
True if obj is a date, and false otherwise.

isArray(obj)

Checks if the type of object passed in is an array. This function will
distinguish between an object and an array.

Params:
obj {object} The object to be checked.
Returns:
True if obj is an array, and false otherwise.

isObject(obj)

Checks if the type of object passed in is an object. This function will distinguish between an array and date vs. an object.

Params:
obj {object} The object to be checked.
Returns:
True if obj is an array, and false otherwise.

isFunction(obj)

Checks if the type of object passed in is a function.

Params:
obj {object} The object to be checked.
Returns:
True if obj is a function, and false otherwise.

copy(source, [dest])

Copies the properties of one object to another (including inner objects, arrays and non-prototype functions). Existing properties in the destination object are preserved, but will be overridden if those properties also exist in the source. Any functions in the prototype of the source will NOT be copied. If no destination object is passed in, a destination object will be created.

Params:
src {object} Source object that properties are to be copied from.
dest {object} Destination object that properties are to be copied to.
Returns:
The destination object.

scopedFn(scope, func)

Used to create a function pointer that will always be called against a specific object. Can be especially useful when assigning event handlers to DOM objects and you want the “this” variable to point to your own object rather than the DOM object.

Params:
{object} scope The object on which func is to be called.
func {function} The function to be called.
Returns:
A scope-corrected function that ensures func is always called against the given scope object.

emptyFn()

Shorthand for an empty function.