In addition to enabling new features and capabilities, another goal of Ext JS 4 was to streamline the overall API and make it more consistent. Given these goals, it was not possible to maintain full backward compatibility with Ext JS 3. However, we definitely recognize the need to make transitioning to Ext JS 4 as smooth as possible for our community.
We are very pleased to introduce several new resources that will assist in migrating existing Ext JS 3 applications to Ext JS 4, and will hopefully minimize the difficulty and effort involved. These are bundled in our new Ext JS 3 to 4 Migration Pack, the components of which are outlined below.
- Ext JS 3 Compatibility Layer
- Ext JS 3 to 4 Migration Guide
- Ext JS Migration Demo App
- Ext JS Migration Screencasts
Table of Contents
Ext JS 3 Compatibility Layer
This consists of a set of files that, when included after Ext JS 4, provide overrides that will bootstrap existing Ext JS 3 code to run under Ext JS 4. The goal of this layer is not to enable your application to run unmodified under Ext JS 4 long-term. On the contrary, you should expect to use this layer only as a temporary means of migrating fully to Ext JS 4. The purpose of providing it is to help make the transition as swift and painless as possible. Rather than debugging obscure errors from a blank screen, you will be able to get your application back into a rendered and functional state much more quickly using the compatibility layer, making it dramatically easier to start migrating to the latest architecture.
Ext JS 3 to 4 Migration Guide
This guide, included with the compatibility layer download, lays out the high-level steps required to upgrade an Ext JS 3 application to Ext JS 4. It does not cover every possible detail about what changed from Ext JS 3—no single guide could do that for such a massive release. Because of that, there are specific guides for charting, tree, grid, and more that are great additional resources to use when upgrading specific components. See the new Ext JS 4 documentation center start page for all of the available guides.
In the vast majority of cases, the compatibility layer handles aliasing and overriding things so that Ext JS 3 applications can become functional under Ext JS 4, but there are some cases where this is simply not possible. The Migration Guide outlines the main areas that will require manual updating outside of the compatibility layer in order to get your app up and running quickly.
Ext JS Migration Demo App
We’ve also included a 3-part demo application with the download that shows off the usage and benefits of the compatibility layer. The application includes many of the most common components running properly under compatibility mode including a tree, tab panel, grid, window, form, chart, data stores, border layout, and more. The download includes:
- A basic application is written in standard Ext JS 3.3.1
- The same application running under Ext JS 4 + the compatibility layer. Minimal modifications were required in the application code to make this work, and these are noted in the source comments. You can run this version of the app in the browser and examine the kinds of warnings presented in the browser console by the compatibility layer.
- The same application fully migrated to Ext JS 4 with no compatibility layer. This version also runs under the new Ext JS 4 class system and uses the new dynamic loader to determine file dependencies automatically at runtime.
Ext JS Migration Screencasts
As a companion to the downloadable Migration Pack, we’ve also produced a 2-part tutorial screencast that will walk you through step-by-step how to migrate an application to Ext JS 4. The first tutorial introduces the compatibility layer into the demo Ext JS 3 application and demonstrates making the app run correctly under Ext JS 4 in compatibility mode. The second tutorial focuses on migrating off of the compatibility layer to run fully under Ext JS 4 and covers all of the changes required in the demo app to do so. It also demonstrates how to convert Ext JS 3 custom classes to the new Ext JS 4 class system and how to leverage the new dynamic loading scheme in your own application.
The compatibility layer and migration guide do not currently provide 100% of possible coverage of the API changes in Ext JS 4. Due to the sheer amount of effort and complexity involved in mapping all of the API’s that changed across the entire framework, the compatibility layer has by necessity been trailing the changes to the framework itself. However, because many people are ready to dive into Ext JS 4 today, we wanted to make these resources available as soon as possible.
Development on the Migration Pack will continue for now, with additional update releases, until it reaches the point where most of the API that can be mapped is mapped. We’ll never get to 100%, but we can get pretty close. There are bound to be questions and issues that arise once people start testing this out. Please use the Ext JS 3 to 4 Migration thread on the Sencha Forum as your primary source for discussing migration issues, rather than posting questions here in the blog comments.
As always, we welcome your feedback, and we hope that these resources will help everyone to quickly upgrade to the latest and greatest framework that Sencha has to offer!