function foo() { 
  return 'foo'; 
} 
foo + ''; // "function foo(){ return 'foo'; }" 
// or 
foo.toString(); 
// or 
String(foo);

When using Class.create from prototype.js, I often get annoyed by a meaningless result of constructor’s toString:

var Person = Class.create({
  initialize: function(name) {
    this.name = name;
  },
  speak: function(msg) {
    return this.name + ' says: ' + msg;
  }
})
 
Person + ''; // "function klass() { this.initialize.apply(this, arguments); }"
 
var Employee = Class.create(Person, {
  initialize: function($super, dept) {
    $super();
    this.dept = dept;
  }
})
 
Employee + ''; // "function klass() { this.initialize.apply(this, arguments); }"

As you can see, constructor’s default toString tells little about what’s going on under the hood. In fact, Class.create returns a generic constructor-function which only calls initialize method of a prototype. In other words it acts as a proxy. One of the ways to see actual constructor’s code is to inspect “initialize” method directly:

// nothing new here
Person + ''; // "function klass() { this.initialize.apply(this, arguments); }"
 
// and the actual code
Person.prototype.initialize + ''; // "function (name) { this.name = name; }"

This is quite verbose, don’t you think? Let’s monkey patch Class.create a little:

Class.create = (function(original) {
  var fn = function() {
    var result = original.apply(null, arguments);
    result.toString = function() { return result.prototype.initialize.toString() };
    return result;
  };
  fn.toString = function(){ return original.toString() };
  return fn;
})(Class.create);

We simply redefine original Class.create with an “enhanced” version. New version “binds” toString of prototype.initialize as toString of constructor-function. As a bonus, it also takes care of a “wrapped” Class.create.toString itself - trying to be as unobtrusive as possible:

// monkey-patch Class.create first...
 
// Person.toString now yields much more informative result
Person + ''; // "function (name) { this.name = name; }"
 
// Class.create code seems to be unchanged
Class.create + ''; // outputs actual Class.create code

Some of the new features include:

• User Dashboard, where one can see all their scripts, and edit them.
• Image upload for scripts. Finally, you can replace that default “empty page” image with your own.
• Improved RSS feed with more useful information, and better formatting.
• Improved communication and response to various actions. This includes:
  • Automated, token-based “claim script” feature. No more claiming script and not knowing what to do next.
  • More robust and informative feedback on script approval/rejection.
• Small usability improvements.
• Many bug fixes, polishing.

We all know that using namespaces is generally a wise thing to do. You don’t have to create a multi level object structure, but nesting your code under a pseudo-namespace is what makes maintenance, upgrades and migrations somewhat easier and error-prone.

Few popular javascript libraries implement some sort of a utility function that automatically creates nested objects. What it means is that instead of writing it manually, you could let the helper handle it for you:

 
// creating nested structure manually is painful
var com = {
  thinkweb2: {
    projects: {
      _prototype: 'a deeply nested property...'
    }
  }
}
 
com.thinkweb2.projects._prototype // => 'a deeply nested property...'

Well, it appears that inject can handle such task in only 3 lines of code:

 
'com.thinkweb2.projects.prototype'.split('.').inject(window, function(parent, child) {
  var o = parent[child] = { }; return o;
})
 
Object.inspect(com.thinkweb2.projects.prototype) // => "[object Object]"

Not bad - a completely generic namespacing snippet.

What’s happening here is not a black magic. Inject accepts initial object as a first argument (in this case - window object) and iterator function as the second argument. It then calls iterator function on each item from the collection (in our case it’s simply a string split into an array). Iterator function receives accumulated result as a first argument and current value as a second. Iterator performs an action (creates a nested object) and returns accumulated result (the newly created parent object) to be used in following iterations.

Alternatively, we could wrap this all nicely and define as a String.prototype method:

 
String.prototype.namespace = function(separator){
  this.split(separator || '.').inject(window, function(parent, child) {
    var o = parent[child] = { }; return o;
  })
}
 
