54_RELEASE_NOTES.txt

Scratch pad for changes destined for the 5.4 release notes page.

# Non-Breaking Changes:

A new DeprecationWarning service exists to write runtime warnings about deprecated component parameters.

There have been sweeping changes to the client-side support in JavaScript, including the long-awaited abstraction layer.
Tapestry is moving to the use of asynchronously-loaded modules, using the RequireJS library. Virtually all of Tapestry's
existing JavaScript libraries are being recoded as JavaScript modules; in 5.5, the remaining JavaScript libraries will
be removed.

The abstraction layer, the `t5/core/dom` module, is a set of wrappers that encapsulate most of the differences between
Prototype and jQuery. By coding to the abstraction layer, it will be possible to swap
out Prototype support for jQuery.  Prototype will no longer be bundled with Tapestry starting in Tapestry 5.5. Ultimately
it will be possible to efficiently support other foundation frameworks, such as MooTools or ExtJS, by providing your
own implementation of the abstraction layer.

Prior releases of Tapestry would require several separate constructs to initialize client-side behavior:

* A unique id, generated on the server, on a client-side element
* A JavaScript library that extended T5.initializers with an initialization function
* Creating a _spec_ to describe behavior, including URLs and the unique client element id
* Many similar client-side event handlers on specific elements (created by the initialization function)

Although this was well-structured, it had numerous pain points for developers, as well as some client-side performance issues.
For example, it means that components that occur many times on the page will include many similar event handler
functions.

Tapestry 5.4 represents a shift to a more modern, lighter approach. Behavior of components is encoded into
`data-` attributes on the element, and logic shifts to a module that provides top-level event handlers on the
document object. This is an overall win: it reduces the number of event handlers, solves some timing issues related
to running initialization functions, deals with DOM updates better, and is overall more performant.

Tapestry is moving away from "magic class names" to a more uniform approach based on the use of HTML 5 compliant `data-`
attributes.

## Asset Improvements

Prior versions of Tapestry created cacheable URLs for Assets that incorporated the application version number. The
Assets were served with a far-future expires header: the client browser would not even need to check to see
if the asset had changed.

Unfortunately, when any asset changed in a new deployment of the application, the version number needed to
change, resulting in all assets being downloaded (because the application version number in their URLs changed).

In this release, individual assets are given a URL containing a checksum based on the asset's content. When the underlying
file is changed, the asset will be served with the new URL, but unchanged assets will not be affected. This means
that when redeploying your application, you'll see far less asset traffic, as most client web browsers will already
have most assets (whose contents have not changed) in their local cache.

In prior releases of Tapestry, the response to an asset URL could be compressed (with GZip) if the client supported
it, and the file was itself compressable. Compressable assets include CSS files and JavaScript, but not image
format files (those have built in compression). The fact that two different versions of the file were available
with the same URL could confuse some Content Delivery Networks. In Tapestry 5.4, compressed and uncompressed
asset URLs are distinct.

Tapestry 5.4 now re-writes CSS files, expanding any `url()` references in them into fully qualify URLs; this
is to allow for the checksum embedded into each URL, which breaks relative references.

Tapestry 5.4 introduces a new module, tapestry-wro4j, that provides support for compiling CoffeeScript into JavaScript,
Less into CSS, and for minimizing CSS and JavaScript. All processing takes place at runtime.

## ControlGroup Mixin

This new mixin for Field components adds the outer <div> and <label> elements for a Field to layout correctly
inside a Twitter Bootstrap form.

## tapestry-test deprecated

The tapestry-test module contains base classes used when writing TestNG, Selenium, and EasyMock tests.
It has been deprecated; users are directed to the Spock Framework (as a replacement for TestNG and EasyMock),
and to Geb (which is a vastly improved wrapper around Selenium, and works nicely with Spock).

The useful RandomDataSource class has been extracted into a new module, tapestry-test-data.

The code for launching an instance of Jetty or Tomcat has been extracted to a new module, tapestry-runner.

# Breaking Changes:

## tapestry-yuicompressor replaced with tapestry-wro4j

