the changes between with Ext1.0 and Ext 2.0

Ext 1 to 2 Migration Guide

From Learn About the Ext JavaScript Library

Jump to: navigation, search

Introduction

Welcome to Ext 2.0. If you are new to Ext (or just new to 2.0), you'll probably want to begin with the Ext 2.0 Overview as it introduces some of the new concepts in version 2.0. This document is intended for existing Ext 1.x users who need to migrate existing code from 1.x to 2.0. Unfortunately, because of the architectural changes in the new version of Ext, it was not possible to maintain full backwards compatibility. While the Overview will help get you oriented with the new code base, this guide will provide the practical steps needed to migrate your code as painlessly as possible.

Once your application is compiling again under 2.0, you'll probably want to dive into the details and start utilizing some of the new advances in the framework that could help take your applications to the next level. For additional information on 2.0, here are some helpful resources:

• Ext 2.0 Overview
• Ext 2.0 API Reference
• Ext 2.0 Examples
• Ext 2.0 Change Log
• Ext Community Forums

Summary: A summary of breaking changes between Ext 1.x and 2.0 with migration guidance provided. Author: Brian Moeskau Published: November 15, 2007 Ext Version: 2.0 Languages: English

Contents

[hide]

• 1 Introduction
• 2 Summary of Breaking Changes
• 3 Upgrading to the 2.0 Component Model
• 4 Converting BorderLayout to 2.0
  • 4.1 Layout Architecture
  • 4.2 Layout Class Mappings
  • 4.3 Converting BorderLayout
    • 4.3.1 BorderLayout vs. Viewport
    • 4.3.2 Using the Items Array
    • 4.3.3 Adding Regions and Panels
    • 4.3.4 Creating Tabs
    • 4.3.5 Rendering the Layout
• 5 Upgrading Grids for 2.0
  • 5.1 Introduction
  • 5.2 Grid to GridPanel
    • 5.2.1 Other Notes
  • 5.3 GridView API Changes
  • 5.4 Details Regarding Column Locking
• 6 Upgrading TabPanels for 2.0
  • 6.1 TabPanel Example
  • 6.2 TabPanel API Changes
  • 6.3 TabPanelItem to Panel
• 7 Upgrading Forms for 2.0
  • 7.1 Form to FormPanel API Changes
  • 7.2 Form Upgrade Example
• 8 Upgrading BasicDialog to Window
  • 8.1 BasicDialog and Window API Comparison
  • 8.2 Simple Dialog Example
  • 8.3 Tabbed Dialog From Markup Example
• 9 Upgrading LayoutDialog to Window
• 10 Upgrading QuickTips for 2.0
  • 10.1 Introduction
  • 10.2 QuickTips Singleton API Changes
• 11 Converting MasterTemplate to XTemplate
  • 11.1 Introduction
  • 11.2 Basic MasterTemplate Conversion Steps
  • 11.3 MasterTemplate to XTemplate API Changes
• 12 Converting View to DataView
  • 12.1 Introduction
  • 12.2 Basic View Conversion Steps
  • 12.3 Converting JsonView to DataView
• 13 Minor API Changes
  • 13.1 Introduction
  • 13.2 Blank Image URL
  • 13.3 API Changes

Summary of Breaking Changes

Here's a high-level summary of all the areas in 2.0 that are not backwards-compatible with 1.x and will require manual modifications to existing code to migrate it to 2.0. Please note that there have been countless minor improvements, bug fixes and other backwards-compatible changes across the framework from 1.x to 2.0. It would be impossible to list everything, so this migration guide is focused only on the areas in the framework that will not work correctly "out of the box" after an upgrade to the 2.0 library. Each item is explained in complete detail in the sections following this summary.

• Component Model Changes
  In 2.0, the Component model has been greatly improved and now forms the base of all major components. Part of this model is a unified constructor and rendering model, and many 1.x classes that have moved to this new model had their constructor signatures changed, and so must be upgraded to 2.0-style constructor/rendering. Details
• Layout Model Changes
  The 1.x BorderLayout model has been replaced by a much more flexible layout architecture in 2.0. BorderLayout is now only one of many layout styles, and the object model related to layouts has changed significantly. Details
• Grid Changes
  Both the Grid and GridView classes have changed in 2.0. Many new features have been added, but some (like column locking) have been removed. Details
• TabPanel Changes
  TabPanel now extends Panel instead of Observable, and has a few other relatively minor API changes. Details
• Form Changes
  The Form class now extends Panel, meaning that as a Container class, it has standard methods for adding items and performing layouts in 2.0. Several form-specific layout methods have been removed in favor of standard 2.0 methods. Details
• BasicDialog Removed
  BasicDialog has been replaced with a much more flexible Window class that can contain any types of items or layouts. Details
• LayoutDialog Removed
  LayoutDialog was simply a means for adding a BorderLayout to a BasicDialog in 1.x. Now that Window can have any layout (including BorderLayout) a separate class is not needed. Details
• QuickTip Changes
  The single QuickTips singleton has been replaced by four separate classes now for much added power and flexibility. Details
• Template Changes
  The regular Template class still exists for basic template processing, but MasterTemplate (for child template processing) has been replaced by the more powerful XTemplate, which adds a slew of new template features. Details
• View Changes
  The View and JsonView classes have been replaced by the more powerful DataView, which now extends BoxComponent and uses an XTemplate internally for template processing. Details
• Other API changes
  There were a small number of relatively minor API changes that only affected specific members (as opposed to entire classes). Most of these are simple text-replacement fixes to upgrade to 2.0.Details

Upgrading to the 2.0 Component Model

Many classes that did not extend Component in 1.x now do so in 2.0. Any 1.x classes that used to pass a container reference (or any other arguments) and a config into the constructor now render under the Component model, which means the constructor only takes a config. Because of this, any existing code that creates instances of classes that now extend Component will most likely need to be changed as follows:

1. Remove all non-config arguments so that the config object is the only constructor argument.
2. Quite often a container or 'el' argument was required in 1.x. You can now specify the container in 2.0 either by using the renderTo or applyTo configs, or by rendering the component directly to its container in code like so: myComponent.render('containerId');.
3. If any other arguments were present in 1.x, there will be an alternate config-based method for passing them in. See the specific class documentation for details if needed.

Converting BorderLayout to 2.0

Layout Architecture

In 1.x the layout classes were entirely focused around the BorderLayout model. BorderLayout extended the base LayoutManager, but every other class either extended or was aggregated by BorderLayout. The basic model in 1.x was that a BorderLayout could contain regions, and regions could contain content panels.

Ext 1.x (left) to 2.0 (right) Layout Hierarchy Comparison

In 2.0, there are several major differences, and understanding them will definitely aid in transitioning existing code from 1.x.

• The entire model is now based on Component/Container.
  In 1.x, the BorderLayout class itself acted as the primary container, supplying the methods for adding and removing regions and panels. However, its containment capabilities were limited to those specific classes. In 2.0, there is an entire Component/Container architecture that is now consistent across all Components. Layouts are now built by creating and nesting containers like Panels and assigning each one a layout style.