foo.bar.baz.quux = 'Nothing special...'; // => ERROR: foo is not defined
 
// Default separator is '.'
'foo.bar.baz.quux'.namespace();
 
foo.bar.baz.quux = 'Nothing special...'; // => "Nothing special..."
 
// Or using a custom one
'MY_AWESOME_APPLICATION::util::DOM::dimensions'.namespace('::');
 
'dimensions' in MY_AWESOME_APPLICATION.util.DOM; // => true

Note how we use “separator” argument (or defaulting to ‘.’) making the function somewhat more flexible.

P.S.
Heavy namespacing could lead to unnecessary complexity.
Lack of it - to buggy behavior.
In the end, the only thing that matters is what works best for you.

Enjoy!

A long awaited Prototype cheat sheet - a full reference to a bleeding edge 1.6.0.2 is finally here. I had no experience creating something like this before, so any bugs or suggestions are very much appreciated. Couple of notes about notations:

• Modules are sorted in a somewhat logical order - those commonly used are mostly in the left/center area, while deprecated/utility methods are all the way to the right
• Method can be recognized by parentheses following it (anything that doesn’t have ones is a property)
• Deprecated items are marked red and have NO parentheses/arguments specified
• Prototype extends quite few native objects’ prototypes with a set of convenient methods. In such cases there’s an explicit note about it next to a module name - i.g. stripScripts() method from “String (String.prototype)” can be called as 'foo'.stripScripts()
• When a module is also a class, there’s a “(constructor)” note next to it - i.g. “Hash (constructor)” means that it should be called as new Hash()
• There are few bonus items (such as those from Prototype.Browser) which are not yet included in documentation

Download (18378 downloads) and Enjoy!

Update:
I have managed to choose the most retarded format for the cheat sheet - almost squared - which was impossible to print or navigate. Sincere apologies. There is an updated version at the same address which also fixes few other annoyances:

• Ajax.Responders is now a separate section
• Added missing Event.fire
• Added Prototype.BrowserFeatures.XPath
• Added simple “Dimensions/Offsets” diagram
• Minor rearrangements

Update 2:
Uploaded a Higher Contrast version (4349 downloads)
Seems to look much better when printed.

In place editing is a great way to enhance user interface when dynamically changing data on a page. Scriptaculous’ In Place Editor is a nice extension with extensive set of features and options. I recently needed such functionality in one of the projects, but IPE wasn’t exactly the best tool for the job. The idea was to let users select one of the predefined options as well as add their own. GMail chat widget and the way it allows to change availability status is a great example of such user interface addition. Another concern was to make control fit in a limited space - google simply gets rid of “Save”/”Cancel” buttons and saves value of the input field when clicking outside of control.

I tried duplicating this behavior into a simple prototype based script which can be simply plugged into any project.
This work is experimental (there are couple of known issues) and I would appreciate any feedback.

Head over to a demo page and let me know what you think.

It’s been over 2 months since the last release of Proto.Menu - highly lightweight and easy-to-use prototype based extension aimed to make context menu creation as simple as possible. Version 0.5 happened to be quite useful (considering all the positive feedback). There were many requests for all kinds of features, but the goal was to keep things small and concise. After analyzing the source, I found few obvious drawbacks which were supposed to be taken care of long time ago. Trying not to bloat the code base, the script was rewritten with speed, size and accessibility in mind. The result is a new shiny version - still small and fast but is much more robust and accessible. Without further ado, here is what the new version is all about:

Prototype 1.6

Prototype 1.6 is finally out. Upgrading Proto.Menu to the latest revision was definitely a reasonable thing to do. Besides tons of great enhancements and speed improvements, RC1 fixed a “conextmenu” bug (which was taken into account in a previous version) - that fix itself made the script even more compact.

Iframe shim