The tapestry-yuicompressor module has been removed and superseded by tapestry-wro4j. WRO4J (Web Resource
Optimizer for Java) is a Apache-licensed project that provides support for CoffeeScript support, Less and
SASS processing, and various forms of JavaScript and CSS minimization. The new tapestry-wro4j module enables
a base set of these.

With tapestry-wro4j in place, you can write your client-side code in CoffeeScript (with the ".coffee" file
extension) and Tapestry will take care of converting it, at runtime, to JavaScript.

The WRO4J support is separate and optional, as it is not an Apache Software Foundation project, and it has a
large number of dependencies needed to run the various processors (some of which are written in Ruby and require JRuby,
for example).

By default, tapestry-wro4j enables:
- compilation of CoffeeScript to JavaScript (using Java's Rhino JavaScript engine)
- compilation of Less to CSS
- minification of CSS using Andy Robert's csscompressor
- minification of JavaScript using the Google Closure compiler (in simple optimizations mode)

## RenderSupport Removed

The RenderSupport interface, which was deprecated in Tapestry 5.2, has been removed entirely.

## FormFragment Component

The FormFragment component's visibleBound parameter is no longer supported; it was used to make a decision about how
far up the DOM above the FormFragment's client-side element should be searched when determining visibility. This may
resurface in the future as a CSS expression, but is currently not supported.

## Symbol tapestry.asset-path-prefix

The definition of the symbol 'tapestry.asset-path-prefix' has changed; it no longer includes the leading and trailing
slashes. The default in 5.3 was "/assets/", in 5.4 it is simply "asset".

A second symbol, "tapestry.compressed-asset-path-prefix" has been added; this is used when assets are to be compressed.
It defaults to "${tapestry.asset-path-prefix}.gz". You should generally see "/asset" URLs for image files, and
"/asset.gz" URLs for CSS and JavaScript.

## Libraries de-emphasized

JavaScript Libraries (including stacks) are being replaced with modules. Note that libraries are now loaded with
RequireJS, which may mean that global values exported by the libraries are not visible; you should explicitly attach
properties to the global JavaScript window object, rather than assume that the context (the value of `this`) is the window.

## T5 and Tapestry namespaces all but eliminated

Only a limited number of properties exported in the `T5` and `Tapestry` namespaces (on the client) still exist; enough
to continue to support the `T5.initializers` approach to page initialization that was used in Tapestry 5.3 and earlier.
These will be eliminated in Tapestry 5.5.

## New method on ResourceTransformer

The interface org.apache.tapestry5.services.assets.ResourceTransformer has had a new method added:
getTransformedContentType(). This makes it possible to determine which file extensions map to which content types
(for example, a ResourceTransformer for CoffeeScript files, with extension "coffee", would map to "text/javascript").

## Zone component change

Older versions of Tapestry included client-side support for an element with the CSS class "t-zone-update" as the actual
element to be updated when new content is provided for the zone in a partial page render response. This feature has been
removed with no replacement.

## Scriptaculous Deprecated

Tapestry code no longer makes use of Scriptaculous. Instead, Tapestry will fire events on elements, and user code may
decide to animate them using whatever library is desired. The event names are defined in the `t5/core/events` module.

## Floating Console

On the client side, the "floating console" is now only used in cases where a native console is not available. The console
should not be used to present information to ordinary users (Bootstrap provides Alerts for that purpose), but is only
intended for use in development.

## Form.clientValidation parameter

Prior releases of Tapestry mapped "true" and "false" values for Form.clientValidation to BLUR and NONE. This mapping
was introduced in Tapestry 5.2, and has now been removed.

Support for validating fields on blur (i.e., when tabbing out of a field) has been removed. Validation now occurs when
the form is submitted, or not at all. The ClientValidation.BLUR enum value has been deprecated and is now treated
identically to SUBMIT.

## Wait-for-page logic removed

Tapestry 5.3 contained client-side code that attempted to prevent Ajax requests until after the page had loaded;
this was based on the function `Tapestry.waitForPage()`.  Server components no longer make use of this function, and the function
itself now does nothing. A replacement approach to preventing the user from interacting with links and forms before
the page initialization has completed may be implemented in the future.

However, once initial page initialization has occurred, the attribute `data-page-initialized` on the root HTML element
is set to "true". In many cases, automated tests should be updated to wait for this attribute to be set after loading
a new page.

## Twitter Bootstrap

Tapestry now includes a default copy of Twitter Bootstrap in addition to its own default set of CSS rules (the
file "default.css" automatically included in rendered pages). The Tapestry CSS has been largely eliminated; instead
components now refer to standard Bootstrap CSS classes.

The Bootstrap CSS is now only present if the `core` JavaScript stack is imported. You may need to change your application's
layout component to do so explicitly, by adding `@Import(stack="core")` to the class.

ValidationDecorator and ValidationDecoratorFactory are deprecated in 5.4 and will be removed in 5.5. The default
implementation of ValidationDecorator now does nothing. All the logic related to presentation of errors has moved
to the client, and expects and leverages the Twitter Bootstrap CSS.

Fields that require validation messages to be displayed fire events, and the default handlers show and update
help blocks that appear (by default) beneath the fields. To get the full effect, you should enclose your fields inside
.control-group elements, as described in the Bootstrap documentation:
http://twitter.github.com/bootstrap/base-css.html#forms

You may also use the new ControlGroup mixin for most fields.

## BeanEditor / BeanEditForm

The property edit blocks contributed to the BeanBlockSource service should expect to be nested inside a
div.control-group, which is provided around the editor for each property.

## ClientBehaviorSupport

This service, primarily used by built-in components in Tapestry 5.3, is no longer useful in 5.4. The service
still exists, but the methods do nothing, and the service and interface will be removed in 5.5.

## JavaScriptSupport

In prior releases, adding _any_ JavaScript to the application would implicitly import the `core` JavaScript stack.
This no longer occurs; in most cases, the core stack is provided automatically by other components.

You may want to consider adding `@Import(stack="core")` to your applications' main layout component, especially
if you want to leverage the built-in Twitter Bootstrap CSS, which is provided as part of the core stack.

## Palette Component

The selected property is now type `Collection`, not specifically type `List`. It is no longer allowed to be null. You may
need to provide a "prepare" event handler to initialize the property before it is read by the Palette component.

## Autocomplete Mixin

The Autocomplete mixin has been rewritten to use Bootstrap; this implies it will also force jQuery onto the page,
to support the Bootstrap JavaScript library. In addition, Bootstrap's typeahead component does not support multiple
tokens, so this behavior has been removed.

## RenderNotification Mixin

The timing of this mixin has changed, it now has the @MixinAfter annotation, so it triggers its events *after*
the component to which it is attached has executed its @BeginRender phase, and *before* the component executes
its @AfterRender phase.

## LocalizationSetter service

The method setNonPeristentLocaleFromLocaleName() was renamed to setNonPersistentLocaleFromLocaleName() to correct
the typo (the missing 's').

## OperationTracker Extended

The OperationTracker interface has had a new method added, for performing an IO Operation (that may throw IOException).

## Session Locking

Tapestry now uses a lock on access to the HttpSession; a shared read lock is acquired when reading session attribute
names; an exclusive write lock is acquired when reading or writing session attributes. Locks, once acquired, are kept
until the end of the request. A new configuration symbol can be used to turn this feature off, reverting to Tapestry
5.3 behavior.

## AssetPathConstructor

The interface for AssetPathConstructor was changed incompatibly, to allow for individual asset checksums.

## StreamableResource Extended

StreamableResource has been modified, adding a new `getChecksum()` method; this interface is rarely, if ever,
used or implemented by application code.

## Module classes moved to new modules

Traditionally, Tapestry IoC Module classes have lived in the same package as the service interfaces they define, and
at the same time reference implementation classes in a separate (usually internal) package. This is not a desirable
approach, as proper practices is to avoid cases where separate packages import classes from each other.

To resolve this, new `modules` packages have been created, and module classes have been moved there. Since module
classes are typically not used directly by end-user code, this is not expected to be a disruptive change.

## tapestry-test and TapestryTestConstants

Several constants defined in org.apache.tapestry5.test.TapestryTestConstants have moved to a new class,
org.apache.tapestry5.test.TapestryRunnerConstants in the new tapestry-runner module.

## AbstractValidator base class

The constructor for AbstractValidator has changed to include an instance of JavaScriptSupport.