• Class responsibilities have been inverted.
  In 1.x, the LayoutManager/BorderLayout controlled layout logic and resize monitoring. BorderLayout contained regions, and regions contained content. In 2.0, this structure has been flipped around. The Container class (which displays content) is now the root of the structure, and it contains layouts. Regions are still available, but are specific to BorderLayout instead of being an integral part of the overall layout hierarchy.
• Layout logic has been delegated to the layout managers.
  The actual layout rendering logic has now been delegated to the layout-specific classes so that a given Container knows nothing about layout at all, and simply delegates all layout duties. This makes the entire hierarchy much more flexible as any Container can now employ any given layout strategy, and Containers can be arbitrarily nested, each containing its own layout. This is a powerful leap forward from the capabilities of 1.x layouts.
• There are now many additional layout managers.
  1.x was based on BorderLayout and did not provide any other options (aside from the ReaderLayout convenience class). 2.0 still includes BorderLayout, but also provides nine additional layout managers for ultimate flexibility. These are discussed in more detail in the 2.0 Overview Guide.

Layout Class Mappings

This section will outline how the layout classes generally map between 1.x and 2.0. Note that the mapping is not perfect as the entire structure was completely rewritten, but it should still give a good sense for where to look in 2.0 for comparable functionality from 1.x.

1.x 2.0 Notes Ext.LayoutManager — LayoutManager didn't actually do much by itself. As a base class, it mostly provided template and proxy functionality that was intended to be useful to its subclasses, such as begin/endUpdate to allow the developer to tell the layout when to render, proxying region event firing at the layout level, view size monitoring and an empty layout template method. The closest match in 2.0 would probably be ContainerLayout, although there isn't much practical similarity in the code. Ext.BorderLayout Ext.layout.BorderLayout,
Ext.Container In 2.0, the layout classes only provide layout logic, and that's it. Also, they are not generally created directly — instead, they are called and managed internally by the Container classes. So in terms of layout logic, Ext.BorderLayout.layout maps pretty closely to Ext.layout.BorderLayout.onLayout, but in 1.x it was called directly by the developer, while in 2.0 it is called internally by Containers automatically. The functionality of adding panels has been moved to the Container classes in 2.0, and the functionality to add regions is still in BorderLayout, but it no longer contains methods to do so. Instead, now adding regions is done entirely through configuration. Ext.ReaderLayout — This was simply a convenience class that created a specific BorderLayout configuration to render a classic, 5-pane application. It consisted of a header, a primary center region containing two nested regions (a top one for a list view and one for item preview below), and regions on either side for additional content. There is no corresponding class in 2.0, although the example below of converting a BorderLayout to 2.0 is extremely close to the default ReaderLayout and should provide a perfect template for duplicating that layout style in 2.0 if needed. Ext.BasicLayoutRegion,
Ext.LayoutRegion Ext.layout.BorderLayout.Region Although not all of the functionality is the same, the two 1.x region classes combined map exactly to the Region class in 2.0. One thing to note is that in 1.x, the regions had a convenient shortcut built-in that adding multiple panels automatically converted each panel into a tab and the region itself became a tab container. In 2.0, Containers can now commonly contain multiple non-tab panels depending on the layout style, so in order to create a set of tabs in 2.0, the TabPanel widget must be used directly (and can of course be added to a BorderLayout region). Ext.SplitLayoutRegion Ext.layout.BorderLayout.SplitRegion Although not all of the functionality is the same, this is a one-to-one class mapping. Ext.ContentPanel,
Ext.NestedContentPanel Ext.Panel The Panel class in 2.0 is basically the same as the 1.x ContentPanel although many times more powerful. The NestedContentPanel was specifically available to allow nesting of additional BorderLayouts within an existing ContentPanel. In 2.0, this behavior is already built into the Container/Panel classes to allow arbitrary nesting with any layout, so no extra class is needed. Ext.GridPanel Ext.GridPanel These classes map exactly, although in 1.x GridPanel was just a wrapper for the grid, while in 2.0 the GridPanel actually is the grid. — AbsoluteLayout,
AccordianLayout,
AnchorLayout,
CardLayout,
ColumnLayout,
ContainerLayout,
FitLayout,
FormLayout,
TableLayout These are all of the new layout managers provided in 2.0. There was nothing comparable in 1.x.

Converting BorderLayout

Now that you should have a good overall understanding of how the layout architecture has changed, an example will provide the best practical demonstration of transitioning a 1.x BorderLayout to 2.0. In the Ext "/examples/layout/" folder that comes with the download, there is a file called complex.html. This file existed in 1.x, and has been upgraded to work under 2.0. Comparing both versions of that file demonstrates how to upgrade a layout to 2.0, so let's break it down piece by piece.

A typical 1.x BorderLayout

BorderLayout vs. Viewport

In 1.x, the BorderLayout was created directly and rendered to document.body. In 2.0, while you can technically create a Panel rendered and sized to document.body, the Viewport class was built to provide that exact functionality. Anytime you are rendering a full-screen UI, the Viewport should be the foundation. The Viewport, just like all Container classes, can support any valid layout style. In this case, we will specify layout:'border'.

1.x 2.0