We all know the notoriously famous IE6 bug - select elements don’t play nice, popping through any elements positioned on top (even when z-index is set to be higher). Unfortunately, IE6 is still the most used browser out there. I have no idea how this fix didn’t make its way into previous versions, but I believe that any self respectable extension should be taking care of this annoyance.

this.shim = new Element('iframe', {
   style: 'position:absolute;filter:progid:DXImageTransform.Microsoft.Alpha(opacity=0);display:none',
   src: 'javascript:false;',
   frameborder: 0
});
...
if (Prototype.Browser.IE) {
   this.container.insert({
      after: this.shim.setStyle(Object.extend(Object.extend(elOffsets, elDimension), {
         zIndex: this.options.zIndex - 1
      }))
   })
}

zIndex option

When fixing the z-index bug, I realized that it might be convenient to explicitly specify z-index of a menu container. As web applications become more complicated, the number of various elements on a page increases. Modal windows, tooltips and other floating elements should interact nicely with each other. Proto.menu now has a zIndex option (which is internally used to set iframe z-index properly)

new Proto.Menu({
   ...
   zIndex: 500,
   ...
})

“beforeShow”, “beforeHide” and “beforeSelect” callbacks

Callbacks is something every extensions developer should consider adding to their scripts. They allow users to intercept script execution at certain moments - add, change or stop certain behaviour. Proto.Menu now supports 3 callbacks: beforeShow is called every time the right click occurs but before the menu was positioned and rendered. If you wish to intercept the left click on a document which “cancels” the menu, you can now use beforeHide callback. Note that it’s not executed on menu item selection, we have another callback for that - beforeSelect is executed after the menu item was clicked but before the menu container was hidden and item callback invoked. Note that all callbacks get an event object as a first argument.

document.observe('click', function(e){ 
   if (this.container.visible() && !e.isRightClick()) {
      this.options.beforeHide(e);
      this.container.hide();
   }
}.bind(this));

Better callbacks

Menu item callbacks sucked a lot in previous version. There was no way to get neither reference to a clicked element, nor anything else. This was probably one of the most requested features. To make everyone happy, callbacks now get event object as a first argument. You can now easily access any event’s properties/methods such as target (clicked element), mouse position, and others.

var menuItems = [{
   name: 'Select all',
   callback: function(e){
      if (e.target.match('input[type=checkbox]')) {
         e.target.up('form').select('input[type=checkbox]').each(function(el){
            el.checked = true;
         })
      }
   }
}, {
   ...
}]
...

“className” option

Another highly requested feature (and one of the big drawbacks of previous version) was a lack of descriptive images in menu items. Images definitely take user interface on a next level. Not only visually pleasing, they let us make decision faster and be more productive. Any menu item, besides name callback and other options, now supports a className which is then assigned to an anchor element. Image based menus have never been easier!

Semantic markup

The last but not least of the new features is a proper markup of a menu element. Instead of just set of links (I can’t believe I made it this way), the structure now actually represents its true essence - unordered list of anchor elements. Making the web a somewhat meaningful environment is definitely the right way to go - interface elements should represent their purpose and try to be more user-friendly. As usual, I am always looking forward to any bug reports/suggestions or just any feedback about this extension. Check out a

demo page

and have fun!

P.S.
Just to make things a little tidier, the extension now has an extensive set of unit tests (svn). Unit tests are a wonderful way to maintain proper cross-browser functionality and behavior. Please let me know if you find any of them failing so that the bugs can be take care of quickly.

Version 0.6 is most likely the last one to be released under this name. Proto.Menu has been ported to a Prototype-UI framework and will continue to be developed as one of its components. UI.ContextMenu supports shadow, submenus, verious themes (including Mac OSX and Leopard ones) and is deeply integrated into the framework’s core. For a sneak preview of what to expect check out latest examples

In case you haven’t heard about Prototype UI, now is a good time to check it out. Originally started by Sebastian Gruhier (creator of very popular Prototype Window Class) and Ruby/JS guru Samuel Lebeau, Prototype UI aims to provide a set of high quality, skinnable UI components which can ease development of complex User Interfaces in web browsers.

