54_RELEASE_NOTES.txt - tapestry-5 - Git at Google

 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 module. Much of Tapestry's existing
 JavaScript libraries are being recoded as JavaScript modules; in 5.5, the remaining JavaScript libraries will be removed.

 All of the clients-side objects available inside the T5 or Tapestry objects (in Tapestry 5.3) are considered deprecated
 in Tapestry 5.4.  Where possible, the implementations of such objects have been reworked to use the new support provided
 by the modules. In many cases, logic that was previously supplied using client-side objects and the T5.initializers
 object is now provided using the event handlers.

 The abstraction layer is a set of wrappers that encapsulate most of the differences between Prototype and jQuery (or
 other, more modern JavaScript foundation libraries). By coding the 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.

 Prior releases of Tapestry would require several moving parts to initialize client 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 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
 body 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.

 * data-prevent-submission: Used on a HTML form to indicate that normal submission should be suppressed; typically because
   client-side code will be submitting the form's contents via an Ajax request.

 * data-skip-validation: Used on an HTML form; the immediately subsequent form submission will skip all validation.
   This is often associated with buttons that cause a form to be canceled or otherwise submitted without client-side
   validation.

 * data-validation: Used on form control elements; a non-null value indicates that the field should have the
   `events.field.validate` event triggered on it, when the form is validating, prior to submission.

 # Breaking Changes:

 ## 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 "assets".

 ## Libraries de-emphasized for modules

 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 (this) is the window.

 ## T5 and Tapestry namespaces all but eliminated

 Only a limited number of properties exported as 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.

 ## 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").

 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 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.

 ## 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 as
 SUBMIT.

 ## Wait-for-page logic removed

 Tapestry 5.3 contained 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".

 ## 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

 ## 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.

 ## Palette Component

 The selected property is now type `Collection`, not specifically type `List`. It is no longer allowed to be null.

 ## 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 attaches has executed its @BeginRender phase, and *before* the component executes
 its @AfterRender phase.
	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 module. Much of Tapestry's existing
	JavaScript libraries are being recoded as JavaScript modules; in 5.5, the remaining JavaScript libraries will be removed.

	All of the clients-side objects available inside the T5 or Tapestry objects (in Tapestry 5.3) are considered deprecated
	in Tapestry 5.4. Where possible, the implementations of such objects have been reworked to use the new support provided
	by the modules. In many cases, logic that was previously supplied using client-side objects and the T5.initializers
	object is now provided using the event handlers.

	The abstraction layer is a set of wrappers that encapsulate most of the differences between Prototype and jQuery (or
	other, more modern JavaScript foundation libraries). By coding the 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.

	Prior releases of Tapestry would require several moving parts to initialize client 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 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
	body 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.

	* data-prevent-submission: Used on a HTML form to indicate that normal submission should be suppressed; typically because
	client-side code will be submitting the form's contents via an Ajax request.

	* data-skip-validation: Used on an HTML form; the immediately subsequent form submission will skip all validation.
	This is often associated with buttons that cause a form to be canceled or otherwise submitted without client-side
	validation.

	* data-validation: Used on form control elements; a non-null value indicates that the field should have the
	`events.field.validate` event triggered on it, when the form is validating, prior to submission.

	# Breaking Changes:

	## 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 "assets".

	## Libraries de-emphasized for modules

	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 (this) is the window.

	## T5 and Tapestry namespaces all but eliminated

	Only a limited number of properties exported as 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.

	## 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").

	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 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.

	## 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 as
	SUBMIT.

	## Wait-for-page logic removed

	Tapestry 5.3 contained 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".

	## 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

	## 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.

	## Palette Component

	The selected property is now type `Collection`, not specifically type `List`. It is no longer allowed to be null.

	## 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 attaches has executed its @BeginRender phase, and before the component executes
	its @AfterRender phase.