Prototype 1.6.0 RC1: Changes to the class and event APIs, hash rewrite, and bug fixes

Document directory

• Complete rewrite of the hash class
• Other changes and deprecations in this release
• Download, report bugs, and get help

Two months after putting 1.6.0 RC0 out in the wild, we 've fixed a handful of bugs and made some changes to the class and event APIs in response to your feedback. we 've also addressed a long-standing issue with the hash class. these changes are now available for download in our second release candidate, prototype 1.6.0 rc1. keep reading for a detailed description of the changes, some of which are incompatible with previous versions of prototype.

Changes to the class API

The changes to the class API introduced in [7833] are a result of feedback we 've gotten from 1.6.0 _ RC0, and of numerous lengthy internal debates. our goal was to improve the clarity of the API as well as pave the way for features that may make their way into future versions of prototype.

To that end, we 've eliminated the class. extend and class. mixin methods, improved the class. create syntax, and changed the way you add methods to existing classes. the API is still backwards-compatible with all pre-1.6 versions of prototype. we haven't changed the way inheritance works, and you still access superclass methods using the special $ super argument.

The biggest change is that all classes (as in the objects returned by class. create (), not instances of those objects) now have a method named "addmethods. "This method takes a single argument, an object whose properties become instance methods and properties for all instances of the class.

For example, in 1.6.0 _ RC0, where you 'd write:

var Foo = Class.create(); 
Class.extend(Foo, { /* instance methods */ });

We 've changed this so you now write:

var Foo = Class.create(); 
Foo.addMethods({ /* instance methods */ });

As in 1.6.0 _ RC0, you can still add instance methods directly from class. Create:

var Foo = Class.create({ /* instance methods */ });

Also unchanged from 1.6.0 _ RC0, You can inherit from a superclass by passing the class as the first argument to class. Create (and you can optionally specify instance methods afterwards ):

var Bar = Class.create(Foo); 
var Baz = Class.create(Foo, { /* instance methods */ });

Internally, prototype calladdmethods on the newly created class to add instance methods passed to class. Create.

Finally, we 've modified class. create to take a variable number of arguments, so you can now specify multiple collections of instance methods to add to the class, in order. this is useful for adding mixins to the class before defining your own methods:

var Bar = Class.create(Foo, Enumerable, SomeMixin, { /* instance methods */ }); 
var Baz = Class.create(Enumerable, { /* instance methods */ });

Hop to our "Learn" section for a full-length tutorial on classes and inheritance in prototype.

Changes to the event API

A small but important change was made to custom events in [7835]: All Custom Event names must now include a namespace. this is our solution to the problem of Custom Event names conflicting with non-standard native DOM events, such as "mousewheel" and "dommousescroll."

Prior to this change, prototype treated only the event names present in the event. domevents array as native DOM events. now, prototype looks for the presence of the namespace delimiter-a single colon-to determine whether you're observing a custom event or a native event.

You'll need to update any code that uses 1.6.0 _ RC0's "contentloaded" event to use its new name, "DOM: loaded. "You'll also need to give namespaces to any other custom events you may be firing or observing.We suggest using singular nouns for namespaces, and past-tense verbs for the event names (e.g. "effect: queued", "Widget: Activated", and so on ).

We also fixed a minor annoyance for users still using inline event handling in their code: they were unable to stop event propagation with event. stop (e) in IE because the event object was not extended. now, event. stop and event. element extend the given event object automatically and work as expected even with Inline event handling.Note that inline event handlers are still stronugly discouraged; You shoshould upgrade your code to use event. Observe or element # observe methods, where possible.

Complete rewrite of the hash class

Backwards compatibility change-Although it serves the same purpose as before, the new version of hash isNotCompatible with the hash class in previous versions of prototype.

Hash properties are now hidden away in a private store to prevent the risk of collision with hash's instance and mixed-in methods. this means that properties of the hash can no longer be set, accessed or deleted directly; you must use the hash # Get (key), hash # Set (Key, value) and hash # unset (key) instance methods instead. to initialize strate:

var myhash = new Hash(); 

// old API --> new API 
myhash.name = "Bob"; --> myhash.set('name', 'Bob'); 
myhash.name; --> myhash.get('name'); 
delete myhash.name; --> myhash.unset('name');

You shoshould also be aware of other changes to the hash API:

• The $ H (object) shortcut cut is now completely equivalent to new hash (object). Both always return a new object, regardless of whether the argument was an object or another hash.
• Hash # merge returns a new hash instead of modifying the hash it's called on.
• Hash # update is a destructive version of hash # merge that modifies the hash it's called on.
• Hash # clone returns a new, cloned instance of hash.
• Hash # toobject that returns a copy of the hash's inner object.
• Hash. toquerystring is now an alias of object. toquerystring. (hash. toquerystring is deprecated and will be removed in a future version of prototype .)
• Hash # Remove has been removed in favor of hash # unset.
• Hash. tojson has been removed in favor of object. tojson or the hash # tojson instance method.

Other changes and deprecations in this release

• Element # wrap now returns the newly created wrapper element instead of the element being wrapped.
• Document. getelementsbyclassname and element # getelementsbyclassname are now deprecated, since native implementations of these methods return a live nodelist, while we can only return a static array. please use $ or element # select instead. example:

  document.getElementsByClassName('foo') --> $('.foo') 
  element.getElementsByClassName('foo') --> element.select('.foo')

We 've fixed 19 bugs since 1.6.0 _ RC0; see the changelog for full details.

Download, report bugs, and get help

• Download prototype 1.6.0 _ RC1
• Submit bug reports to rails TRAC
• Get prototype help on the rails-spinoffs mailing list or # prototype IRC channel
• Interact with the core team on the prototype-core mailing list

Thanks to the specified contributors who made this release possible! Barring any heinous bugs, RC1 will be our last release candidate, and you can perform CT the final version of 1.6.0 to land in early November.