I have recently joined the team and am currently working on UI.ContextMenu and UI.IframeShim modules. Besides these, the library is featuring full-blown Window and WindowManager classes (completely reworked PWC), Carousel, Dock, Shadow and others.

UI.ContextMenu is nothing more than a port of Proto.Menu with few changes to take advantage of library’s core methods. Increased complexity and deep integration with other components is the reason why we do Unit Testing. Unit testing is what makes development a summer breeze - knowing that next commit into a trunk plays nice with the rest of the code sure feels good.

One of the lesser known features of scriptaculous unit testing framework is Event.simulateMouse method. The name is pretty self-descriptive - it simulates mouse event, allowing us to pass some optional parameters along - pointerX, pointerY, shiftKey, etc. Everything would be just fine if this nifty helper was a little more cross-browser. The latest revision of Scriptaculous’s unittest.js states that this feature is experimental and is Firefox-only. Bah! Shouldn’t we account for at least the most popular browser out there - IE6 and 7?

Ok, so it doesn’t work cross-browser, but do we really care? Why is it such a big deal anyway? Why simulate mouse event which triggers certain methods in our code, if we can “shorten the road” and call those methods directly? I asked myself same questions, and the answer seems to be - “Yes, we should be using it” and here’s why:

1

Mouse simulation (MS) based tests are much “closer” to the real life use cases. We sort of draw a straight line from action to the result without delving into actual implementation - “Clicking toggle button should collapse container. Clicking it again should expand it.”

2

The MS based tests can effectively catch UI related problems which would otherwise be really painful to find. As an example, let’s think of a window widget. This widget has minimize and maximize buttons. Clicking those buttons invokes appropriate actions - window changes its size and position. We decide to write assertions based on direct method invocation:

 
new Test.Unit.Runner({
   testMaximize: function() {
 
      // create window object
      var myWindow = new UI.Window().show();
 
      // call our method
      myWindow.maximize();
 
      // wait till effect is completed
      wait(1000, function() {
 
         // assert that window has proper dimensions 
         asserEqual(800, myWindow.element.getWidth());
         assertEqual(600, myWindow.element.getHeight());
      })
   }
})

Ok, all seems fine. We run the code, window resizes, tests pass, we are happy and feeling safe. Let’s see what happens next. Few days go by and one of the users reports a problem - “clicking on maximize button does NOT maximize the window”. Feeling pretty clueless, we fire up the test suit and realize that it still passes all the assertions. Moreover, the window appears to be resizing as assertion is executed! It takes us 2 hours of tedious debugging, just to find out that the problem is not in maximize method at all. The problem is that invisible iframe, which should be positioned under the menu (to prevent IE6 <select> overlapping) somehow has z-index higher than window element and is effectively blocking any clicks on a button. No need to mention that MS based tests would make it much easier to catch the nasty bug.

I have to say that this is not a real life example - it has never happened to me when testing any of the window functionality. My point was to show one of the many UI related problems - problems which would be not so easy to find and debug. As complexity of web applications increases, the dynamic elements on a page and their behavior can quickly get out of order. Having more precise tools for the job could no doubt save a lot of time.

Turning Event.simulateMouse into a somewhat robust solution was quite trivial. The result - cross-browser mouse event simulation that works in FF2+, IE6+, Safari2+ and Opera9+. Instead of calling maximize as in previous example we could now simply do:

 
new Test.Unit.Runner({
   testMaximize: function() {
     ...
 
     var button = myWindow.getButtonElement('maximize');
 
     // simulate mouse click on a button
     Event.simulateMouse(button, 'click');
 
     // or using element's method
     button._click();
     ...
   }
})

Pretty simple, don’t you think?

Last thing to mention is that all of this is very much work in progress.
I will see what can be done to simulate drag&drop or mouseover/out functionality, so stay tuned.

