JavaScript Singleton in XPages

So, I’ve been cleaning up a lot of my “first starting” mess here in XBlog. The Posts, Comments and Pages are now “componentized” as opposed to being just generated HTML. Don’t get me wrong there is still a lot of “generated” HTML here, but it’s at least getting to be more manageable. But during this clean up I decided to implement a client side API of sorts and the best way to do that is to create a JavaScript Singleton to hold all the CSJS functions and properties as that would provide the most robust solution to provide other people the ability to expand XBlog.

What is a singleton? Well here’s a rather broad definition from Wikipedia

In software engineering, the singleton pattern is a design pattern used to implement the mathematical concept of a singleton, by restricting the instantiation of a class to one object. This is useful when exactly one object is needed to coordinate actions across the system. The concept is sometimes generalized to systems that operate more efficiently when only one object exists, or that restrict the instantiation to a certain number of objects.

I don’t know about you but after reading that I really don’t know any more than what I started with. But in general terms a singleton is a Javascript class. It’s also a global object of methods and properties. A good example of a singleton is to take a look in Firebug, under the DOM tab and you should see the singleton/names space for dojo, dijit, XSP, etc.
FireBugSingletons.jpg

The pattern for a singleton is very straight forward and rather ingenious if you ask me.

/*
 * This is an example of a singleton
 */
var MyAPI = function() {
	var outside = "I'm running, jumping and playing outside";

	// This is object will be our public API
	var myapi = {
		someProperty: "Hello World!",
		someMethod: function() {
			alert(this.someProperty + " Go do something outside, " + outside);
		}
	}
	return myapi;
}();

I admit that’s not a very complex example but should show the overall theory quite well. We’ve got a variable (MyAPI) that’s actually a function that runs because of the “()” after the closing }. When this function runs it builds our “myapi” object and returns it which then becomes our public API with a name of “MyAPI” which is accessible from CSJS. Also notice we’ve got a variable (outside) which is above our myapi object. This variable will still be accessible from myapi via code within myapi but not from code outside of myapi, so you couldn’t build a script in an xpage to modify the “outside” variable.

Now that we’ve got our client side API and we add the Script Library this is in as a resource to an xpage, or better yet a resource available to the entire application via the theme. You can now get to all the methods and procedures in this object from CSJS anywhere. The syntax would be:
MyAPI.someMethod();

So to see our API in action let’s take a look at firebug and we should now see our MyAPI namespace represented in the DOM tab.
Firebug-MyAPI.png

And if you put some code (MyAPI.someMethod();) in the Javascript console of firebug and run it against MyAPI it should function just as we would expect it to by throwing up an alert.
HelloWorld-MyAPI.png

This makes it possible to include all your client side logic within a name space of your preference, say the application name or internal abbreviation. Also, it’s more of a class like structure with all the benefits of using classes and it makes it much easier to manage your API and easier to troubleshoot issues when they arise. Talking of issues, you will probably want to put some error handling in place to spit out meaningful error messages.

So I hope this shows how easy it is to create your own client side API and the benefits of doing so. If you want to see this live you can see the demo here.

Share This: