ext1.x to ext2.0升级指南2（转自官方）
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.
| 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({ |
| 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 (TBD)
Ext.form.Form - Rename the class anywhere it's used to Ext.form.FormPanel.
FormPanel now extends Ext.Panel in 2.0 so that it gets automatic layout handling. The following methods are no longer supported:
- column
- fieldset
- container
- start
- end
Ext.form.Layout
- Replaced Ext.form.Layout with Ext.layout.FormLayout
- Changed Fieldset to extend Ext.layout.FormLayout instead of Ext.form.Layout
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.
| 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.
var dialog = new Ext.BasicDialog(null, { |
var win = new Ext.Window({ |
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.
|
|
var dialog = new Ext.BasicDialog("markup-dlg", { |
var win = new Ext.Window({ |
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).
|
|
var dialog = new Ext.LayoutDialog("layout-dlg", { |
var tabs = new Ext.TabPanel({ |
Upgrading QuickTips for 2.0 (TBD)
- QuickTips class has been broken out into Tip, QuickTip (class), QuickTips (singleton) and Tooltip
- Changed width tag attribute to qwidth to avoid browser attribute conflicts
| Config Options | ||
| animate | ||
| autoDismiss | ||
| autoDismissDelay | ||
| autoHide | ||
| cls | ||
| hideDelay | ||
| hideOnClick | ||
| interceptTitles | ||
| maxWidth | ||
| minWidth | ||
| showDelay | ||
| text | ||
| title | ||
| trackMouse | ||
| width |
Converting View to DataView (TBD)
- Extends BoxComponent instead of Observable
- View used Ext.Template, DataView uses Ext.XTemplate
- itemSelector config is a new required property
- JsonView no longer exists as a separate class
Converting MasterTemplate to XTemplate
Template API Changes
| member formatting functions | |||
| VARIABLE:this.METHOD(arguments) | this.METHOD(arguments) | {[this.METHOD(arguments)]} | The syntax to execute member formatting functions has changed slightly through revisions. In 2.0 you can execute your member functions anywhere including in the new conditional if attribute. |
| tpl attributes | |||
| name | for | for | The name attribute was changed to a for attribute. You must provide the name of a valid object or array instead of an arbitrary name to fill. |
| Methods | |||
| add | — | — | No longer needed due to auto-filling of arrays. Use a for attribute with the same name of your array. |
| addAll | — | — | No longer needed due to auto-filling of arrays. Use a for attribute with the same name of your array. |
| fill | — | — | No longer needed due to auto-filling of arrays. Use a for attribute with the same name of your array. |
| reset | — | — | No longer needed due to auto-filling of arrays. Use a for attribute with the same name of your array. |
| set | — | — | Create a new XTemplate via the constructor. |
Converting to XTemplate
- Change any name attributes to a for attribute. If you previously used an unnamed tpl which you were filling, you will now need to give it a for attribute.
- Change the value of the for attribute to a valid object/array which will be in the variable you are applying
- Change the syntax of member formatting functions
- Apply an object which meets the specs of your template
For Example:
var iconTpl = new Ext.MasterTemplate('<fieldset><legend>{title}</legend><
tpl><img src="{img}" width="16" height="16" /> {desc}<br/></tpl></fieldset>');
var tplObj = {title: 'Order Legend'};
var iconArray = [
{img: 'images/icons/cog_orange.png', desc: 'Active Order'},
{img: 'images/icons/stop.png', desc: 'Cancelled Order'},
{img: 'images/icons/tick.png', desc: 'Completed Order'}
];
iconTpl.compile();
iconTpl.fill(iconArray);
iconTpl.append(document.body, tplObj);
Could be converted to:
var iconTpl = new Ext.XTemplate('<fieldset><legend>{title}</legend><tpl
for="iconArray"><img src="{img}" width="16" height="16" /> {desc}<br/></tpl><
/fieldset>');
var tplObj = {
title: 'Order Legend',
iconArray: [
{img: 'images/icons/cog_orange.png', desc: 'Active Order'},
{img: 'images/icons/stop.png', desc: 'Cancelled Order'},
{img: 'images/icons/tick.png', desc: 'Completed Order'}
]
};
iconTpl.compile();
iconTpl.append(document.body, tplObj);
Minor API Changes
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.
| Ext.Element | |||
| getNextSibling | next |
|
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 |
|
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 | — |
|
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 |
|
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) |
|
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] |
|
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) |
|
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) |
|
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 |
beforeexpandnode, expandnode, beforecollapsenode, collapsenode |
|
These events were renamed to reflect the fact that they are actually node events, not tree events. |