The latest version of Event.simulateMouse can be found in a trunk (and unit tests for the curious ones). All you need to do is inculde event_simulate_mouse.js right after unittest.js.

Bug reports, or any comments are as always very welcome.

Start experimenting and have fun!

• We could pause periodical ajax requests happening on a background to prevent server overload
• We could stop some resource intensive operations happening on a client side (i.e. animation or data processing)

Ok, so detecting idle state could be useful, but how do we go about implementing it?

Before diving into all the dirty details, I’d like to mention that Andrew’s code encaplsulates “onIdle” logic into a one single function - this is where we would have to stop our requests/calculations. Such approach is absolutely fine but to decouple things a little we could abstract them into custom events. This will allow us to subscribe anyone to independently observe idle/active state of the user and act accordingly. There are quite few very, good, explanations of custom events, just in case you’re not sure what they are, as well as prototype, based, extensions. Prototype natively supports custom events since version 1.6 (which is not yet officially released). The implementation still varies (i.e. there were some drastic changes in one of the last revisions) but overall works flawlessly. In the following example I am going to use a new way of defining events - prefixing them with pseudo namespace (which I think is more descriptive).

Ok, so let’s see what these weird things are all about.

1

First, we store events (and corresponding elements) that represent any kind of interaction in a two dimensional array. I think these should pretty much cover any user action.

var events = [
	[window, 'scroll'],
	[window, 'resize'],
	[document, 'mousemove'],
	[document, 'keydown']
];

2

Next, we are interating over this array, invoking Event.observe for each element/event pair. The observe handler is simply an anonymous function. This function will fire our custom ’state:active’ event passing idleTime parameter. We basically encapsulate few native DOM events into one custom. To make things clear, the event is essentially just an object. It has methods such as .stop() and .findElement() as well as properties such as .target and .pageX. When firing custom event we can pass an optional object along with it - storing any additional data that might be useful later on. This data is then accessible through event.memo and in our case quite conveniently stores idle time.

events.each(function(e){
	Event.observe(e[0], e[1], function(){
		document.fire('state:active', {idleTime: new Time() - document._idleTime});
		clearTimeout(document._idleTime);
	})
})

3

Now that we have taken care of ’state:active’ all that’s left to do is set a timer to fire the opposite event - ’state:idle’. You can obviously change the time to anything you like. The trick here is that ’state:idle’ event will only get fired if timer doesn’t get cleared within 5 seconds (by any of the above specified user actions)

document._timer = setTimeout(function(){
	document.fire('state:idle')
}, 5000);

4

What’s really cool is that we can now observe these custom events just like we would observe the regular ones! Note the use of memo.idleTime to retrieve data passed along with the object.

document.observe('state:idle', onStateIdle).observe('state:active', onStateActive);
 
onIdle = function() {
	console.log('Oh no... where is everybody?');
}
onIdleEnd = function(e) {
	console.log('Looks like user is still alive but have been idle for ', e.memo.idleTime, ' ms');
}

We can now wrap this code into a self containing class to keep things clean and unobtrusive:

var Notifier = Class.create({
 
	_events: [[window, 'scroll'], [window, 'resize'], [document, 'mousemove'], [document, 'keydown']],
	_timer: null,
	_idleTime: null,
 
	initialize: function(time) {
		this.time = time;
 
		this.initObservers();
		this.setTimer();
	},
 
	initObservers: function() {
		this._events.each(function(e) {
			Event.observe(e[0], e[1], this.onInterrupt.bind(this))
		}.bind(this))
	},
 
	onInterrupt: function() {
		document.fire('state:active', { idleTime: new Date() - this._idleTime });
		this.setTimer();
	},
 
	setTimer: function() {
		clearTimeout(this._timer);
		this._idleTime = new Date();
		this._timer = setTimeout(function() {
			document.fire('state:idle');
		}, this.time)
	}
})

Here’s a little demo page to see this in action.

Enjoy your ride.