Echo2 to Echo3 Migration Guide

Echo is divided into two primary modules the "Application Framework" and "Web Container". The "Application Framework" module defines the components, properties, and events that an end-developer uses to create an application. The "Web Container" serves as a back-end to render the application to the client.

General Application Framework Changes

With Echo3, the application framework receives very minor changes compared with Echo2, and thus porting code that uses the application framework is fairly trivial.

Package Name Change

The most obvious change between Echo2 and Echo3 is the application framework package name. In Echo2, the package name was nextapp.echo2.app. In Echo3, the '2' is dropped, and the package name simply becomes nextapp.echo.app. A search-and-replace should bring your code up to date.

A similar package name change has occurred in the Echo3Extras, with nextapp.echo2.extras.app becoming nextapp.echo.extras.app

XML StyleSheet Syntax

If your application used any Echo XML stylesheets, you'll need to update them to the Echo3 format. An automated conversion utility is provided in the Echo3 download to accomplish this. See the StyleSheet Conversion page for more information.

Web Container Changes

The Web Container has been entirely re-written in Echo3. This is likely to be of significant consequence only if your application makes use of custom components that render their own HTML and JavaScript. The Echo3 API is all-new here, but is substantially easier to use.

Component Rendering Changes

In Echo2, components could be rendered to HTML on either the server or client. In Echo3 this work is now done exclusively on the client. Additionally, component state and user input is now automatically serialized between client and server.

If you have written an Echo2 HTML-rendering component, you will want to read the Component Authoring section of the developer's guide.

Component Specific Changes

Some components have slightly altered behaviors in Echo3 that developers of which developers should be aware.

SelectField

SelectFields now have their first options selected by default. In Echo2, an empty option was selected by default, which disappeared once a value was selected. If you would prefer the Echo2 style behavior, it will be necessary to specifically add an empty option to the ListModel.

SplitPane

SplitPanes now have a default separator position of 50%. In Echo2 the default separator position was 100 pixels (Echo2 did not support percentage-based SplitPane positioning.

WindowPane

Changes have been made to the way WindowPane renders insets for its close icon. WindowPanes now support multiple icons in a "control area" which contains the close icon. The overall insets is controlled by a new property, controlIconInsets, which has a default value of 5. The insets of individual insets of each control icon may also be adjusted. The Echo2 property closeIconInsets remains in the new API, but now has a default value of 0. If your components or styles were specifying a value for closeIconInsets though, you will likely want to update them to instead set a value for controlsInsets.