Page History

Perhaps nothing in Tapestry has changed over the years so much as the way client-side JavaScript is supported. From the get go, the goal was to make JavaScript a first-class citizen in the Tapestry world, and make it easy to encapsulate JavaScript within components.

The legacy JavaScript page discusses the earlier approaches; the main feature of Tapestry 5.4 is a total rewrite of all things client-side, with the following goals:

...

On the server-side, a Tapestry component (or mixin) will exposes configurable parameters. The component will write writes DOM elements or attributes, as well as some amount of JavaScript initialization. The encapsulation here allows developers with little or no knowledge of client-side JavaScript to enjoy the benefits (as consumers of components created by developers who are versed in client-side coding and Tapestry components).

...

For several years, it has been obvious that Tapestry "backed the wrong horse" with respect to Prototype and jQuery. When the first code was being laid down in 2007 or 2008, it wasn't so clear that jQuery with its odd abstractions and unfamiliar approach, would go on to conquer the world. Meanwhile, Prototype was very strongly integrated into Ruby on Rails and had first class documentation and books.

That being said, jQuery may is not be the be-all and end-all either. Tapestry 5.4 introduces an abstraction layer, that allows many components to write code that doesn't care whether the foundation framework in is Prototype or jQuery . This is especially useful during the arduous process of moving Tapestry 5.3 client-side code forward to 5.4.If you or something else. If you like jQuery then there's no problem: write your application using just jQuery and you can ignore a lot of the features in the abstraction layer. Your code will likely be just a bit more efficient.

If you are building a reusable component or library, writing to the abstraction layer may be worth the effort; it is entirely possible that someone may write a replacement for the abstraction layer that targets your favorite foundation framework, such as ExtJS, MooTools, or something not even known of today.

...

In Tapestry 5.4, the goal is to make things light. In most cases, there will not be isn't a specific initialization function; instead a JavaScript module will be  is loaded, and it will install installs one or more top-level event handlers; the elements will have has data- attributes attributes that are used by those top level handlers to recognize which elements they are responsible for.

This is more of a full lifecycle approach; adding or removing page content (such as with a Zone component) is both cheaper and less error prone using top-level event handlers than per-element event handlers; there's also less of a chance of memory leaks under Internet Explorer.

...

Under 5.4, there are a number of data- attributes that can be attached to any DOM element. A form will search searches for elements with a non-blank value for data-validation; each such element has a series of custom events triggered on it. The top-level handlers for those events will receive notifications for elements throughout the document.

...

The t5/core/events module defines constants for different custom event name, it's also a handy place to hang  hang documentation about those events.

The t5/core/dom namespace is the abstraction layer.  onDocument is a handy way to attach a top-level event handler.

Fields that are required will have the attribute data-optionality=required; the event handler is passed a memo object that includes a value property, the value from the field. This makes it easier to generate an error if the value is blank.  Because the exact error message may be customized or localized, it is provided in the element as well, as the data-required-message attribute. Setting memo.error to a validation error string will cause causes the field to be decorated with the error message and will indicate indicates that the form itself is in error and not ready for submission.

...

The abstraction layer is defined by the t5/core/dom module. This module is currently has two different implementations - one is a wrapper around Prototype, and the other is a wrapper around jQuery.

The result resulting abstraction layer is a bit of a bit schizophrenichybrid; it mostly looks like jQuery, but events look a bit more like jQueryPrototype. It also doesn't have jQuery's concept of operating on a matched set of elements.

The abstraction is both transitional and permanent. It is transitional in that it is about allowing existing sites with a heavy investment in Prototype to continue to operate with Prototype in the mix. It is permanent in  in that it is desirable for third party library developers to keep an abstraction layer between Tapestry's client-side code and any underlying framework, so that particular applications can provide their own abstraction layer and operate without breaking built-in components.

Most applications should transition to jQuery and feel free to use jQuery directly.  It is still best to inject module jquery into your own modules (usually as parameter $). 

If you are writing a third-party application and want to maximize re-use, then use the abstraction layer.

It is often easier to use the abstraction layer to respond correctly to to custom Tapestry events.