In my previous post on the mf object methods I discussed several methods that act against a single object. In this next series of object methods I will begin demonstrating some of the mf object methods that deal with arrays of objects. When we look at applications within the business sphere we in most cases have to deal with large amounts of data that is displayed in grids and other standard user interface implementations. When dealing with this type of data you need to envision, in regards to a grid, what types of behaviour and functionality you need to provide to the consumer. There are some obvious features like sorting and search plus filter. As such we need to provide these types of methods as part of the object methods. In the future of mf I will be developing a store object which will make significant use of these methods. In this post I will discuss the following methods…

• mf.object.exec
• mf.object.normalize
• mf.object.merge
• mf.object.sort
• mf.object.search
• mf.object.difSearch

mf.object.exec (mixed, function, deep, desctructive)

The object.exex method allows you to enumerate through an array of objects or a single object and place the result of the provided function as the value of the property. The function is passed three arguments as the enumeration of the object is run. The value of the property, property namespace and the root object instance. You can optionally pass the deep boolean which defaults to false if you require deep object enumeration. The final parameter destructive is also optional boolean that defaults to true. When set to false the passed object or object array is first cloned and then returned. For example..

var myObject = [
{z:1,x:'a',b:undefined},
{
    a:{
        aa:1,
        bb:2
    },
    f: 1
}]
mf.object.exec(myObject,function(val){return mf.isNumber(val)?val*10:val},true,false)

The result of the exec method would return an array which has been cloned with the following values:

{z:10,x:'a',b:undefined},
{
    a:{
        aa:10,
        bb:20
    },
    f: 10
}]

Since the destructive argument was set to false the original myObject has not been modified.

mf.object.normalize(array, value)

The normalize object method takes and array object mixed objects and ensures that each object all have the same properties. For example given the following call:

var myObject = [
{z:1, x:'a', b:'z'},
{
    z:2,
    a:{aa:1,bb:2},
    f: 1
}]
mf.object.normalize(myObject);
The result would be:
[
 {
    z:1, 
    x:'a', 
    b:'z',
    a:{aa:null,bb:null},
    f:null
 },
 {
    z:2,
    x:null,
    a:{aa:1,bb:2},
    b:null,
    f: 1
 }
]

As can bee seen both objects now share all of the same properties. The optional second parameter value is the default value to assign to properties that are created in each object in order to normalize. By default the value argument is Null.

When we dealing with large datasets being pulled via AJAX requests one of our goals is to reduce the size of this request as much as possible.  When dealing with these large sets most often all of the object definitions match on properties in the JSON requests even specific fields are null. On these large requests returning that a field is Null is wasteful on the request pipe. By using the mf.object.normalize method you can retrieve your data optimized for transport then use normalize it within the client. It should be taken into account however that running the normalize method against very large datasets is not recommended as it takes several passes on the data in order to normalize. Like any implementation a balanced approach needs to be taken by testing the performance versus request time.

mf.object.merge(array, function, deep)

Merges an array of objects into a single object allowing the ability to do things such as summed sets. For example:

var data=[
{a:1,b:6},
{a:4,c:{y:2}},
{a:2,b:1,c:{x:1,y:1}}
];
mf.object.merge(data,function(prop,obj,ns,depth,mergeObjVal,mergeObj){obj[prop]+=mergeObjVal},true)

The method would then return

{
  a:7,
  b:7,
  c:{
     x:3,
     y:3
   }
}

The merge method initially clones and normalizes the passed array of data so it is not destructive. The deep parameter is optional and is true by default. The function argument is passed several parameters to allow for direct changes to the both the current object and the resulting object. The function is passed the present object property along with the object root the current namespace as a string and the namespace depth.  The function is also passed the current value for the matching namespace in the merge object and the root of the merge object as well. The result of this function is always the merge object itself.

mf.object.sort(array, key, ascending)

Sorts an array of objects based on the provided key and its subsequent value. This method does NOT do a deep enumeration of each object so the key/property as string must exist at the root of each object. The boolean ascending is true by default to sort in descending order pass false. For example:

var data=[
{a:1,b:6},
{a:4,b:3,c:{y:2}},
{a:2,b:1,c:{x:1,y:1}}
];
mf.object.sort(data,'a')

The passed data will now be sorted ascending by the value contained in the root a property of the objects. This method does NOT do any data normalization to ensure that the provided property key exists in each object.

mf.object.search(propertySet, array)

Search an array of objects and returns an array of those objects matching the propertySet. This method does not support deep object enumeration, use intersect for deep enumeration. The property set is by definition a simple object that allows for matching of property values. For example:

var data=[
{a:1,b:6},
{a:4,b:3,c:{y:2}},
{a:2,b:1,c:{x:1,y:1}}
];
mf.object.search({a:4},data)

This would return an array containing one object from data whose a property was equal to 4. The property set parameter can also contain functions that must return true or false. Consider the following scenario:

var data = [
 {title:'Welcome to my framework'},
 {title:'Using Object Methods',b:2},
 {title:'Object.intersect Method in Detail',b:1}
];
mf.object.search({b:2,title:function(val){return val.match('Object')}},data)

In this case we are checking the title to see if the value contains the word object and also is its b property is equal to 2. The result would be the second object from the array. This is a not a descructive method and the passed objects are NOT cloned into the resulting array so all pointers would still remain intact.

mf.object.difSearch(propertySet,array)

The difSearch method is identical in nature to search but returns an array of objects that do not meet the search requirements. As an example:

var data = [
 {title:'Welcome to my framework'},
 {title:'Using Object Methods',b:2},
 {title:'Object.intersect Method in Detail',b:1}
];
mf.object.difSearch({b:2,title:function(val){return val.match('Object')}},data)

This call would result in only the first array object being returned as both the 2nd and 3rd objects fail on one or more of the tests.

It has been a few weeks since I wrote a post on mf but this has most been due to the time it took to complete all of the object methods available.  Object methods along with array methods are some of the most important methods that any framework can have and as such taking some extra time is required. At present there are 28 methods written and fully tested. Given this number it would obviously be far to much for one single blog post. As a result I will be writing several blog posts each covering several methods at a time. In this post I will discuss the following methods:

• mf.object.each
• mf.object.deepEach
• mf.object.clense
• mf.object.typeMap
• mf.object.containsKeys
• mf.object.containsVals

mf.object.each (object, function, scope)

The each method is used to enumerate through each attribute of an object at a shallow level under the optionally passed scope. On each attribute of the object the provided function is called under the provided scope and passed the name of the attribute as a string, the value of attribute along with the original object passed. For example:

var myObject = {a:1,b:2,c:['a','b','c'],d:{aa:1,bb:2}};
var testFunction = function(key,val,o){
     console.write(key,typeof val, val, o)
};
mf.object.each(myObject,testFunction)

Result:
a, number, 1, {a:1,b:2,c:['a','b','c'],d:{aa:1,bb:2}}
b, number, 2, {a:1,b:2,c:['a','b','c'],d:{aa:1,bb:2}}
c, array, ['a','b','c'], {a:1,b:2,c:['a','b','c'],d:{aa:1,bb:2}}
d, object, {aa:1,bb:2}, {a:1,b:2,c:['a','b','c'],d:{aa:1,bb:2}}

As you can see it is fairly simple in its behaviour. If you wanted to break out of the enumeration of the passed object all you need to is return false from your test function. This function is non destructive in nature. It should be remember however that the method does NOT test for has hasOwnProperty. This is a deliberate decision on my part to allow for the enumeration of prototyped methods and also remove any condition of enumeration for improved performance.

One of the problems however with the object.each method can be seen in the last result of the example which returns d which is an object itself. Basically the each method does not do ‘deep’ enumeration of the passed object. Certainly you could do this with an test and iterative call within your passed function, such as:

var testFunction = function(key,val,o){
  if(mf.isObject(val)){
     mf.object.each(o[key],testFunction)
  }else{
     // do something
  }
}

