Prototype JavaScript framework - Function

methodize

2008-01-08T23:15:00Z

someFunction.methodize() -> Function

Takes a function and wraps it in another function that, at call time, pushes this to the original function as the first argument.

The methodize method transforms the original function that has an explicit first argument to a function that passes this (the current context) as an implicit first argument at call time. It is useful when we want to transform a function that takes an object to a method of that object or its prototype, shortening its signature by one argument.

Examples

// start off with a simple function that does an operation
// on the target object:
var fn = function(target, foo) {
  target.value = foo;
};

var object = {};

// use the original function
fn(object, 'bar');
object.value //-> 'bar'

// if we methodize it and copy over to the object, it becomes
// a method of the object and takes 1 argument less:
object.fnMethodized = fn.methodize();
object.fnMethodized('boom!');
object.value //-> 'boom!'

Of course, usage shown in the example is rarely useful. It's more useful to copy methodized functions to object prototypes so that new methods are immediately shared among instances. In Prototype library, methodize has important usage in DOM and Event modules; Element.Methods and Event.Methods are methodized and placed in their native prototypes so that they are available on DOM nodes and event objects, respectively.

argumentNames

2008-01-08T23:14:00Z

someFunction.argumentNames() -> Array

Reads the argument names as defined in the function definition and returns the values as an array of strings, or an empty array if the function is defined without parameters.

Examples

var fn = function(foo, bar) {
  return foo + bar;
};
fn.argumentNames(); //-> ['foo', 'bar']

Prototype.emptyFunction.argumentNames(); //-> []

wrap

2007-11-02T19:03:00Z

wrap(wrapperFunction[, arg...]) -> Function

Returns a function “wrapped” around the original function.

Function#wrap distills the essence of aspect-oriented programming into a single method, letting you easily build on existing functions by specifying before and after behavior, transforming the return value, or even preventing the original function from being called.

Examples


String.prototype.capitalize = String.prototype.capitalize.wrap( 
  function(proceed, eachWord) { 
    if (eachWord && this.include(" ")) {
      // capitalize each word in the string
      return this.split(" ").invoke("capitalize").join(" ");
    } else {
      // proceed using the original function
      return proceed(); 
    }
  }); 

"hello world".capitalize()     // "Hello world" 
"hello world".capitalize(true) // "Hello World"

defer

2007-11-02T18:56:00Z

defer(arg...) -> Number

Schedules the function to run as soon as the interpreter is idle.

A “deferred” function will not run immediately; rather, it will run as soon as the interpreter’s call stack is empty.

Behaves much like window.setTimeout with a delay set to 0. Returns an ID that can be used to clear the timeout with window.clearTimeout before it runs.

Examples


function hideNewElement() {
  $('inserted').hide();
};

function insertThenHide(markup) {
  $('container').insert(markup);

  // IE needs a moment to add the new markup
  // to the DOM tree
  hideNewElement.defer();
}

insertThenHide("<div id='inserted'>Lorem ipsum</div>");

delay

2007-11-02T18:45:00Z

delay(seconds[, arg...]) -> Number

Schedules the function to run after the specified amount of time, passing any arguments given.

Behaves much like window.setTimeout. Returns an ID that can be used to clear the timeout with window.clearTimeout before it runs.

To schedule a function to run as soon as the interpreter is idle, use Function#defer.

Examples


// before:
window.setTimeout(function() {
 Element.addClassName('foo', 'bar'); }, 1000);

// after:
Element.addClassName.delay(1, 'foo', 'bar');


// clearing a timeout
var id = Element.hide.delay(5, 'foo');
window.clearTimeout(id);

curry

2007-11-02T18:36:00Z


  curry(arg...) -> Function

Partially applies the function, returning a function with one or more arguments already “filled in.”

Function#curry works just like Function#bind without the initial scope argument.

Examples


String.prototype.splitOnSpaces = String.prototype.split.curry(" ");
"foo bar baz thud".splitOnSpaces(); //-> ["foo", "bar", "baz", "thud"]

Function

2006-12-05T21:46:00Z

Prototype takes issue with only one aspect of functions: binding.

What is binding?

