ext1.x to ext2.0升级指南1（转自官方）

官方网站速度太慢了 转到自己这里

Ext 1 to 2 Migration Guide

From Learn About the Ext JavaScript Library

Jump to: navigation, search

Document Status

This document is currently in progress (DRAFT status). However, it has enough content that I wanted to

make it available for initial review. Please do not edit or translate yet — add all comments, questions,

etc. to the discussion page. I plan on finalizing and "officially" publishing it for the 2.0 final release,

but it is open now for public comment and technical review. —Brian

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 is

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, i

t 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 (Coming soon)
• Ext Community Forums

Contents

[hide]

• 1 Document Status
• 2 Introduction
• 3 Summary of Breaking Changes
• 4 Upgrading to the 2.0 Component Model
• 5 Converting BorderLayout to 2.0
  • 5.1 Layout Architecture
  • 5.2 Layout Class Mappings
  • 5.3 Converting BorderLayout
    • 5.3.1 BorderLayout vs. Viewport
    • 5.3.2 Using the Items Array
    • 5.3.3 Adding Regions and Panels
    • 5.3.4 Creating Tabs
    • 5.3.5 Rendering the Layout
• 6 Upgrading Grids for 2.0
  • 6.1 Introduction
  • 6.2 Grid to GridPanel
  • 6.3 GridView API Changes
  • 6.4 Details Regarding Column Locking
• 7 Upgrading TabPanels for 2.0
  • 7.1 TabPanel Example
  • 7.2 TabPanel API Changes
  • 7.3 TabPanelItem to Panel
• 8 Upgrading Forms for 2.0 (TBD)
• 9 Upgrading BasicDialog to Window
  • 9.1 BasicDialog and Window API Comparison
  • 9.2 Simple Dialog Example
  • 9.3 Tabbed Dialog From Markup Example
• 10 Upgrading LayoutDialog to Window
• 11 Upgrading QuickTips for 2.0 (TBD)
• 12 Converting View to DataView (TBD)
• 13 Converting MasterTemplate to XTemplate
  • 13.1 Template API Changes
  • 13.2 Converting to XTemplate
• 14 Minor API Changes

<script type="text/javascript"> if (window.showTocToggle) { var tocShowText = "show"; var tocHideText = "hide"; showTocToggle(); } </script>

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 fo Observable, and has a few other relatively minor API changes. Details
• Form Changes
  The Form class now extends Panel, meaning that as a Container clas, 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 Replaced
  The View class has 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 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
   
3. either by using the renderTo or applyTo configs, or by rendering the component directly to its container
4. in code like so: myComponent.render('containerId');.
5. If any other arguments were present in 1.x, there will be an alternate config-based method for passing
6. 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 classed 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.

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.

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 conta

ins 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: "my-tabs">

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 collections 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	Equiv