However this would get very tiresome having to write this in your code all of the time and two points here. In many circumstances you need to do deep object enumeration and secondly, the point of a framework is to streamline your code. The each method returns the passed object in order to allow for chaining.

mf.object.deepEach(object,function,scope)

The deepEach method works in the exact same fashion as the each method where returning false will exit the enumeration. However it enumerates the object deeply. Given our example above running the same testFunction on myObject with the deepEach method would result in the following output:

Result:
a, number, 1, {a:1,b:2,c:['a','b','c'],d:{aa:1,bb:2}}
b, number, 2, {a:1,b:2,c:['a','b','c'],d:{aa:1,bb:2}}
c, array, ['a','b','c'], {a:1,b:2,c:['a','b','c'],d:{aa:1,bb:2}}
d, object, {aa:1,bb:2}, {a:1,b:2,c:['a','b','c'],d:{aa:1,bb:2}}
aa, number, 1, {aa:1,bb:2}
bb, number, 2, {aa:1,bb:2}

As you can see the call would result in the attributes on the d object being passed as well to the function as well as the original d object itself. Note however, when the provided function is passed the attributes of the d object that the passed object changes to d rather than the original root object.  This allows you do things like o[key] in your function and be guaranteed that the key exists within the passed objects scope.

When working with the deepEach method the passed function is also passed two extra parameters, namespace as string and depth as a number. To understand how these can be used lets look at the following example:

var testFunction = function(key,val,o,ns,depth){
	console.log(key,typeof val, val, o, ns, depth)
}
var myObject = {
a:1,
b:{
	aa:{
		aaa:1,
		bbb:2,
		ccc:{
			aaaa:'a',
			bbbb:'b'
		}
	}
}}
mf.object.deepEach(myObject,testFunction)

Result:
a,number, 1, [object Object], , 0
b,object, [object Object], [object Object], , 0
aa,object, [object Object], [object Object], b, 1
aaa,number, 1, [object Object], b.aa, 2
bbb,number, 2, [object Object], b.aa, 2
ccc,object, [object Object], [object Object], b.aa, 2
aaaa,string, a, [object Object], b.aa.ccc, 3
bbbb,string, b, [object Object], b.aa.ccc, 3

Note the result on our deepEach call  for namespace and depth. When we method is at the root of the passed object no namespace is passed and the depth is zero. When we hit the attribute aa within the b object the namespace is passed as the string b and the depth is 1. This allows you to make test conditions within your function when looking for a specific condition/attribute within a specific namespace or depth. Consider for a moment this object:

var myObject = {a:{aa:1,bb:2},b:{aa:1,bb:2}}
var testFunction = function(key,val,o,ns,depth){
    if(ns==='a' and key==='aa'}{
        o[key]=null
    }
}
mf.object.deepEach(myObject,testFunction)

In this example if the deepEach method did not provide the namespace as string there would be no way to differentiate between the aa attribute in a or b which would not be very useful. Like the each method the deepEach method is non destructive and also returns the passed object to allow for chaining.

mf.object.clense(object, value, deep)

This methods resets an objects attribute values to the optionally provided value. You can also specify if the enumeration should be deep on the object. If the value is not provided is not provided it is defaulted to null. If deep is not provided it will be defaulted to false. Given the following:

var myObject = {a:1,b:2,c:{aa:1,bb:1}
mf.object.clense(myObject,null,true)
Result:
{a:null, b:null ,c:{aa:null, bb:null}

If deep had been set to false only the root attributes of a and b would have been set to null and aa and bb would still be 1.

mf.object.typeMap (object, deep)

The typeMap method is a convenience function that returns an object describing the types of of objects contained with the object. It can be used to easily find specific types of data based on namespaces within the object. The deep parameter is optional and defaults to true. For Example:

var myObject = {
    a:{
        aa:1,
        bb:2,
        cc:[1,2,4],
        dd:null
    },
    b:[1,2,3,4],
    c: undefined,
    d: function(){return true},
    f: 1,
    g: 'abc'    
};
mf.object.typeMap(myObject,true)

Result:
{
  array : ['a.cc','b'],
  function : ['d'],
  null : ['a.dd'],
  number : ['a.aa','a.bb','f'],
  object : ['a'],
  string : ['g'],
  undefined : ['c']
}

The result of the call always returns the exact same properties but if for example no arrays where present in the object the the array attribute would have an empty array.  This typeMap method can be useful when you need to set specific types of information in the object to a value. For example consider if we had an unknown object but needed to ensure that it did NOT contain any attributes assigned to functions and all number attributes where set to 0. This could easily be done within mf with the following code.

var myMap = mf.object.typeMap(myObject,true);
mf.each(myMap['function'],function(val){
    mf.ns.remove(val,myObject)
});
mf.each(myMap['number'],function(val){
    mf.ns.set(val,myObject,0);
})

You will notice in the above code I have touched on a couple of other methods mf.each, mf.ns.remove and mf.ns.set. I will be discussing these methods in a future post.

mf.object.containsKeys(object, keys, deep)

This method accepts an object and an array of namespace keys, a string of comma delimited keys or a single key and returns true if the key(s) are found within the object. The deep parameter is optional and defaults to false. Any of the following calls would be valid

mf.object.containsKeys(myObject,['a','a.bb','cc']);
mf.object.containsKeys(myObject,'a,a.bb,cc');
mf.object.containsKeys(myObject,'a');

If more than one namespace/key is passed they ALL must be found in order for the method to return true.

mf.object.containsVals(object, vals, deep)

This method is identical to contains keys but the comparison is done against the values rather than the keys and if found returns true. As with the containsKeys method if an array of values are passed all must be found in order for the method to return true.

In my next post I will discuss further methods in the object class of mf. These methods will focus more on arrays objects and provide methods for sorting, normalizing, searching, comparison along with many more very cool methods for manipulated arrays of object.

When I have completed the blog posts on the mf.object methods I will be adding them to the mf API documentation at the top of the blog along with other base methods. Until then enjoy.

One of the first key things that is required in any JavaScript framework is a browser sniffer. Browser sniffers are easy to create and as with all of the modules that will be placed into mf it uses my standard design pattern. Here is the code:

var browser = Object.freeze((function(){
     var app = new String(navigator.userAgent),
     mode = document.documentMode,
     isIE = app.match('MSIE')!==null,
     isSafari = app.match('Safari')!==null && app.match('Chrome')===null,
     isChrome = app.match('Safari')!==null && app.match('Chrome')!==null,
     isFireFox = app.match('Firefox')!==null,
     tests = {
           isSafari : isSafari,
           isChrome : isChrome,
           isFireFox : isFireFox,
           isIE : isIE,
           isIE5 : isIE && mode===5,
           isIE6 : isIE && mode===6,
           isIE7 : isIE && mode===7,
           isIE8 : isIE && mode===8,
           isIE9 : isIE && mode===9,
           isIE10 : isIE && mode===10,
           version : 0,
           isWin : navigator.platform.toLowerCase()==='win32',
           isMac : navigator.platform.toLowerCase()!=='win32',
           isSecure : (window.location.protocol).toLowerCase().substr(0,5)==='https'
     },
     Public = {};
     // get browser version
     if(isFireFox){
           tests.version = parseInt(/Firefox\/(\d+\.)/.exec(app)[1],10)
     }else if(isChrome){
           tests.version = parseInt(/Chrome\/(\d+\.)/.exec(app)[1],10)
     }else if(isSafari){
           tests.version = parseInt(/Version\/(\d+\.)/.exec(app)[1],10)
     }else if(isIE) {
           tests.version = parseInt(/MSIE (\d+\.)/.exec(app)[1],10)
     };                             
     tests.mfCompliant = (isSafari && test.version>4) || (isIE && tests.version >8 && mode>8) || (isChrome && tests.version>20) || (isFireFox && tests.version>14);
     // convert results into anonymous function calls
     for(prop in tests){
           Public[prop]=new Function('return '+tests[prop]+';')
     };
     return Public;                                    
}()));

Note that I am adding the mfCompliant property onto the tests object and setting my browser minimum requirements.  I am also not testing for Opera although that certainly could be added in very easily at any point in the future.  Finally I enumerate through the tests object and create anonymous functions within the Public object that return the values of the subsequent property in the tests object.  Note also the the public returned by the outer anonymous function is passed to the Object.freeze method in order to freeze the resulting object. This will prevent users from overriding existing methods or removing them.

In the case of IE9 it does not support the Object.freeze method.  As a result I had to place the following code above this module.

// Ensure we have freeze method on Object for IE9
if((typeof Object.freeze).toLowerCase()!=='function'){
       Object.prototype.freeze = function(o){
              return o
       }
}

Sine the freeze method returns the object being frozen this little override does the same thing in order to ensure when running the framework in IE9 it does not blow up on you.  Freezing is certainly handy on objects but does not add any direct functionality to the framework.

The mf global variable browser is then returned as belonging as a child object to the framework.  This then allows external users to make calls such as mf.browser.isIE() or mf.browser.isSecure(). Certainly over time there may be other items to add under the browser module but these are the basics.

In my next post I will be fleshing out some other core methods for Objects, Arrays along with some base prototyping of core JavaScript objects such as String and Number.

All JavaScript frameworks have common methods each with its’ own unique slant on implementation. All frameworks consist of browser sniffers, DOM normalization plus Event and Component Management along with methods to make life a little easier for the programmer. Each of these concepts offer the same or similar implementation yet there seems to be a gross lack of understanding on how they work.

So the goal of creating the ^mf framework is to demonstrate to JavaScript developers the basic concepts of how frameworks are put together in order to further their understanding of other frameworks. So like driving a car you should have some idea of how the engine actually works!

So, in the next several months I will be building up the framework piece by piece with one or more blog posts on each of the components that will constitute the end product.  Once I have the framework developed to a certain point I will also be placing it up on Google code for people to play with, enhance or throw mean reviews back at me.

Cheers
Keith

As most of us know, well I would hope most of us that is, properties in objects have some fundamental flaws in them, that, like many situations in JavaScript our bits and bites are left hanging out!  Object properties that are exposed publicly, whether in a module pattern or an instance have absolutely zero control over them.

If one does some research however you will dig up the Object.defineProperty method and supporting methods that as of IE9 are now common across all modern browsers.  If you are interested in reading up on the defineProperty Object method I have found the best documentation to be over at Mozilla . While Object.defineProperty does provide us enhancements such as read only, freezing and preventing deletion is certainly does not, in my opinion, provide much power. A property should provide the following:

• Verbose setters and getter methods,
• Conditional checking on setters,
• Chaining of base object setters,
• Watches and events.

So let’s go through each of these concepts. Verbose setter and getter methods are in essence methods to set and get the property value while protected the actually base value. So assuming we have an object entitled myLittleObject with a property called height I should be able to say myLittleObject.height.set(10) or myLittleObject.height.get(). Now a very good argument can be made for simple having a single method on height which either returns the value or takes a value, thusly myLittleObject.height(10) sets the value to 10 and myLittleObject.height() returns 10. While I have nothing against this, I simply prefer my code to be extremely verbose, hence my preference for property.set/get.  It also helps that I am an extremely fast typist, so perhaps that helps!

Conditional Checking of setter refers to the ability to apply a test to value being assigned to a property. One of the general weaknesses of JavaScript is its’ base data types. Let’s face it Number() really does not cut it for numeric values. Most languages, in fact I cannot think of any that do not support Int, Long, Double etc. I recognize that there is argument that there is no point to creating other base types as they will all be based against the browser engine data type so there is no memory or speed enhancement. However from a pure programmatic point of view being able to apply tests against a value being passed in provides for much greater control.

Chaining is a key part of todays’ JavaScript frameworks. Chaining is the process of returning the base object on calling the setter method of that object’s property. For example, if we have an object with two properties we should be able to do, myObject.x.set(1).y.set(2) rather than having to make two separate statements on myObject. In this case the set method of each property returns myObject.

Watches and events are an extremely important aspect of a property object. Many years ago Mozilla introduced watches on variables which in essence allowed you to create binders to the watch to ‘watch’ for certain conditions.  This could be viewed at its core level as an event style paradigm. For the purpose of this blog post I will not cover creating the watch/event object as that is beyond the scope of this post. I will however discuss the creation of an event object in the next post.

Now that we have gone through the requirements let’s look at the basics for the method.

/**
  * @method createProp
  * @description Creations a property on the passed object and property based on the provided config.
  * @param scope [object] The location within the object to create property
  * @param prop [string] The name of the property to create
  * @param config [object] Mixed object declaring the details of the property, see defaults.
  * @return null
  **/
 createProperty = function (scope,prop,config){
                 var defaults = {
                                 // @prop verbose (bool) When true properties are given declaritive set and get methods rather
                                 // than a single method that tests for the existence of a passed value.
                                 verbose : false,

                                 //@prop writeable (bool) indicates if the property will have a setter method
                                 writeable : true,

                                 //@prop value (mixed) value of the property
                                 value : null,

                                 //@prop allowNull (bool) When true property may be null
                                 allowNull : true,

                                 //@prop allowUndefined (bool) When true property may be undefined
                                 allowUndefined : false,

                                 //@prop valueCondition (function) A function passed the value being provided to the setter method. If false is returned  the property value will not be changed
                                 valueCondition:function(){return true},

                                 // @prop setterErrorThrow (object) Object containing booleans on whether to throw errors on setter failuers. For example if  the config property allowNull is false have a setterErrorThrow of null true will throw an error when the property is attempting to be set to null. If the properties root sibling is true then the sibling throw property will be ignored.
                                 setterErrorThrow : {
                                                 allowNull : false,
                                                 allowUndefined : false,
                                                 valueCondition : false
                                 },

                                 // @prop chain (bool) When true the scope object is returned on the setter method allowing for the chaining of objects 
                                 chain : true,

                                 // @prop scope (mixed) object to return on setter when chain is true, defaults to passed scope on function
                                 scope : scope
                 };
                 config = applyIf(config,defaults);
 };

If we remember back to my previous post ‘Writing Flexible JavaScript Functions’ I introduced the applyIf method that allows for the assignment of properties in an object. As can be seen by the above code I have set up a set of default properties along with explanations of what each will do.

Now that we have this set up lets write the actual code to return the object following the applyIf line.

var propObject = (function(config){
                 var currentValue=config.value,
                 propConfig = config,
                 methods = {
                                 get : function(){
                                                 return currentValue;
                                 }
                 };
                 if(propConfig.writeable){
                                 methods.set = function(value){
                                                 if(value === undefined && !propConfig.allowUndefined){
                                                                 if(propConfig.setterErrorThrow.allowUndefined){
                                                                                 throw('undefined not allowed');
                                                                 }
                                                 }else if(value === null && !propConfig.allowNull){
                                                                 if(propConfig.setterErrorThrow.allowNull){
                                                                                 throw('null not allowed');
                                                                 }              
                                                 }else if(!propConfig.valueCondition(value)){
                                                                 if(propConfig.setterErrorThrow.valueCondition){
                                                                                 throw('value condition fail');
                                                                 }                                                                              
                                                 }else{
                                                                 currentValue=value;
                                                 };
                                                 return propConfig.chain?propConfig.scope:value;
                                 }
                 }
                 return methods;
 }(config));

 if(config.verbose){
                 scope[prop]=Object.freeze(propObject);
 }else{
                 scope[prop]=Object.freeze(function(value){
                                 if(value!==undefined && propObject.set!==undefined){
                                                 return propObject.set(value);
                                 }else if(value===undefined){
                                                 return propObject.get();
                                 }
                 })
 }

As you can see this is a fairly simple implementation. I create an internal object called propObject with the required methods along with a copy of the passed config. Once the object is created I check the config.verbose setting to decide how to assign the object to the passed scope and property.

The first thing that you will most likely be thinking at this moment is why not use the prototype model as most likely we would have a fair number of these properties created.  You would of course be 100% correct; using the prototype model would be more efficient.  But herein lies the key issue with the prototype model. Any prototyped method can only use the this keyword to refer to the instance on the object that is calling the method.  This being the cased how do you get the protected value since it is not exposed within the object.  To use the prototype model you would have to expose the value within the instance which defeats the very purpose of creating setters and getters in the first place.  Although I love the prototype patter I see the issue of closures on the instance being the most significant drawback to the implementation.

Over the past several posts I have introduced some key ideas for design patters, function implementations etc. In my next post I will be putting them into a framework entitled mf.  I choose mf not to reflect Mr. Purple and his Sexy Mf but rather it stands for my framework.  Although in times of frustration one could use the other definition! Once we have the basic framework set out I will be introducing how to write your own event component followed by some other key components you need to have in a custom framework.

Until then…cheers

I am a real bugger when it comes to how my code is organized. Given the advanced user interfaces that we have today I have often noticed that JavaScript developers have become, for lack of a better adjective, bloody lazy!  Before we get into the singleton design patter a short discussion is warranted on when a singleton should be used versus a class that supports instantiation.

The most common examples of a singleton are existing JavaScript frameworks such as ExtJs, jQuery, etc. In essence we would only ever have a single instance of each of these frameworks each represented by its own unique namespace Ext and $ respectively. The other most common example of the singleton pattern is the root namespace that represents your JavaScript application because you would under most circumstances only have one. Note I said most circumstances.  There is often the case in the real world where a requirement initially requires a singleton pattern but over time it becomes evident that a class instance would be better.  The golden rule of ‘the only constant is change’ should always be kept in mind when designing your code structures. The purpose of this post is to demonstrate how to effectively use the singleton pattern properly and in such a way as to allow for the easy migration to a class pattern. The secondary goal is to show how writing your singletons in this fashion leads to consistency of code which is something we should all strive for!

First let’s look at the basic singleton design pattern that I often see exemplified on the web.

var mySingleton = {
                 globalVar1 : null,
                 globalVar2 : null,
                 myMethod1 : function(){},
                 myMethod2 : function(){}
 }

So I will state this very clearly and strongly, the above is NOT a singleton.  In my opinion this is a simple object that does nothing more provide a hierarchical structure of variables and methods under a root namespace.  For starters this pattern does NOT use closures and does not have the concept of private/protected vs public methods and variables. At a minimum the singleton design pattern should be written as follows.

var mySingleton = ( function(){

                 // private/protected variables and methods
                 var myVar1 = null,
                 myVar2 = null,
                 method1 = function(){…}
                 method2 = function()(){…};

                 // public variables and methods
                 return {
                                 publicVar1 : null,
                                 publicVar2 : null,
                                 publicMethod1 : function(){…},
                                 publicMethod2 : function(){…}
                 }
 }());

As we can see the singleton is wrapped in an out closure with an inner function that immediately executes upon load.  Methods and variables that need to be exposed to a consumer are defined within the return statement. So far so good, but nowhere good enough for me. At the beginning of this post I said I was a real bugger about code design.  In my humble opinion with a touch of ego a singleton or for that matter an instantiable class has the following basic namespaces.

In JavaScript terms this would be written as follows:

var mySingleton = (function(){

                 // Container Object for singleton configuration variables 
                 Config = {},

                 // Container object for private/protect methods
                 Private = {},

                 // Container object for shared methods
                 Shared = {},

                 // Container object for public methods
                 Public = {}, 

                 // Initialization actions
                 initialization = function(){}();

                 return Public;
 }());

Not the initialization function that auto executes before the outer singleton is itself executed and returns its result, in this case anything defined within the inner Public namespace. The Config namespace (ns) is for internal properties or variables that are consumed internally by the singleton.  In essence they are protected/private and therefore could exist within the Private ns. I simply prefer to have them at the root of the singleton at the very top for ease is access when trolling through the code. Note that each of the root ns’s are capitalized.  This is because public and private are both reserved words for future use in JavaScript. My choices of the root namespaces are purely personal and of course you could use any you choose such as Protected versus Private.  The primary purpose though is to logically break up your code for readability.  So long as you are consistent in your implementation that is all that matters. Note also that I define a singleton global variable called me to refer to the singleton itself.

You may at this point be questioning the use of the Shared ns but there is an important definition within the object.  Shared methods are those methods that are consumed by both Public and Private methods.  I cannot name the number of times where I have code within Private that needs to be replicated by Public.  Any such code with then go into Shared. The importance of this is for legibility and to reduce code errors during future enhancements to the class. When a developer is asked to modify a Public method on the class and they see that the method points to a Shared method they immediately know that they need to look at how it is called from the Private method.  This helps to reduce noodled code as I like to call it because I hate noodles but love spaghetti! Let’s look at some pseudo code as an example:

var mySingleton = (function(){
                 var Config = {},
                 Private = {
                                 iAmPrivateMethod1 : function(){
                                                 Shared.method1()
                                 }
                 },
                 Shared = {
                                 method1 : function(){…}
                 },
                 Public = {
                                 method1 : function(){
                                                 Shared.method1()
                                 }
                 }, 
                 initialization = function(){}();
                 return Public;
 }());

Not something important in the above Public ns.The method1 function is not a direct pointer to to Shared.method1 and it NEVER should be. Public methods should always have their own distinct closure, as the British would say ‘It’s just good form’. Notice something else though, the readability of the code becomes very apparent to the developer. This is an incredibly important aspect of good code development, ‘do not write code for just yourself’. To assume that the code you are presently writing will never have to be modified by you later on or by another developer is simply pure ignorance.  I write by the motto of what comes around goes around, well hopefully someday it will, but that’s not the point.

Now that we have the basics of a good Singleton pattern done, let’s look at how we can use basically the exact same pattern for a class.

var mySingleton = (function(){
                 var Config = {},
                 Private = {
                                 iAmPrivateMethod1 : function(instance){
                                                 Shared.method1(instance)
                                 }
                 },
                 Shared = {
                                 method1 : function(instance){…}
                 },
                 Public = {
                                 method1 : function(){
                                                 Shared.method1(this)
                                 }
                 }, 
                 initialization = function(){}();

                 var Component = function(config){
                                 // initialization code for instance
                                 Private.iAmPrivateMethod1(this);
                                 return this;
                 };
                 component.prototype.method1 = Public.method1;
                 return Component;
 }());

As you can see from the above code we now return Component which is of course a function that can be called with the new method as in, myinstance = new mySingleton({config}). All that has really changed is what we are returning and the fact that we now pass around this t represent the instance to the Shared and Private methods.  When the Component is instantiated any private methods should be called to define what is required for your component/widget.  The Private methods are only ever called once on instantiation of the instance.  This is where Private becomes much more apparent. Public methods are also prototyped into the component class and point to the subsequent Public methods.

Granted if you had many methods or parameters within the Public ns you would have a lot of prototype lines after your component definition.  In my next post I will demonstrate how to optimize this process with a single call as well as how to create automatic setters and getters for variables you may wish to expose in your class.

Until then, Cheers
Keith

So imagine the below scenario:

So in the above image there are three shapes.  The blue square has been selected and when any of the 3 horizontal rulers comes into contact with the top, middle or bottom of the other shapes they would need to appear.  Same goes for the vertical if the user where to drag the blue square to the right. So this means that for each element/shape on the page there are 3 vertical and 3 horizontal points to compare to the current points on the actively dragged element, in this case the blue box. Now consider you could have any number of shapes you need to align to! This leads one to the conclusion that any sort of heavy on the fly calculation while dragging will simply destroy performance.  So the question then becomes how can we do this with ZERO calculations/conditions while the selected element is being dragged.  The answer is YES we can and here is how. Just a quick note regarding some of the code, in order to preserve the privacy of the application I am not using the general namespace we use for our toolkit that provides DOM manipulation. However you can easily see how to do this in jQuery, ExtJS etc.  The point is the solution not so much the implementation.

Creating the Component

The first step is to create our basic component framework.  Each piece of functionality I call a component and all of its behavior is neatly encapsulated in the file for easy modification.  Since this component is a singleton we will use Crockford’s singleton patter.

(function(){

      // the canvas element we exist in 
      var canvas = me.element.get('canvas');

      // set up the necessary static values
      var config = {
         width : canvas.width(),
         height : canvas.height(),
         tolerance : Number(8),
         baseTolerance : ‘k’,
         maxToleranceRange = 'kjihgfedcbabcdefghijk',
         activeTolerance= (config.maxToleranceRange.substring(10-tolerance,9+tolerance)).split(''),
      },

      // object to hold the map cordinates      
      map = {
         x : null,
         y : null
      },

      // Small function to help with setting the colorScale object
      getIncrementStyle = function(){},

      // Object to hold dynamic ruler styles
      colorScale = {},

      // create our rulers initially 
      rulers = {
          top : canvas.append(me.create({cls:'ruler horizontal top'})),
          middle : canvas.append(me.create({cls:'ruler horizontal’})),
          bottom : canvas.append(me.create({cls:'ruler horizontal’})),
          left : canvas.append(me.create({cls:'ruler vertical’})),
          center : canvas.append(me.create({cls:'ruler vertical’})),
          right : canvas.append(me.create({cls:'ruler vertical’}))
      },

      createRulerMap = function(){},
      hideRulers = function(){},
      trackRulers = function(){};

      // Bind to the necessary system events
      me.subscribe(‘me.element.selected’,createRulerMap);
      me.subscribe(‘me.element.deselected’,hideRulers);
      me.subscribe(‘me.canvas.dragMoved’,trackRulers);
      me.subscribe(‘me.canvas.dragEnd’,hideRulers);  
      return {};
}())

So all we have done at this point is lay out our basic framework which grabs the width and height of our work area and creates the rulers and assigns them to the rulers object for quick reference later one.  I will discuss the tolerance, maxToleranceRange and baseTolerance a little later on. I have also bound to the basic events in the system. The first one is the element selected which gets fired when an element/shape is selected on the canvas.  This is when we will create our map of other elements. The other is the element deselected and canvas drag end which in both cases will hide the rulers.

Note that in the rulers object where I am created the rulers I am assigning several CSS classes to each.  Here is the basic CSS:

.ruler{
   background-color:transparent;
   border-top-width:1px;
   border-left-width:1px;
   position:absolute;
   display:none;
 }
. horizontal{
   height:0px;
   left:0px;
   border-bottom:none !important;
   border-left:none !important;
   border-right:none !important;
 }
. vertical{
   width:0px;
   top:0px;
   border-right:none !important;
   border-top:none !important;
   border-bottom:none !important;
 }

Now some may argue why create the rulers initially rather than on demand to save DOM weight.  My argument against that is speed.  For this specific behavior we have to ensure no lag when the user clicks on an element and begins to drag.  Otherwise I would create on demand then destroy when no longer needed.

Creating the X and Y Map

So based on our initial component layout when an element on our canvas is selected we call the createRulerMap function, this is where our config.baseTolerance comes in. First we need to create a string of the baseTolerance keys based on the config.width  and place in map.y and conversely for map.x.

map.x = (Array(Number(config.width)).join(baseTolerance).split(‘’);
map.y = (Array(Number(config.height)).join(baseTolerance).split(‘’);

In essence create an empty array for the necessary width or height then join it with the base tolerance value. So if our base tolerance is k and the width is 1200 we end up with a string of 1200 k’s which we then split back into an array each containing a k. In other words we have a shit load of K’s!

Now let’s assume for now that we have one other element on the canvas that is 100 by 100 pixels in size and is at position X 200 and Y 200. So for this element we need to gets its 3 vertical positions and 3 horizontal positions to align the rulers to by placing those coordinates in our map. Let’s assume we have gotten our element in question and assigned it to the variable element.

var coords = {
   left : Number(element.x()),
   top : Number(element.y()),
   right : Number(element.x()) + Number(element.width()),
   bottom : Number(element.y()) + Number(element.height()),
   center : 0,
   middle : 0
};
coords.center = coords.left + parseInt(cords.right/2,10);
coords.middle = coords.top + parseInt(coords.bottom/2,10);

So now we have a coords object with left:200, top:200, right:300, bottom:300, center:250 and middle 250.

Now we come back to the config.activeTolerance and config.maxTolerance values along with the config.tolerance level. If we look at our config.activeTolerance we get the following result hgfedcbabcdefgh, this is based on the config.tolerance level which goes either side of the center of the string for the value specific in config.tolerance. If we look at the map.x presently we have a bunch ok baseTolerance k’s and now we need to insert the active tolerance where A sits at the exact coordinate. Therefore assuming our first X coordinate, coords.left, we need to insert it at position 200 in the map.x string.  What we would want to see is in essence:

…..kkkkkkkkkhgefdcbabcdefghkkkkkkkkkk….

However we could have more than one element on the page that we have to account for. What happens if there is another element sitting at X205, we need to account for that. So let’s work on doing our enumeration:

createRulerMap = function(){

   // This grabs all of canvas elements with a class of moveableElement
   var elements = canvas.filter(‘moveableElement’),

   // get the Dom ID of the currently selected element
   currentElementId = me.currentElement.id(),

   setTolerance = function(startPoint,mapCoord){                       
       var startPoint -= config.tolerance;
       for(var point=0;point<(config.tolerance*2)-1;point++){
           map[mapCoord][(point+startPoint)]=activeTolerance[point]<map[mapCoord][(point+startPoint)]?activeTolerance[point]:map[mapCoord][(point+startPoint)];
       };
       return null;
    };

    for(var element = 0; element < elements.length; element++){
        if(elements[element].id()!=currentElementId){
            var coords = {
                left : Number(element.x()),
                top : Number(element.y()),
                right : Number(element.x()) + Number(element.width()),
                bottom : Number(element.y()) + Number(element.height()),
                center : 0,
                middle : 0
            };
            coords.center = coords.left + parseInt(cords.right/2,10);
            coords.middle = coords.top + parseInt(coords.bottom/2,10)
            setTolerance(coords.left,’x’);
            setTolerance(coords.right,’x’);
            setTolerance(coords.center,’x’);
            setTolerance(coords.top,’y’);
            setTolerance(coords.bottom,’y’);
            setTolerance(coords.middle,’y’);
        };
     };
     map.x=map.x.join(‘’);
     map.y=map.j.join(‘’);
 }

So I think I little explanation of the inline setTolerance may be in order at this point so I will lay it out here. Here it is broken down :

// @param : startPoint (integer) position of the value we wish to put the string at;
// @param : mapCoord (string) either the string x or y to indicate what map string we are testing against
function(startPoint,mapCoord){
     // The start point in the array that we wish to check against is the passed coordinate minus the actual tolerance, so if x is 200 it would be 200-8
     var startPoint -= config.tolerance;

     // now enumerate through the tolerance * 2 but minus 1 because there is only one center value of A
     for(var point=0;point<(config.tolerance*2)-1;point++){

        // set map[ x or y](the loop value plus the startPoint      
        map[mapCoord][(point+startPoint)] =

        // test if the present value in the tolerance string is less than the value presently in the array at point+startPoint. This test works because A is less than B and B is less than C etc.
        (activeTolerance[point]<map[mapCoord][(point+startPoint)])?

        // if less then put in the tolerance letter otherwise leave what is in there.
        activeTolerance[point]:map[mapCoord][(point+startPoint)];
     };
     return null;
 };

So in the case of have 2 objects at X 200 and X 205 you would end up with the following snippet in the map.x string:

…..kkkkkkkkkhgefdcbabccbabcdefghkkkkkkkk….

At the end of our function we merge the map.x and map.y arrays back into single strings.

Tracking the Drag and doing the Magic bits

Now that we have our X and Y map we need to start tracking the drag behavior and decide when it is appropriate to display the necessary ruler. Before we do that however, we need to create our set of style rules that indicate how to display a ruler. If you remember back to when we created the basic framework for the component I declared an empty object variable entitled colorMap in the global scope of the component. To define this object first I first create a simple function that creates a style based on an integer value passed in, this is placed about the colorScale definition.

getIncrementStyle = function(x){
  var opacity=(((tolerance-x)+1)/10);
  return ';display:block;border-width:'+x+'px;opacity:'+opacity+';filter:alpha(opacity='+(opacity*100)+')'
}

Now we define our coloScale:

colorScale = {
  k:'',
  j:'border-color:#f80708;border-style:solid'+getIncrementStyle(10),
  i:'border-color:#f80708;border-style:solid'+getIncrementStyle(9),
  h:'border-color:#f80708;border-style:solid'+getIncrementStyle(8),
  g:'border-color:#f80708;border-style:solid'+getIncrementStyle(7),
  f:'border-color:#f80708;border-style:solid'+getIncrementStyle(6),
  e:'border-color:#f80708;border-style:solid'+getIncrementStyle(5),
  d:'border-color:#f80708;border-style:solid'+getIncrementStyle(4),
  c:'border-color:#f80708;border-style:solid'+getIncrementStyle(3),
  b:'border-color:#f80708;border-style:solid'+getIncrementStyle(2),
  a:'border-color:#00fffc;border-style:solid;display:block'
}

Now the getIncrementStyle is completely optional but it simply resulted in less coding for me and allowed me to play with the style a little more easily.  Note the value for k does not specify display of block.  This is because it is our config.baseTolerance. Also remember that the default style for the rulers based on its CSS is rules is display of none.  So when the ruler K is assigned to a ruler it is not displayed. In this style implementation the opacity of the ruler and width increases as a user gets closer to A until we hit A then simple make the ruler a solid dark line.

Now the final method of trackRulers, which is called during the drag event on our canvas element. This now becomes very simple.

trackMove = function(){
   var currentElement = me.currentElement,
   left = currentElement.x(),
   top = currentElement.y(),
   center = left + parseInt(currentElement.width().2,10),
   middle = top + parseInt(currentElement.height()/2,10),
   right = ((center-left)*2)+left,
   bottom = currentElement.height()+top;

   // apply the styles based on the letter found in the map which provides us our color via the colorScale object
   rulers.top.attribute('style',colorScale[map.y.substr(top,1)]+';top:'+top+'px;width:'+config.width+'px');
   rulers.middle.attribute('style',colorScale[map.y.substr(middle,1)]+';top:'+center+'px;width:'+config.width+'px');
   rulers.bottom.attribute('style',colorScale[map.y.substr(bottom,1)]+';top:'+bottom+'px;width:'+config.width+'px');
   rulers.left.attribute('style',colorScale[map.x.substr(left,1)]+';left:'+left+'px;height:'+config.height+'px');
   rulers.center.attribute('style',colorScale[map.x.substr(center,1)]+';left:'+xCenter+'px;height:'+config.height+'px');
   rulers.right.attribute('style',colorScale[map.x.substr(right,1)]+';left:'+right+'px;height:'+config.height+'px');
   return null;
}

So as you can see there are NO calculations going on during the applying of the styles to each of the six rulers. In this implementation I set the map.x and map.y to strings and then used the substr method to get the appropriate letter to get the style.  I am not sure why I simply did not leave it as an array in the first place there by negating the need for a substr calculation. But as they say hind sight is 20/20. Note also when setting the style attribute of each ruler I set horizontal rulers width to the config.width and the vertical rulers to config.height.  Each of these config values where defined at component start up time to the height and width of our working canvas area.

I have uploaded a screen cast of the alignment rulers in action at http://screencast.com/t/MGjZ1mej3be. In my implementation the users have the ability to always have rulers on when they select an element which the video demonstrates.

{Elegance Sometimes Happens}

I added this to the title of this post because I consider this an elegant solution to what may first appear as a simple piece of functionality but when you dig a little deeper you realize it is not. It is often the case that elegance is driven by necessity. In this case I had to find a solution that required as small of a footprint as possible while an element was being dragged around the screen.  This was required in order to ensure there was no choppy behavior that would ruin the user experience. This is one of the key factors of elegance, provide an efficient and usable user experience.  Here are some other factors of code elegance:

1. Encapsulated within a closure,
2. Does not rely on other components and therefore stands alone,
3. Easy to read,
4. Small foot print,
5. Simple and clean,
6. Easily customizable,
7. Ratio between size and complexity vs functional behavior and user experience is high

How often have we seen function grow over time with just one more parameter added for that supposed last little piece of functionality we have to add. Far too often I would imagine.  Then add in the new requirement that some of the parameters on the function need to be optional and the next thing you know you are in a world of hurt. There is a basic maxim in any software development, the only constant is change. As a result as a software writer I strive to ensure my code recognizes this maxim along with a couple of others.

Alas for JavaScript, the poor Yorick of languages we all know so well, it does not give us a lot of flexibility in the function object. Unlike other languages, even SQL, functions/methods provide much greater flexibility in there definition, including default values, optional parameters, name parameter calling, e.t.c. It would certainly be nice if we could provide a similar model to JS function calls and definitions. Many a moon a go I started developing in ExtJS and was introduced to a very simple method called Ext.apply and Ext.applyIf. In essence these methods take two objects as parameters and merge them into one. So if you call Ext.apply({a:1,b:2},{c:1}) you would get back {a:1,b:2,c:1}.  Sounds simple enough right? The applyIf works in the same fashion but makes a test in the receiving object to see if the property already exists and if so does not over write it. This is a very simple piece of code that we can look at below:

function applyIf(objectTo,objectFrom){
              if(objectTo){
                          for(var property in objectFrom){
                                      if(typeof objectTo[property] == 'undefined' ){
                                                  objectTo[propety] = objectFrom[property];
                                      }
                          }
              }
              return objecTo;
  }

So in essence, enumerate through the properties in objectFrom and if the property does not exist in the objectTo then add the property and its value from the objectFrom. So what does this have to do with functions you are probably asking? Let’s have a look at a mythical function as an example

function doSomethingCool(
              // width of element
              width,
              // height of element
              height,  
              // text of element
              text,
              // optional x and y, element type and style string
              ,x,y,elType,style){…do some stuff}

Looks simple enough but what’s with the four of optional parameters at the end of the function.  As you well know from in your function code you end up with a bunch of if statements along the lines of if(x===undefined){x=0}.  This of course gets to be a pain in the code rear. Now let’s change our function to accept to a single parameters as an object.

function doSomethingCool(config){
            config=applyIf(config,{
                          width : null,
                          height : null,
                          text : ’’,
                          x : 0,
                          y : 0,
                          elType : ‘div’,
                          style : ‘position:relative’
              })
… do some stuff
  }

So now in our doSomethingCool function we can easily default each parameter in our function and reduce the amount of if conditions to test for them.  By defaulting each of our values we also reduce the risk of errors being introduced by bad callers.

This may seem like a simple idea but it has a couple of extremely important advantages.  How many times have you had to go and look up a function you wish to call to check the order or the parameters? I would guess far too many times. Using a single parameters object order of the values in the object to not matter. But there is a far more important reason to use this method and that is in regards to the caller.  In the standard function design you would see some code calling the method like thus:

doSomethingCool(10,10,’my text to display’,undefined,undefined,’span’)

Really does not really tell you much when you look at it does it. When another developer has to go through your code the above line tells him/her absolutely nothing and forces them to go and look at the doSomethingCool function to determine what 10 and 10 is and why are there two undefined. Now lets make the same call to the function using the config object parameters:

doSomethingCool({
              width : 10,
              elType : ‘span’,
              height : 10,
              text : ‘my text to desolay’ 
  })

Looks a lot better doesn’t it! Not only is it very clear on what we are passing, we also did not need to add in a bunch of undefined definitions to get to the elType parameter. Notice also that in the above the order of object properties do not matter either.

A couple of noteworthy things about implementing your functions this way. If you need to add another parameter to your doSomethingCool function you can simply default it the default config object that is applied without any concern of impacting existing callers.  Another great benefit is code readability. How often have you had to take someone else’s code over? Now imagine reading through that code and seeing all these clearly understandable calls.  Not only does it benefit you when you need to revisit something but it will benefits the next developer who has to hit your code to make a modification.

In the next part of the series I will be exploring Crockford’s singleton pattern vs the prototypal pattern and how to merge, extend them and organize code.

So after several days of adding to a JavaScript Coding Standards document explaining Design Patterns at my most recent job, it got me to thinking ‘how can I protect the code yet not loose any flexibility that the Module Pattern provides?‘ It’s one of those problems you think about when you go to sleep and are still going at it when you awake at sunrise and stubbornly refuse to get up despite your brain saying ‘get at it lad’ just to add to the encouragement from your bladder. Like many problems you fiddle about with code constantly hitting F5 in your browser as your brain goes into overdrive as it is fully convinced this has to be possible!  Then the solution hits you and you exclaim to yourself ‘man that’s so f’ing obvious and simple what was I thinking!!‘.  The solution is wrap your singleton in an anonymous function – duh! So here you go enjoy:

(function(){

	var myApp =function(){
		//add your application code here as you normally would
	}();

}());

Yes its that simple!  In essence wrap your application in an anonymous function.  So long as all of your child classes within myApp reference myApp.whatever then no problem.  Give it a try then hit your page with Firebug or any other dev tool and look in vain for myApp, you will not find it.

But this introduces a problem.  Your busy working on your highly complex web app and you need to be able to do console.log statements to my app. Well no problem:

(function(){

	var DEBUG = true,

	var myApp =function(){
		//add your application code here as you normally would
	}();

	if(DEBUG){
		window.MyApp=myApp
	}
}());

Now you can debug to your hearts content and when ready for the big release set your DEBUG switch to false.  So now the next issue, ‘ya that’s all very nice Keith but I NEED to expose some of my methods for consumption by 3rd parties‘.  Again very simple:

(function(){

	var DEBUG = true,
	EXPOSED_NS = 'ForTheCosumer';

	var myApp =function(){
		//add your application code here as you normally would
		return {
			DoSomething 	: function(){},
			DoSomethingElse : function(){}
		}
	}();

	// expose my public methods
	window[EXPOSED_NS]={
		doSomething 	: myApp.DoSomething,
		doSomethingElse	: myApp.DoSomethingElse
	};

	if(DEBUG){
		window.MyApp=myApp
	}
}());

So thats about all there is to it.  In my next post I will deal with another contentious issue with the Module Pattern. Code segmentation into separate files and how to get them into your now hidden application.

Cheers

Keith

Since I am very evidently sticking my nose out I had best explain ‘What is Elegence?’ In terms of a JS implementation the object model should provide for an obvious segmentation of functional areas that reflect their purpose and the interface itself.  Having an overly flattened object model simply makes it confusing for developers to inherit the code base and work with it.  I usually layout my base class with the following structure. 

• .ui
  Contains all of the components that make up the base interface.  Most often this a direct pointer to the created viewport.
• .user
  The user class holds the context of the currently logged in user and any methods for login, logout, options etc.  It will contain interface components/methods but most often these are modal dialog in nature so do not impact on UI. The user class should also provide for permission methods.
• .remote
  The remote class is most often a function and is in charge of ALL remote calls whenever possible.  It is important that an attempt be made to push all of your remote REST calls or any server requests through a single point of entry/exit.  In some cases this is not possible, for example with a tree control or with a panel with autoLoad set, but these are special circumstances.
• .component
  The component object is a holder for specific component objects that your interface supports. It relies on both ui and user classes.  Often I have a common or core subclass within component that provides for common functionality that is shared amongst components.
• .util
  A catch all class for methods that support all the other primary classes.
• .config
  I flip flop on this one frequently.  The config object is used to store configuration objects that are commonly used throughout the application.  For example default panel configs that are applied with Ext.applyIf within functions.  I flip/flop on this one because with it being exposed it opens opportunity for nosey hackers to fiddle with it and introduce behaviors.

In many cases I see very large flattened object models and exposed components because for some very bizarre reason people have not picked up on the ref property of a container config in ExtJS.  Ref is your best friend and simplifies your life.  As you may well know one of the major challenges in ExtJS or any JS application is maintaining a reference to that object you just created.  Sometimes we drop in our on ID so that we can use Ext.getCmp(‘thatDangObject’) or pre-create a id with Ext.id, add it to the config and store the id somewhere for later retrieval.  Well by using the ref function you do not need to.  For example let’s look at a standard 3 panel viewport with a North, South, Center layout. 

First off you will note __root.ui, __root is a reference to the base class of the application but I will get to that a little later.  For now you can assume that myapp.ui is now a pointer to the created ExtJS viewport object.  If you were to use FireBug and look at myapp.ui within the DOM explorer you would see under myapp.ui, _panelNorth, _panelWest and _panelCenter.  A quick comment, if you have not heard of Firebug stop reading this article, get it, learn how to use then by all means come back and read the rest. A note about my use of the underscore in the ref property.  I use this for two reasons.  One, I know that the ref name I come up with will NOT conflict with any ExtJS property and more importantly they show at the top of the list in the DOM explorer when expanding the object. 

__root.ui= new Ext.Viewport({
layout: 'border',
items: [
{region:’north’, ref:’_panelNorth’},
{region:’west:’, ref:’_panelWest’},
{region:’center’,ref:’_panelCenter’}
]});

With ref one of the very spectacular things you can do is move it up the object hierarchy by the use of ‘..\’. So for example if I had a tbar in the _panelNorth and I want to have it exist within the DOM hierarchy directly under myapp.ui I could add in ref:’..\_topTbar’ in the tbar config within the north panel.  There are cases you may want to do this but remember if you do then you loose your logical object flow in your code which means as a result you had better name it something very logical.  For example really which is better of the below two: 

                myapp.ui._panelNorth._topToolBar
                myapp.ui._panelNorthTopToolBar 

Personally I prefer the first case because that little ol’ dot tells me something directly where as in the later example I am trusting the name to indicate it.  I will defer to dot whenever I can! 

‘Dude it’s an object no need to wrap it more’, this is one of my favorite issues I see in ExtJS development.  Creating components that wrap ExtJS components because of the need to track some aspect of that component.  It is kind of akin to that annoying Uncle who thought it was cute to wrap a small present inside a big box that was also wrapped.  It’s not funny and it just adds waste!  Waste is the important word here.  Not only are you wasting time but you’re wasting memory and my time while I try to figure out what the hell you are trying to do.  You can add anything to an ExtJS config object and it will show up as part of that object.  Take for example the following panel config: 

__root.ui._panelCenter.add({
	xtype:’panel’,
	ref:’_panelForSomething’,
	_myProperty1:’abc’,
	_myProperty2:’def’,
	_myMethod:function(){callmyprivateMethod(this)}
})

Now when I want to get to _myProperty in this added panel I can simply say myapp.ui._panelCenter._panelForSomething._myProperty1 and I get abc.  What I often see is the reverse where a class has been created that contains the control and a lot of extra code expended to make available certain properties/methods of the container available for consumption.  If you are comfortable with the security issues of this then make use of that ExtJS object.  There is a reason they have the functions Ext.apply and Ext.applyIf, read up on them as they are another best friend of ExtJS development.  A small comment on the use of underscore!  I realize and recognize that this is not a recommended implementation according to Mr. Crockford but I would argue this point with him with some zealousness and perhaps a slight grin on my face that I am arguing with Douglas Crockford! 

I mentioned the term security and this leads me to my next point. Not everything needs to be a publicly accessible method or property. Object scope is an incredibly important aspect of any complex application design and making EVERYTHING scoped at the object level is just asking for some pimple faced annoying genius kid to go nutty on your application in Firebug and post it up to the world in some sense of accomplishment over your lack of thinking!  This is where ‘design patterns’ come in, there are many, most notably Douglas Crockford’s. It is Crockford’s implementation that is used witin ExtJS for components. I could probably dedicate an entire book or a least a lengthy blog post to JS design patterns for the purposes of this discussion I will outline two that I use primarily.  The first is a basic class that one instance of will be created for the purpose of service the application. 

function myClass(scope){

	// private variables
	var _me = this;			// internal reference
	var __root = scope		// constructor reference
	var pTermLength = null		// exposed property

	// private methods
	function doSomething(){};

	// shared methods
	function pIAmASharedMethod(){};

	// shared property setters/getters
	function pSetTermLength(v){pTermLength=v};
	function pSetTermLength(){return pTermLength};

	// public methods/properties
	this.doSomething=pIAmASharedMethod;
	this.getTermLength=pGetTermLength;
	this.setTermLength=pSetTermLength;
	this.letItAllHangOut=new Number(1)
}

Notice that in this class we only have 3 exposed or public methods and one exposed variable name.  I like to have my public methods point to private functions.  This allows for internal/private functions to call them directly without the use of the this reserved word.  It also means that your exposed methods and properties are simply pointers.  When using this style of implementation it is important that you come to a consistent naming convention on the function and variable declarations. With regards to variables the basic rule of thumb is you should not let them hang out there publicly but rather create public setter and getter methods.  If the variable has a direct impact on the behavior of the class and typing is important then don’t just let it hang out there for consumption and override. Using a getter/setter implementation allows for you to check type and value scope of the var before fubarring your class.  Now I will fall back to Mr. Crockford and his implementation which is slightly different and serves a different purpose.  Remember the above example is for a class that will behave more like a singleton. ‘Why not a singleton’ you ask, well I will get to that next.  Mr. Cockford would say the above implementation should be done thus: 

function myClass(scope){

	// private variables
	var _me = this;			// internal reference
	var __root = scope		// constructor reference
	var pTermLength = null	// exposed property

	// private methods
	function doSomething(){};

	// shared methods
	function pIAmASharedMethod(){};

	// shared property setters/getters
	function pSetTermLength(v){pTermLength=v};
	function pSetTermLength(){return pTermLength};

	// public methods/properties
	return {
		doSomething : pIAmASharedMethod,
		getTermLength : pGetTermLength,
		setTermLength : pSetTermLength,
		letItAllHangOut : new Number(1)
	};
}

Note that in this case that when creating an instance of the class it returns an object which in essence does the same thing as the earlier class.  The difference is that the return statement returns an object which is in essence a singleton or in this case a singleton expressing the instance of the object.  My problem is that a singleton implementation is extremely limiting in its internal scope referencing.  You must follow the object convention of using commas and can NOT have locally scoped variables within the return object.  The argument would be that you should not have locally scoped variables within the returned object but I feel that is limiting.  This leads me to the second style of class implementation and for this let’s try and use a real world example to show why.  Let’s assume we have an application with a standard viewport.  On the left is a tree in which a bunch of users are listed.  In the center panel we have a tabpanel implementation.  When the user selects a user in the tree we have to create a new tab panel for that user.  Obviously then we are going to have a class that manages the interface for the selected user in the tab panel.  In Mr. Crockford’s implementation we would have a class which we would create an instance of and part of its initialization would be to create the interface.  Problem here though is we now have to write a bunch of code to manage the instances of user we have created.  Where should that code go then within are architecture?  Logically it should go in the user class itself but that class is only designed to manage an instance of a user not instances. 

Remember way back in this article I had a child class of off base entitled component.  Well this is where out component would go.  Let’s look at the code for our user class that manages multiple instances: 

function myClass(scope){

	// private variables
	var _me = this;			// internal reference
	var __root = scope		// constructor reference
	var pTermLength = null	// exposed property
	var instances=[];

	// private methods
	function doSomething(){};
	function createInterface(instance){
		// create the interface for the instance and store
		instances.push(__root.ui.center.add(instance.config))
	}

	// shared methods
	function pIAmASharedMethod(instance){};
	function pcloseAllUsers(){
		Ext.each(instances,function(o){
			__root.ui.center.hideTabPanel(o.id)
		})
	}

	// shared property setters/getters
	function pSetTermLength(v){pTermLength=v};
	function pSetTermLength(){return pTermLength};

	// public methods
	this.closeAllUsers=

	// start component
	this.component=function(config){
		var _me=this;				// pointer to this instance
		var myTermLength=1			// local instance variable

		function initialize(){
			createInterface(_me)
		};
		this.config=config
		this.doSomething = function(){pIAmASharedMethod(_me)},
		this.getGlobalTermLength = function(){return pGetTermLength()},
		this.setGlobalTermLength = function(v){pSetTermLength(v)},
		this.getTermLength=function(){return myTermLength},
		this.setTermLength=function(v){myTermLength=v}
		this.letItAllHangOut = new Number(1)		

		// init instance
		initialize();

		return _me;
	}; //-> end component
}

Notice a couple of things: 

1. Initially we created a single instance of this class with myapp.component.user=new myClass(this) where this is a pointer to the root of our application myapp.  This means that the class can now get to any of our child classes, such as ui via the locally scoped variable __root.
2. When we want to create a new user interface we call new myapp.component.user.component({some config})
3. The component creates a locally scoped variable entitled _me that points to its self. On creation the internal initialize function is called which in turn calls the base class createInterface function and passes an instance of its self.
4. Since createInterface is passed a pointer to the instance and instance has a public property that points to the passed config our createInterface method in the base class can now say create the tab panel using the passed instance.config.  The createInterface stores a pointer to it in a LOCALLY scoped array.
5. When creating the component it returns a reference to itself for further manipulation.

Now a couple of other things.  Let’s assume that the config we pass to the component creation contains a ref value, for example it is set to ‘userABC’. Now if we want to get to it publicly through our object hierarchy it would be myapp.ui._panelCenter.userABC.  This of course would only get us to the ExtJS component.  Now is where things can get a bit confusing and there are several approaches you can use depending on your requirement. 

For arguments sake let’s assume you want to be able to get to that control directly then you could do this.  Remember you can add anything to that config! 

// start component
	this.component=function(config){
		var _me=this;				// pointer to this instance
		var myTermLength=1			// local instance variable

		function initialize(){
			createInterface(_me)
		};
		this.config=config
		config._doSomething = function(){pIAmASharedMethod(_me)},
		config._getGlobalTermLength = function(){return pGetTermLength()},
		config._setGlobalTermLength = function(v){pSetTermLength(v)},
		config._getTermLength=function(){return myTermLength},
		config._setTermLength=function(v){myTermLength=v}
		config._letItAllHangOut = new Number(1)		

		// init instance
		initialize(config)
	}; //-> end component

Now we have added our public component methods as part of the config of the ExtJS object.  So now I can say myapp.ui._panelCenter.userABC._doSomething() 

The advantage of doing this is of course the base user class when enumerating through its array of component instances can access each of the public methods of each since they are part of the ExtJS component. 

How you decide to implement these types of components comes down to what your needs are.  Questions such as does this need to be accessible from other classes, what are the security risks of being public exposed, do I need a component or will a singleton do?  Should my controller base class provide all the functionality needed? 

In my next post I will discuss the overuse of Ext.extend and Observable. When to use it and when to not use it. 

One last thing to think on… config.instance=_me!!  Now you’re going down the rabbit hole and saying to yourself ‘I should have taken the blue pill’  Try it and see what you see in Firebug DOM J 

Until then….cheers 

Keith Chadwick