This is a quick guide to changes between releases of Tapestry. This is meant to provide information on any additions or changes that developers will face after upgrading to the latest version of Tapestry.
It is always advised to perform a full and complete build after upgrading.
You should also check the project-wide release notes for information about bugs fixes and other improvements.
As part of TAPESTRY-2311, there have been subtle changes to how event handler and render phase methods are invoked, when the methods are overrides of base class methods.
Tapestry now organizes JavaScript a bit differently; all JavaScript is at the bottom of the page, just before the </body> tag. This applies to both externally loaded scripts, and to per-page dynamically generated JavaScript.
This can cause some pages to break, those that included inline <script> blocks in their templates. You should inject the RenderSupport environmental and use it to include JavaScript properly.
A new annotation, ReorderProperties (which is placed on a type) has replaced the OrderAfter and OrderBefore annotations (which were placed on accessor methods).
The root package for all Tapestry code was changed from org.apache.tapestry to org.apache.tapestry5. This will make it reasonable to deploy Tapestry 3 or Tapestry 4 applications side-by-side with a Tapestry 5 application.
In addition, a number of classes were refactored.
PageRenderSupport has been renamed to just RenderSupport.
TapestryConstants has been removed, split into a number of new classes (by type), such as SymbolConstants.
Likewise, TapestryUtils has been split into MarkupUtils and VersionUtils.
Many of the internal services of Tapestry have been split off into their own module, InternalModule. This should not affect any user code.
The default ValidationTracker built into the Form component now has a persistence strategy of "flash". This means that if you navigate away from a page with validation errors and return, you will lose the errors To support this style of navigation, you will need to bind the Form's tracker parameter to a field that has the correct persistency (most likely, "session", the previous persistence strategy).
The methods exists() and openStream() were added to the Resource interface. The semantics of some of the other methods were slightly alterred.
The Loop component's elementName parameter was renamed to simply element (to be consistent with element parameters added to the Any and FormInjector components).
The method getElementName() on interface Field was renamed to getControlName(). This brings the property in alignment with W3C documentation and terminology, and helps differentiate from the element name (i.e., the tag name used to represent the element in a component template).
This affects a number of existing components that implement the interface.
Method allocateElementName() on interface FormSupport was likewise renamed to allocateControlName().
The show and hide parameters of the Zone component now have a default binding prefix of "literal".
In addition, the client-side Tapestry.ZoneEffect object was renamed to Tapestry.ElementEffect to reflect that it can be used with elements that are not explicitly Zones.
The method invokeIfBlank() on interface Validator was renamed to isRequired().
The findMeta() method on interface MetaDataLocator has changed significantly; it now expands symbols and performs type coercion.
The GridModel interface and the prepare() method of GridDataSource have changed to accommodate the ability to sort using multiple columns.
The getWidth() method was removed from the PropertyModel interface; the logic for deducing the desired field size from the @Width annotation has been moved into AbstractTextField.
The data type for boolean values has changed from "checkbox" (reflecting how it is rendered in an edit form) to "boolean" (reflecting what it is). In addition, all numeric types are given the data type "number". This will only affect your application if you provided an overriding contribution to the BeanBlockSource service.
The return type for getStackTrace() on ExceptionInfo changed from List<String> to List<StackTraceElement>.
The store methods on these two interfaces were renamed to be more explicit. These are not methods typically invoked from user code.
The remove() method of BeanModel was renamed to exclude(), and a new method, include() was added. The remove parameter of BeanEditForm, BeanEditor, BeanDisplay and Grid were all renamed to exclude as well (and a new include parameter was added to each).