layout = new Ext.BorderLayout(document.body, {

var viewport = new Ext.Viewport({
    layout:'border',

Using the Items Array

In 1.x, each object had to be created explicitly and added to its parent explicitly. In 2.0, every Container class has an items config that can be populated with an array of any Components or other Containers. In this example, every single object making up the UI has been added in the Viewport's items array.

1.x 2.0

layout.add('north', new Ext.ContentPanel('north', 'North'));
layout.add('south', new Ext.ContentPanel('south', {title: 'South', closable: true}));
layout.add('west', new Ext.ContentPanel('west', {title: 'West'}));
layout.add('east', new Ext.ContentPanel(Ext.id(), {autoCreate:true, title: 'Dynamic Tab', closable: true}));
layout.add('east', new Ext.ContentPanel('autoTabs', {title: 'Auto Tabs', closable: true}));
layout.add('center', new Ext.ContentPanel('center1', {title: 'Close Me', closable: true}));
layout.add('center', new Ext.ContentPanel('center2', {title: 'Center Panel', closable: false}));

items:[
    new Ext.BoxComponent({ // raw
        region:'north',
        // other configs
    }),{
        region:'south',
        contentEl: 'south',
        // other configs
    }, {
        region:'east',
        // other configs
    } //etc.

Adding Regions and Panels

As shown above, Regions and ContentPanels were created explicitly as objects in 1.x. While you can still create your own Regions and Panels in 2.0, the preferred syntax for building a UI is the config syntax shown in the example code. Each object being passed into the items array is a config object representing a Panel (except the first one, which shows an example of adding a raw BoxComponent when a full Panel is not required).

The 1.x BorderLayout converted to 2.0

Creating Tabs

In the 1.x example, tabs are created simply by adding multiple content panels to the same region (as in the east and center regions). In the 2.0 code, note that TabPanels are explicitly created and added into the items arrays of the appropriate containers. Note that when specific components are added directly to a layout (as in the case of the center TabPanel) the region config must be specified on that component.

1.x 2.0

layout.add('center', new Ext.ContentPanel('center1', {title: 'Close Me', closable: true}));
layout.add('center', new Ext.ContentPanel('center2', {title: 'Center Panel', closable: false}));

new Ext.TabPanel({
region:'center',
deferredRender:false,
activeTab:0,
items:[{
    contentEl:'center1',
    title: 'Close Me',
    closable:true,
    autoScroll:true
},{
    contentEl:'center2',
    title: 'Center Panel',
    autoScroll:true
}]

Rendering the Layout

Once everything is constructed, it gets rendered. In 1.x, the developer was responsible for telling the layout when to defer rendering and when to update the UI using beginUpdate/endUpdate. In 2.0, this is no longer required. You simply build up the UI and updates are automatically deferred. Then once the top-most container is rendered, all contained components get rendered automatically by the framework. For regular Panels, this would require a call at the end like panel.render(document.body). However, since Viewports are automatically rendered for you, this is not needed in this example.

Upgrading Grids for 2.0

Introduction

The underlying models for getting data into a grid (proxies, readers, stores, column model, selection model) have not changed significantly in 2.0, which is good news for upgrading grids. The biggest change is that Grid extended Observable, but in 2.0, it now extends Panel (hence, the name change to GridPanel). While there are some breaking changes as detailed below, most are relatively minor. However, there are a huge number of new members in GridPanel, so be sure to have a look through the API docs to see how much more powerful the grid is in 2.0.

Grid to GridPanel

Grid (1.x) GridPanel (2.0) Notes Config Options enableColLock — Column locking has been removed in 2.0 Additional details enableCtxMenu enableHdMenu In 1.x, the header menu was only accessible via context (right-click) menu. In 2.0, the menu dropdown arrows are rendered into the header directly and automatically displayed on mouseover. Because of this the 1.x name for this event was updated to reflect the new meaning. autoSizeColumns autoFill (GridView) This option was renamed and moved to GridView (pass in the GridPanel's viewConfig option). autoSizeHeaders — This is no longer needed in 2.0 as the header widths are automatically synced. enableRowHeightSync — Related to column locking which is no longer supported in 2.0. Additional details Methods Grid(container, config) GridPanel(config) Renamed to reflect the new inheritance hierarchy. For additional information on upgrading the constructor, see the Component constructor upgrade guidelines. autoSize doLayout The method of redrawing the grid now comes from the base Container class in 2.0. getDataSource getStore Method renamed for consistency. getGridEl getEl This method now comes from the base Component class. render() render([container], [position]) This method is backwards-compatible, but is still worth mentioning for its new optional arguments. It is now inherited from the base Component class for consistent rendering support along with other components. Events dragdrop,
dragenter,
dragout,
dragover,
enddrag,
startdrag — These never actually fired in 1.x and have been removed.

Other Notes

• Make sure you specify the ‘height’ configuration option for GridPanel (2.0). If ‘height’ is set to ‘auto’ (default value) you may see a header row only without any data (both IE and FF).

GridView API Changes

1.x 2.0 Notes Methods autoSizeColumn — Autosizing (or force-fitting in 2.0) is no longer supported on a per column basis. autoSizeColumns forceFit [config] A method call is no longer needed. Just pass forceFit in the grid's viewConfig and it will automatically maintain its fit after each column resize. ensureVisible focusCell/focusRow This method was made private as focusCell or focusRow should be called instead. Focusing a cell or row will automatically scroll it into view if needed. fitColumns forceFit [config] A method call is no longer needed. Just pass forceFit in the grid's viewConfig and it will automatically maintain its fit after each column resize. getFooterPanel bbar (GridPanel) The GridView no longer maintains its own separate footer for toolbars and other components. The containing GridPanel already contains a bottom bar (bbar) for this purpose. getHeaderPanel tbar (GridPanel) The GridView no longer maintains its own separate header for toolbars and other components. The containing GridPanel already contains a top bar (tbar) for this purpose.

Details Regarding Column Locking

The column locking feature in the 1.x grid (locking one or more columns in place so that columns to the right could scroll horizontally leaving the locked columns in place) has been removed permanently. The header menu option for locking/unlocking has been removed, and no configs or methods related to locking are available in 2.0.

Column locking was a great feature for a small subset of Ext users. However, because of the underlying layout and rendering requirements necessary to enable locking, grid performance was significantly affected for everyone. Unfortunately, column locking is fundamentally incompatible with high performance in a web environment, and performance has always been a high priority for Ext. Because of that, we made the decision to remove it with the result that the grid in 2.0 renders much faster and can handle many more rows of data than it did in 1.x.

Note: There is an effort currently underway in the community to implement column locking via a user extension for 2.0, and it is already looking pretty promising as of this writing. More information is available in the forum thread.

Upgrading TabPanels for 2.0

The API for TabPanel has received a major upgrade in 2.0 as it now extends Panel instead of Observable. It also contains standard Panel objects as tabs rather than the special TabPanelItem class that existed in 1.x. While there are some breaking changes as detailed below, most are relatively minor. However, there are a huge number of new members in TabPanel, so be sure to have a look through the API docs to see how much more powerful the tabs are in 2.0.

TabPanel Example

Here is a simple example of upgrading a basic TabPanel from 1.x to 2.0. Using the API reference below you should be able to handle any additional member conversions that may be needed. Note that while the JS code is a little bit shorter in 1.x, the overall complexity is actually reduced in 2.0 thanks to the greater config flexibility. No more need for custom CSS for basic styling tasks.

1.x 2.0

// CSS:
body {margin:30px;}
#my-tabs {width:300px;}
#my-tabs .x-tabs-body {height:80px;overflow:auto;}
#my-tabs .x-tabs-item-body {display:none;padding:15px;}
 
// JS:
var tabs = new Ext.TabPanel('my-tabs');
tabs.addTab('tab1', 'Tab 1', 'A simple tab example!');
tabs.addTab('tab2', 'Tab 2', 'More content');
tabs.addTab('tab3', 'Another One', 'More content', true);
tabs.activate('tab1');
 
// HTML:
<div id="my-tabs"></div>

var tabs = new Ext.TabPanel({
    renderTo: Ext.getBody(),
    activeTab: 0,
    width: 300,
    height: 100,
    //plain: true, //remove tab strip background
    defaults: {
        autoHeight: true,
        autoScroll: true,
        bodyStyle: 'padding:15px'
    },
    items: [{
        title: 'Tab 1',
        html: 'A simple tab example!'
    },{
        title: 'Tab 2',
        html: 'More content'
    },{
        title: 'Another one',
        html: 'More content',
        closable: true
    }]
});

TabPanel API Changes

1.x 2.0 Notes Config Options currentTabWidth,
maxTabWidth,
preferredTabWidth — In 1.x, all of these tab width configs only applied if the resizeTabs config was true. In that case, Ext managed tab widths within the rules applied by these additional configs. In 2.0 the reizeTabs config is still available, but tab widths are completely managed and these additional options are no longer honored. Only minWidth still applies in this case. Methods TabPanel(container, config) TabPanel(config) TabPanel now extends Panel instead of Observable. For additional information on upgrading the constructor, see the Component constructor upgrade guidelines. addTab,
addTabItem add (Container) Both addTab (for creating new TabPanelItems) and addTabItem (for adding existing ones) are replaced by the inherited Container add method that expects a Panel. For an approximation of addTab, you can pass in a new Panel config and it will be created dynamically on render. autoSizeTabs — This is now an internal method and should not be called directly as tab widths are automatically managed by Ext. disableTab,
enableTab — In 1.x, these methods delegated to a contained TabPanelItem's disable/enable methods. In 2.0, there are no methods on the TabPanel to directly disable/enable a tab. Instead you would simply get a tab (Panel) reference and act on it directly. For example: tabPanel.getItem('my-tab').enable(); getActiveTab : TabPanelItem getActiveTab : Panel This method is the same, but it is worth noting that the object returned is now different, so the actions performed on the returned object may have to be updated as well. getCount items.length In 2.0, the Container items collection is exposed directly as a property that can be used to access the contained items in many ways. getTab : TabPanelItem getItem : Panel This getter is now an inherited Component method that returns a Panel object instead of a TabPanelItem. hideTab,
unhideTab hideTabStripItem,
unhideTabStripItem   removeTab remove (Container) This is now an inherited Container method. setTabWidth — You can set the tab width initially using the tabWidth config, but the setTabWidth method is no longer available. syncHeight([height]) — Tab dimensions are now managed by the container automatically. Properties bodyEl body Since TabPanel is now a subclass of Panel, the standard Panel body replaces bodyEl. el getEl() In 2.0, el is private and the inherited Component getEl method should be used instead.

TabPanelItem to Panel

Note that while the TabPanelItem events are all supported by Panel, event handlers will now be called with a Panel object instead of a TabPanelItem, so any handling logic might have to change accordingly.

TabPanelItem (1.x) Panel (2.0) Notes Properties TabPanelItem(tabPanel, id, text, closable) see notes TabPanelItems in 1.x only existed for the purpose of residing in a TabPanel, thus they had a very specific constructor argument list. There is no direct replacement as Panels are generic and the constructor is config-based. However, the following code would be equivalent when adding a new Panel to a TabPanel (note that a separate container config is not needed in this example since the Panel is being directly added):

tabPanel.add(new Ext.Panel({
   id: 'my-tab',
   title: 'My Tab',
   closable: true
}));

bodyEl body   closeText — The tab's close button no longer supports configurable tooltip text in 2.0. id getId() The id property is now private in 2.0 and the inherited Component getId method should be used instead. tabPanel ownerCt Every Component in 2.0 supports the ownerCt property which returns a reference to the owning Container. Methods activate show (Component) When a Panel is added into a TabPanel as a tab, its normal show method will activate it within the TabPanel. getText title [property] The standard Panel title is used as the tab text when the Panel is added to a TabPanel. getUpdateManager getUpdater This returns the update manager for the Panel's body element. isActive — Panels have no knowledge of whether or not they are active. Instead you could check tabPanel.getActiveTab().getId() == 'my-panel'. isHidden hidden [property] The standard Component hidden property can be used so no method is necessary. refresh,
setUrl load,
getUpdater().refresh In 1.x, refresh used the properties set in setUrl to reload remote content into the tab. In 2.0, Panels can be loaded directly using the load method, or you can access the update manager directly via getUpdater and either load the Panel or refresh it using previously loaded configuration data. setContent body.update Equivalent functionality. setHidden setVisible Same functionality, although note that these methods are now reversed. setHidden(true) in 1.x should now be setVisible(false) and vice versa. setText setTitle   setTooltip — No longer supported in 2.0

Upgrading Forms for 2.0

The basic functionality hasn't changed dramatically with forms in 2.0, but the method of laying out form components and containers has changed quite a bit. Forms now use the standard 2.0 Container/Panel architecture, along with the new layout managers, to provide layout capabilities consistent with the rest of 2.0, rather than form-specific layout functions as in 1.x. Here's a quick summary of the changes from 1.x to 2.0:

• In 1.x, Form inherited from BasicForm (the base class that handles form actions and field access). In 2.0, Form now inherits from FormPanel and contains a reference to a BasicForm instance internally to manage fields and actions. This way FormPanel can now participate in standard 2.0 layouts alongside other components while delegating base form functionality as needed.
• The Ext.form.Layout class has been replaced by Ext.layout.FormLayout, reflecting its proper place in the layout architecture rather than the forms architecture. FormLayout is now one of many different layout styles supported within forms.
• The Fieldset class now extends Panel instead of Ext.form.Layout so that it acts like a standard 2.0 container.
• Forms are now consistent with the new Container architecture in 2.0. As such, all of Form's container-specific methods (start, end, column, etc.) have been replaced with standard Container concepts as explained below.

Form to FormPanel API Changes

Note that because Form no longer inherits from BasicForm, but instead holds a reference to a BasicForm instance via its private form property, all BasicForm members once available directly on Form must now be accessed via Form.getForm(). Please refer to the 1.x API docs for Ext.form.Form for a complete list of all members inherited from BasicForm. The BasicForm API in 2.0 is fully backwards-compatible to 1.x.

Following are all other API changes from 1.x to 2.0 excluding missing BasicForm members:

Form (1.x) FormPanel (2.0) Notes Methods Form(config) FormPanel(config) The constructor arguments are the same, but the name must be updated. FormPanel also supports all the new standard configs available in its Component/Container inheritance chain. add(field, [field], [etc]) add(component) In 1.x, adding items to a form involved a specific procedure of opening a container element (container, fieldset, etc.), adding items into it, then closing it. You could nest containers by keeping multiple containers open at once, the most recently-opened container being the active one. The add method took an arbitrary number of arguments corresponding to fields to add into the currently-open container.

In 2.0, the entire process of building up form containers and fields has been redesigned to work consistently within the 2.0 Container architecture. Now, every form container is actually a Container subclass, and all containers support a standard interface for adding components into them. At config time, you can add components into a Container's items collection, or use the add method to add components to an existing Container. There is no need to manage container levels — that is done implicitly in 2.0 by simply nesting configs to arbitrary depths, or adding components directly into any Container at any depth within the FormPanel by direct reference. column,
container see notes Rather than creating individual containers manually as objects, in 2.0 you create a standard Panel and specify the appropriate layout as a Panel config style (layout:'column' for columns). This allows you to add columns into the Panel, then add the Panel to the form. At config time, you simply pass the Panel into the FormPanel's items collection, or you can add it to the FormPanel using the add method. See the API docs for ColumnLayout to see column-specific config options available in 2.0. fieldset see notes You still create FieldSet objects in 2.0, but as FieldSet now extends Panel, it simply acts like any other standard Panel that can be added to a form. See the notes above for add — now components are added into FieldSets exactly the same way they are added to any Container. There is no method corresponding to the fieldset method in 2.0 — you simply create a FieldSet object, add components into it, and add it to the form. start,
end — There is no need to manually manage the container stack in 2.0. All Container nesting should be done via nested FormPanel configs. Properties buttons buttons [config] FormPanel now inherits Panel's buttons config property. It's still an array of the panel's buttons, but can now also be passed in as a config option for adding buttons initially.

Form Upgrade Example

This basic example will produce the exact same form in 1.x and 2.0. There are too many variations in form layout to effectively cover them all here, so for more examples, please compare the form examples provided with Ext in the "examples/form" folder (particularly the "dynamic" example files).

1.x 2.0

var form = new Ext.form.Form({
    labelAlign: 'top'
});
 
form.column(
    {width:282},
    new Ext.form.TextField({
        fieldLabel: 'First Name',
        name: 'first',
        width:225
    }),
 
    new Ext.form.TextField({
        fieldLabel: 'Company',
        name: 'company',
        width:225
    })
);
 
form.column(
    {
        width:272, 
        style:'margin-left:10px', 
        clear:true
    },
    new Ext.form.TextField({
        fieldLabel: 'Last Name',
        name: 'last',
        width:225
    }),
 
    new Ext.form.TextField({
        fieldLabel: 'Email',
        name: 'email',
        vtype:'email',
        width:225
    })
);
 
form.container({},
    new Ext.form.HtmlEditor({
        id:'bio',
        fieldLabel:'Biography',
        width:550,
        height:200
    })
);
 
form.addButton('Save');
form.addButton('Cancel');
form.render('form-ct'); //a 600px wide container

var form = new Ext.FormPanel({
    labelAlign: 'top',
    bodyStyle:'padding:5px 5px 0',
    width: 600,
    items: [{
        layout:'column',
        items:[{
            columnWidth:.5,
            layout: 'form',
            items: [{
                xtype:'textfield',
                fieldLabel: 'First Name',
                name: 'first',
                anchor:'95%'
            }, {
                xtype:'textfield',
                fieldLabel: 'Company',
                name: 'company',
                anchor:'95%'
            }]
        },{
            columnWidth:.5,
            layout: 'form',
            items: [{
                xtype:'textfield',
                fieldLabel: 'Last Name',
                name: 'last',
                anchor:'95%'
            },{
                xtype:'textfield',
                fieldLabel: 'Email',
                name: 'email',
                vtype:'email',
                anchor:'95%'
            }]
        }]
    },{
        xtype:'htmleditor',
        id:'bio',
        fieldLabel:'Biography',
        height:200,
        anchor:'98%'
    }],
 
    buttons: [{
        text: 'Save'
    },{
        text: 'Cancel'
    }]
});
 
form.render(document.body);

Upgrading BasicDialog to Window

BasicDialog and Window API Comparison

The BasicDialog class no longer exists in 2.0, and has been replaced by the more general-purpose Window class. Window is based on Panel, so it can participate in the standard Component lifecycle, as well as acting as a standard Container and supporting 2.0 layouts. The table below summarizes the API differences between BasicDialog and Window, and offers tips on upgrading to Window when relevant. Only members that have been changed or removed are listed.

BasicDialog (1.x) Window (2.0) Notes Config Options autoCreate — No longer needed, as Window automatically renders from code unless a content element is specified (e.g., via the applyTo config). autoTabs autoTabs (TabPanel) In 2.0, tab functionality has been completely factored out of the Window class. Anytime tabs are needed, a TabPanel should be created, and it has the autoTabs config that works just like the BasicDialog version did in 1.x. Note that the required CSS classes for identifying tab content in existing markup have changed (see the examples below for details). constraintoviewport constrain,
constrainHeader There are now two separate functions, one for constraining the entire Window to the viewport, and one for constraining only the header element while allowing the Window body to overflow. fixedcenter — The behavior of auto-centering the Window anytime it is displayed or programmatically resized is not supported by default in 2.0. However, it would be easy to add if needed by simply monitoring the Window's resize and/or beforeshow events and calling Window.center(). proxyDrag — Windows only support proxy dragging in 2.0, so it's no longer an option. syncHeightBeforeShow — No longer needed in 2.0 as internal box dimensions are managed automatically by the Window. tabTag autoTabSelector (TabPanel) The functionality is the same, but is now specified in the TabPanel config. Methods BasicDialog(el, config) Window(config) Aside from the supported config object being different, the Window constructor does not take an element as the first argument. Instead, the standard 2.0 approach to specifying the element is by using the renderTo config value or passing the el into the render method. addButton addButton In 2.0, buttons must be added prior to rendering. The preferred approach in 2.0 is to specify all buttons in the buttons config for the Window rather than calling this method, but it is supported if needed. addKeyListener keys,
keyMap A valid KeyMap config object can be passed as the Window's keys config to add listeners at config time. You can also access the Window's internal KeyMap object directly via the keyMap property. collapse collapse([animate]) New optional argument to animate the effect. destroy([removeEl]) destroy() Argument removed — the el will always be removed on destroy in 2.0. expand expand(animate) New optional argument to animate the effect. getTabs items (Container),
Ext.getCmp() Since Containers in 2.0 can hold any type of Component, there is no point in having component-specific getters. Instead, you can access the Container's items MixedCollection and use any of the available methods for retrieving any component by id, index, selector, etc. Alternatively, any Component can be retrieved at any time by id from the ComponentMgr by calling Ext.getCmp('id'). hide([callback]) hide([animateTarget], [callback], [scope]) Additional arguments available (callback moved to second argument). initTabs readTabs(true) (TabPanel) The functionality is the same, but is now specified in the TabPanel readTabs method. The optional removeExisting argument will remove any existing tabs if true is passed (initTabs always removed existing tabs). moveTo setPosition The functionality is the same, but is now specified by the BoxComponent base class. resizeTo setSize The functionality is the same, but is now specified by the BoxComponent base class. restoreState — State management is now handled automatically by the Component base class. If a state provider is initialized, the Window will automatically persist and reload its state. setContentSize — No longer needed in 2.0 as internal box dimensions are managed automatically by the Window. setTitle(title) setTitle(title, [iconCls]) New optional argument to set the window icon. show([animateTarget]) show([animateTarget], [callback], [scope]) New optional arguments. Events keydown — This event is no longer fired by Window. All keydown handling should be provided via the Window's internal KeyMap object. resize(this, width, height) resize(this, adjustedWidth, adjustedHeight, rawWidth, rawHeight) New arguments for the original width and height have been added.

Simple Dialog Example

This is the simplest possible dialog, built dynamically in code. These two blocks produce dialogs that have equivalent basic functionality.

Implementation Notes:

• In 1.x you had to use autoCreate to create a dialog programmatically, and you had to update the body element to add content through code — in 2.0 the Window will create itself programmatically by default, and you can use the html config to add content.
• In 2.0, Windows have shadows by default, so the config is only needed to turn them off.
• The proxyDrag config is no longer supported — Windows can only be proxy-dragged.
• In 1.x the dialog had a minimize tool button that collapsed/expanded the dialog by default. In 2.0, there is not a default behavior for the minimize action since in a desktop-style application, the true default might be to minimize to a task bar or some other container. However, it is simple to add the 1.x default behavior by adding the minimize tool config option along with a simple event handler as shown below.
• 2.0 does have an addButtons method too, but adding them in the config is preferred. Buttons must be added prior to rendering!
• The addKeyListener method has been replaced by the keys config that allows you to pass a valid KeyMap config that defines all the keys to be handled by the Window.

1.x 2.0

var dialog = new Ext.BasicDialog(null, { 
    autoCreate: true,
    width: 300,
    height: 150,
    shadow: true,
    minWidth: 200,
    minHeight: 100,
    proxyDrag: true,
    title: '1.x Simple Dialog'
});
dialog.addKeyListener(27, dialog.hide, dialog); // hide on Esc
dialog.addButton('Close', dialog.hide, dialog);
dialog.body.update('<p>This is a simple dialog.</p>');
dialog.show();

var win = new Ext.Window({ 
    width: 300,
    height: 150,
    minWidth: 200,
    minHeight: 100,
    minimizable: true,
    title: '2.0 Simple Dialog',
    html: '<p>This is a simple dialog.</p>',
    buttons: [{
        text: 'Close',
        handler: function(){
            win.hide();
        }
    }],
    keys: [{
        key: 27,  // hide on Esc
        fn: function(){
            win.hide();
        }
    }]
});
win.on('minimize', function(){
    win.toggleCollapse();
});
win.show();

Tabbed Dialog From Markup Example

This is a slightly more complex dialog that demonstrates rendering from existing HTML markup, as well as automatically generating tabs in the dialog from the markup.

Implementation Notes:

• Note that the dialog CSS classes have changed. In 1.x, the header was "x-dlg-hd" and the body was "x-dlg-bd". These are now "x-window-header" and "x-window-body". Note that "x-window-body" is not actually used in this example since the TabPanel is added to the body programmatically by passing it in the items config. However, you could just as easily create a div for static content with the class "x-window-body" and it would render into the body as expected.
• The tab-related classes have also changed. Tabs are now generic in 2.0, so there is no need for dialog-specific class names like "x-dlg-tab". Now content anywhere in the page with the class "x-tab" can be added to any TabPanel component.
• The TabPanel is now created as a separate component since the tab functionality has been factored out of the Window class. Since Window is a Container subclass, it can contain any components (including TabPanel) by simply passing them into its items config.
• In 2.0, the applyTo config is used to apply a component to existing markup.

1.x Markup 2.0 Markup

<div id="markup-dlg" style="visibility:hidden;">
    <div class="x-dlg-hd">1.x Tabbed Dialog from Markup</div>
    <div class="x-dlg-bd">
        <!-- Auto create tab 1 -->
        <div class="x-dlg-tab" title="Tab 1">
            <!-- Nested "inner-tab" to safely add padding -->
            <div class="inner-tab">
                 Hello...
            </div>
        </div>
        <!-- Auto create tab 2 -->
        <div class="x-dlg-tab" title="Tab 2">
            <div class="inner-tab">
            ... World!
            </div>
        </div>
    </div>
</div>

<div id="markup-win" class="x-hidden">
    <div class="x-window-header">2.0 Tabbed Dialog from Markup</div>
    <div id="hello-tabs">
        <!-- Auto create tab 1 -->
        <div class="x-tab" title="Tab 1">
            Hello...
        </div>
        <!-- Auto create tab 2 -->
        <div class="x-tab" title="Tab 2">
            ... World!
        </div>
    </div>
</div>

1.x Code 2.0 Code

var dialog = new Ext.BasicDialog("markup-dlg", { 
    autoTabs: true,
    width: 300,
    height: 175,
    shadow: true,
    proxyDrag: true
});
dialog.addButton('Close', dialog.hide, dialog);
dialog.show();

var win = new Ext.Window({
    applyTo: 'markup-win',
    layout: 'fit',
    width: 300,
    height: 175,
    minimizable: true,
    closeAction: 'hide',
    plain: true,
    items: new Ext.TabPanel({
        el: 'hello-tabs',
        autoTabs: true,
        activeTab: 0,
        deferredRender: false,
        border: false
    }),
    buttons: [{
        text: 'Close',
        handler: function(){
            win.hide();
        }
    }]
});
win.on('minimize', function(){
    win.toggleCollapse(false);
});
win.show();

Upgrading LayoutDialog to Window

In 1.x, a separate LayoutDialog class was required to embed a BorderLayout into a dialog. In 2.0, the LayoutDialog no longer exists — any Container can contain any style of layout, so it's now as simple as giving the Window a layout config value of 'border' and adding Panels as needed. This example also demonstrates the use of many new config options in the 2.0 code. They will not all be covered here, but are all documented in the Ext 2.0 API docs.

Implementation Notes:

• In the "Tabbed Dialog From Markup" example above, we added a TabPanel directly inline by defining it inside the items config. In this example, each component is constructed separately and then later added into the Window's items config by reference. This is a convenient way of creating references that you can keep for later use if needed (although any component, including Panels and TabPanels, can be accessed at any time via Ext.getCmp('id')).
• Note that you can even mix building the Window contents in multiple ways. The Window container and header elements are defined in markup using the applyTo config. The center tab and west region are populated by explicitly defining their contentEl configs, pointing them at the elements containing their contents. The secondary tab contains content defined inline via the html config. There are many options for building layouts from contents in 2.0!
• One subtle difference is how you can apply custom styles to the contents. In the 1.x example, an inline style declaration was required in the markup to add padding to the panel bodies. In 2.0, there is a special bodyStyle config that allows you to apply custom body styles in code. In this example, passing that in the defaults config simply applies it to each contained item (the 'nav' and 'tabs' components).

1.x Markup 2.0 Markup

<div id="layout-dlg" style="visibility:hidden;">
    <div class="x-dlg-hd">1.x Layout Dialog</div>
    <div class="x-dlg-bd">
        <div id="west" class="x-layout-inactive-content" style="padding:13px 10px;">
        West
    </div>
    <div id="center" class="x-layout-inactive-content" style="padding:10px;">
            A cool layout dialog from markup!
    </div>
    </div>
</div>

<div id="layout-win" class="x-hidden">
    <div class="x-window-header">2.0 Layout Dialog</div>
    <div id="west" class="x-hidden">
        West
    </div>
    <div id="center" class="x-hidden">
        A cool layout dialog from markup!
    </div>
</div>

1.x Code 2.0 Code

var dialog = new Ext.LayoutDialog("layout-dlg", {
    width: 400,
    height: 200,
    shadow: true,
    west: {
        split: true,
        initialSize: 100,
        titlebar: true,
        collapsible: true,
        animate: true
    },
    center: {
        autoScroll: true,
        tabPosition: 'top',
        closeOnTab: true,
        alwaysShowTabs: true
    }
});
dialog.addButton('Close', dialog.hide, dialog);
 
var layout = dialog.getLayout();
layout.beginUpdate();
layout.add('west', new Ext.ContentPanel('west', {title: 'West'}));
layout.add('center', new Ext.ContentPanel('center', {title: 'First Tab'}));
layout.add('center', new Ext.ContentPanel(Ext.id(), {
        autoCreate: true, 
        title: 'Another Tab',
        background: true
}));
layout.endUpdate();
dialog.show();

var tabs = new Ext.TabPanel({
    region: 'center',
    margins: '3 3 3 0', 
    activeTab: 0,
    defaults: {autoScroll:true},
 
    items:[{
        title: 'First Tab',
        contentEl: 'center'
    },{
        title: 'Another Tab',
        html: 'Some other content'
    }]
});
 
var nav = new Ext.Panel({
    title: 'West',
    region: 'west',
    contentEl: 'west',
    split: true,
    width: 100,
    collapsible: true,
    margins: '3 0 3 3',
    cmargins: '3 3 3 3'
});
 
var win = new Ext.Window({
    applyTo: 'layout-win',
    closable: true,
    width: 400,
    height: 200,
    minimizable: true,
    border: false,
    plain: true,
    layout: 'border',
    defaults: {bodyStyle: 'padding:10px;'},
    buttons: [{
        text: 'Close',
        handler: function(){
            win.hide();
        }
    }],
    items: [nav, tabs]
});
 
win.on('minimize', function(){
    win.toggleCollapse();
});
win.show(this);

Upgrading QuickTips for 2.0

Introduction

The 1.x QuickTips functionality was available via the global QuickTips singleton, and all quick tips were created by rendering the singleton's quick tip with different options. In 2.0, the functionality has been broken out into four different classes:

• Tip: The base class for quick tips and tooltips
• ToolTip: A basic tooltip class that can be instantiated and associated with any element dynamically (extends Tip)
• QuickTip: A specialized tooltip for markup-based tooltips (extends ToolTip)
• QuickTips: The singleton for global markup-based tooltips, as in 1.x.

This section will only cover upgrading the singleton from 1.x to 2.0. Make sure you chcek out the 2.0 API docs for details on using the Tip and ToolTip classes.

The QuickTips singleton should migrate pretty easily to 2.0, with only a few minor changes. The most important is how to change config values on the singleton. In 1.x, you could change configs directly on the singleton itself. For example:

Ext.QuickTips.trackMouse = true;

In 2.0, you must access the singleton's internal quick tip instance first via the getQuickTip method:

Ext.QuickTips.getQuickTip().trackMouse = true;

QuickTips Singleton API Changes

1.x 2.0 Notes Config Options animate — No longer supported in 2.0. autoDismiss — Tooltips always autoDismiss now unless dismissDelay is set to 0, so no need for a separate config. autoDismissDelay dismissDelay This was renamed since autoDismiss was removed. This single config now handles both of the previous ones — setting dismissDelay = 0 is equivalent to autoDismiss = false in 1.x. autoHide autoHide The option is still there, but is no longer supported at the singleton level and must be specified per tooltip. hideOnClick — No longer supported in 2.0. Tag Attributes width qwidth This applies to the attributes used when specifying quick tips from markup. The width attribute was renamed to avoid potential conflict with the browser width attribute name.

Converting MasterTemplate to XTemplate

Introduction

MasterTemplate provided basic sub-template processing for the Template class, but didn't offer much flexibility. It required each sub-template to be defined and applied separately, and only supported basic formatting functions. In 2.0, the XTemplate class provides a completely new level of power and flexibility. This section will only cover what's necessary to get a MasterTemplate converted into a working XTemplate — however, you should definitely examine the many examples in the 2.0 XTemplate API docs for additional information about how to use this powerful new class.

Basic MasterTemplate Conversion Steps

1. Change any name attributes in tpl tags to for attributes. If you previously used an unnamed tpl which you were filling using the fill method, you will now need to give it a for attribute.
2. Change the value of the for attribute to a valid object/array which will be in the variable you are applying. Since an XTemplate can now contain multiple nested tpl tags, make sure that your objects and arrays are at the same level in the data and template.
3. Change the syntax of member formatting functions if needed (see API reference below).
4. Apply an object which meets the specs of your template. Most likely, your data format will have to change in order to properly map to a nested XTemplate. See the code below as an example (note how the anonymous object containing the "title" property and the array have been combined into a single data object in 2.0):

1.x:

var tpl = new Ext.MasterTemplate(
    '<fieldset style="padding:10px;"><legend>{title}</legend>',
    '<tpl name="foods">',
        '<div>{quantity} - {name} ({desc})</div>',
    '</tpl>',
    '</fieldset>'
);
tpl.compile();
 
var foods = [
{quantity: '5', name: 'Apples', desc: 'Red and juicy'},
{quantity: '1', name: 'Bread', desc: 'Whole wheat'},
{quantity: '2', name: 'Cookies', desc: 'Chocolate chip'}
];                  
tpl.fill('foods', foods);
tpl.append(document.body, {title: 'Shopping List'});

2.0:

var tpl = new Ext.XTemplate(
    '<fieldset style="padding:10px;"><legend>{title}</legend>',
    '<tpl for="foods">',
        '<div>{quantity} - {name} ({desc})</div>',
    '</tpl>',
    '</fieldset>'
);
tpl.compile();
 
var shoppingList = {
    title: 'Shopping List',
    foods: [
    {quantity: '5', name: 'Apples', desc: 'Red and juicy'},
    {quantity: '1', name: 'Bread', desc: 'Whole wheat'},
    {quantity: '2', name: 'Cookies', desc: 'Chocolate chip'}
    ]
};
tpl.append(document.body, shoppingList);

MasterTemplate to XTemplate API Changes

MasterTemplate (1.x) XTemplate (2.0) Notes Tpl Tag Attributes name for The name attribute was changed to a for attribute. You must provide the name of a valid object or array within the data object instead of an arbitrary variable name to fill. Methods add,
addAll,
fill,
reset — No longer needed due to auto-filling of arrays. Use a for attribute with the name of your array to iterate and apply each array item to the template (e.g., <tpl for="my-array"> ... </tpl>). Inline Functions {property:fn(args)}
e.g.: {text:ellipsis(10)} see notes In 1.x inline functions were pretty much limited to simple formatting functions like the example shown. In 2.0, there is robust support for inline as well as template member functions that can be used for any type of formatting or other custom code. See the XTemplate API docs for many examples of executing custom functions in XTemplate.

Converting View to DataView

Introduction

In 1.x, the View class provided the ability to bind data to a custom UI representation using a Template, keeping the UI in sync when the data changed. There was also a JsonView class which wrapped up the functionality for managing JSON data into a custom View implementation. In 2.0, DataView is now the only view class available for binding data to templates.

The DataView class maps very closely back to the View class, with only a few minor changes (plus lots of additional functionality). The primary changes are:

• DataView extends BoxComponent instead of Observable, allowing it to interact consistently within layouts and with other components in the 2.0 model.
• View used the Template class, while DataView uses the much more powerful XTemplate for view rendering. See the section on upgrading from Template to XTemplate for complete details.
• While DataView adds many new config options, the most important one required for transitioning from a 1.x View is itemSelector. It is a new required config that tells the DataView how to identify the items within its DOM that should be considered items of the view (usually a class name applied to the container element of each item).
• JsonView is no longer supported (more details below).

Basic View Conversion Steps

1. Change the View constructor to DataView, and update the constructor signature as follows:
   • Move the first argument (container) into the DataView config as the renderTo value.
   • Move the second argument (template) into the DataView config as the tpl value.
2. Update the Template to an XTemplate. This may include making some of the changes outlined in the section on Upgrading to XTemplate.
3. Add an itemSelector to the DataView config object, along with a selector class in the template, if needed.

In the following upgrade example, the following styles and data/store are used in both versions:

CSS Styles Test Data/Store Definitions

<style>
    body { margin:30px; }
    .company-node { 
        float:left;
        width:120px;
        height:80px;
        padding:10px;
        margin-right:10px;
        border:1px solid #ccc;
        background:#eee;
        cursor:pointer;
    }
    .view-sel { 
        border:1px solid #999;
        background:#ffc;
        margin-top:3px;
        margin-left:3px;
        width:114px;
        height:74px;
    }
</style>

var myData = [
    ['Adobe Systems',71.72,'9/1/07'],
    ['Apple',29.01,'10/1/07'],
    ['Ext JS',83.81,'3/15/07'],
    ['Google',52.55,'10/11/06'],
    ['Yahoo',64.13,'5/5/07']
];
 
var store = new Ext.data.Store({
      proxy: new Ext.data.MemoryProxy(myData),
      reader: new Ext.data.ArrayReader({}, [
           {name: 'company'},
           {name: 'price', type: 'float'},
           {name: 'lastChange', type: 'date', dateFormat: 'n/j/y'}
      ])
});
store.load();

And now the template and view definitions between 1.x and 2.0. Note that the 2.0 XTemplate now has a tpl tag with a for attribute — this is how XTemplate iterates over each record in the data source.

1.x 2.0

var tpl = new Ext.Template(
    '<div class="company-node">',
        '<b>{company}</b><br />',
        'Price: {price:usMoney}<br />',
        '{lastChange:date("Y-m-d")}',
    '</div>'
);
 var view = new Ext.View('ct', tpl, {
     singleSelect: true,
     selectedClass: 'view-sel',
     store: store
 });

var tpl = new Ext.XTemplate(
    '<tpl for=".">',
        '<div class="company-node">',
            '<b>{company}</b><br />',
            'Price: {price:usMoney}<br />',
            '{lastChange:date("Y-M-d")}',
        '</div>',
    '</tpl>'
);
 var view = new Ext.DataView({
     tpl: tpl,
     renderTo: 'ct',
     singleSelect: true,
     selectedClass: 'view-sel',
     store: store,
     itemSelector: '.company-node' // required!
 });

There are no additional API changes between View and DataView besides those discussed above. All other config values, methods and events from 1.x are still supported by DataView.

Converting JsonView to DataView

As noted above, the JsonView class no longer exists in 2.0. It was a very specific convenience class, and DataView is intended to be flexible enough that such convenience classes should not be necessary. Because of that, there are a few changes needed to migrate to 2.0:

JsonView (1.x) DataView (2.0) Notes Methods clearFilter,
filter,
filterBy,
getCount,
load,
sort store.[method] In 1.x, these methods operated directly on the cached JSON data held by the JsonView. Now all of this functionality is handled generically by the underlying store. getNodeData getRecords This is not an exact match, but it's the closest available. Since DataView is generic, it deals with Record objects instead of a specific object type like JSON. Because of that, it's up to the developer to retrieve a set of records and then process them as needed depending on the type of underlying data that's being managed. Properties jsonData,
jsonRoot — These no longer apply — all data is now managed by the store. See the notes for getNodeData above.

Minor API Changes

Introduction

This section outlines all minor breaking API changes that only affect isolated members of a class, as opposed to a significant majority of a class's API or the class's underlying functionality. These changes are generally simple to diagnose and should only require minimal modifications to upgrade existing code.

Blank Image URL

This change is not strictly an API change, but is worth mentioning. Ext provides a variable for the path to "s.gif" which is required for CSS-based icons to display correctly. It is recommended that you set this path to point to your own server (it defaults to the extjs.com domain). In 1.1, the default recommended path was usually similar to:

Ext.BLANK_IMAGE_URL = '/ext/resources/images/aero/s.gif';

In 2.0, since the Aero theme has now been converted into the default theme, this default path has changed slightly, and may affect existing code that uses the default Ext folder structure:

Ext.BLANK_IMAGE_URL = '/ext/resources/images/default/s.gif';

API Changes

1.x 2.0 Migration Steps Notes Ext.Element getNextSibling next

1. Change any calls from getNextSibling() to next(null, true) for equivalent results

You can optionally pass a CSS selctor in 2.0 as the first arg (instead of null) for custom filtering, and next returns an Element by default (1.x always returned a DOM node), so pass true as the second arg for a DOM node. getPreviousSibling prev

1. Change any calls from getPrevSibling() to prev(null, true) for equivalent results

You can optionally pass a CSS selctor in 2.0 as the first arg (instead of null) for custom filtering, and prev returns an Element by default (1.x always returned a DOM node), so pass true as the second arg for a DOM node. Ext.EventManager wrap —

1. Remove the call

This was required in 1.x to wrap event handlers and override the default returned browser event object with an Ext.EventObject. This is now the default behavior in 2.0, so wrap can simple be removed. Ext.MessageBox getDialog : BasicDialog getDialog : Window

1. Any calls to getDialog must now be changed to expect a Window object.

For details on interacting with a Window instead of a BasicDialog, see the section in this document on migrating to Ext.Window. updateProgress(value, text) updateProgress(value, progressText, msg)

1. To behave exactly like 1.x, simply insert an empty string as the second arg: updateProgress(value, "", text).

By default, the progress text (second arg) will move from the window body into the progress bar itself between 1.x and 2.0. While technically a breaking (behavioral) change, most people will probably find the new default 2.0 behavior more desirable, so this will usually require no change in code. The new optional third argument will update the window body as the second argument did in 1.x. Ext.form.Field applyTo applyToMarkup, or
applyTo [config]

1. To simply convert 1.x calls into working code, replace all instances of field.applyTo() with field.applyToMarkup().
2. To improve the code, optionally consider converting the calls to config definitions using the apply config property. This will accomplish the same thing without the extra method calls.

The behavior of creating components from existing markup was moved into the Ext.Component base class so that all components implement it consistently, and the method was renamed to applyToMarkup so as not to conflict with the config property applyTo. The behavior and results should be exactly the same. Ext.grid.EditorGrid EditorGrid(container, config) EditorGridPanel(config)

1. Rename all references to Ext.grid.EditorGrid to Ext.grid.EditorGridPanel
2. Change the constructor per the Component constructor upgrade guidelines.

EditorGrid now extends GridPanel instead of Grid to take advantage of the 2.0 layout architecture, and so was renamed to EditorGridPanel. It also uses the 2.0 Component model which requires that the only argument to the constructor is a config object. Ext.tree.TreePanel TreePanel(container, config) TreePanel(config)

1. Change the constructor per the Component constructor upgrade guidelines.

TreePanel now extends Ext.Panel instead of Ext.data.Tree to take advantage of the 2.0 layout architecture. It also uses the 2.0 Component model which requires that the only argument to the constructor is a config object. beforeexpand,
expand,
beforecollapse,
collapse,
beforemove,
move beforeexpandnode,
expandnode,
beforecollapsenode,
collapsenode,
beforemovenode,
movenode

1. Add 'node' to the end of the names of any of these events in use.

These events were renamed to reflect the fact that they are actually node events, not tree events. Ext.UpdateManager UpdateManager Updater

1. Update the class name.

Class name was changed (although normally it is used indirectly via Element.update which would not be affected). update: callback (el, success, response) update: callback (el, success, response, options)

1. See notes...

The signature for the update method did not change. However, if a callback is passed in the update call, the method signature of the callback includes a new argument options which contains the original config passed to update. If you are currently passing additional custom params to your callback (e.g., via createDelegate), you'll have to add this new argument to your callback's signature to keep your argument list in order.