“Binding” basically determines the meaning, when a function runs, of the this keyword. While there usually is a proper default binding (this refers to whichever object the method is called on), this can be “lost” sometimes, for instance when passing a function reference as an argument.

If you don’t know much about the this keyword in JavaScript, hop to the docs for the bind() method. The examples there will clear it up.

Prototype to the rescue!

Prototype solves this. You’ll find two new methods on any function: one that guarantees binding (it can even guarantee early parameters!), and one that is specific to functions intended as event handlers.

bindAsEventListener

2006-11-18T18:03:00Z

bindAsEventListener(thisObj[, arg...]) -> Function

An event-specific variant of bind which makes sure the function will recieve the current event object as the first argument when executing.

If you’re unclear on what “binding” is, check out Function’s API page. If you don’t quite understand what bind() does, check out its specific article.

When you’re creating methods that you want to use as event handlers, you need to get the current event somehow, as well as control the context in which the method will run. bindAsEventListener takes care of both, as it binds the handler to the specified context (thisObj) and makes sure the event object gets passed to the handler when the event actually occurs.

This method also works around the problem in MSIE when using DOM level 0 style of event handling and the event object isn’t passed as the first argument, but has to be read from window.event instead. You can forget about that with this method as you don’t have to do it manually.

You typically use this method in conjunction with Event.observe, and anywhere you need to pass a method as an event listener.

Example

Here is a consolidated example:


var obj = { name: 'A nice demo' };

function handler(e) {
  var tag = Event.element(e).tagName.toLowerCase();
  var data = $A(arguments);
  data.shift();
  alert(this.name + '\nClick on a ' + tag + '\nOther args: ' + data.join(', '));
}

Event.observe(document.body, 'click', handler.bindAsEventListener(obj, 1, 2, 3));
// Now any click on the page displays obj.name, the lower-cased tag name
// of the clicked element, and "1, 2, 3".

bind

2006-11-18T18:02:00Z

bind(thisObj[, arg...]) -> Function

Wraps the function in another, locking its execution scope to an object specified by thisObj.

As discussed on the general Function page, binding can be a pretty tricky thing for a newcomer, but it generally is a very simple concept. It requires the basic understanding of the JavaScript language.

In JavaScript, functions are executed in a specific context (often referred to as “scope”). Inside the function the this keyword becomes a reference to that scope. Since every function is in fact a property of some object—global functions are properties of the window object—the execution scope is the object from which the function was called, or (more precisely) the object that holds a reference to the function:


window.name = "the window object"

function scopeTest() {
  return this.name
}

// calling the function in global scope:
scopeTest()
// -> "the window object"

var foo = {
  name: "the foo object!",
  otherScopeTest: function() { return this.name }
}

foo.otherScopeTest()
// -> "the foo object!"

Because of the dynamic nature of the language, we can’t be sure that, for instance, otherScopeTest() will always be called on our foo object. The reference to it can be copied somewhere else, like on the window object:


// ... continuing from the last example

// note that we aren't calling the function, we're simply referencing it
window.test = foo.otherScopeTest
// now we are actually calling it:
test()
// -> "the window object"

The last call demonstrates how the same function can behave differently depending on its execution scope.

When you begin passing around function references in your code, you often want them to become fixated on a specific scope. Prototype can guarantee that your function will execute with the object you want under the this keyword just by invoking bind on it. You can also save the returned function and use it multiple times if you need so.

Examples

The code below is simply proof-of-concept:


var obj = {
  name: 'A nice demo',
  fx: function() {
    alert(this.name);
  }
};

window.name = 'I am such a beautiful window!';

function runFx(f) {
  f();
}

var fx2 = obj.fx.bind(obj);

runFx(obj.fx);
runFx(fx2);

Now, what few people realize is, bind can also be used to prepend arguments to the final argument list:


var obj = {
  name: 'A nice demo',
  fx: function() {
    alert(this.name + '\n' + $A(arguments).join(', '));
  }
};

var fx2 = obj.fx.bind(obj, 1, 2, 3);
fx2(4, 5); // Alerts the proper name, then "1, 2, 3, 4, 5"

Not yet clear enough?

OK, try Justin’s sweet article explaining function binding.