fireInternet/res/extjs/docs/guides/upgrade_41

Ext.data.JsonP.upgrade_41({"title":"Upgrade 4.0 to 4.1","guide":"

Ext JS 4.1 Upgrade Guide

\n

\n

Contents

\n

\n
1. Component render called only on top-most components
\n
2. Component onRender elements now exist in DOM at time of call
\n
3. Component renderTpl now calls helper methods
\n
4. callParent calls overridden method
\n
5. FocusManager no longer requires subscribe
\n
6. Component doLayout and doComponentLayout methods internal changes
\n
7. config setters are called to set default values
\n
8. Ext.data.Model can now join multiple Ext.data.Stores
\n
9. Ext.layout.container.Border adds splitter components to the container
\n
10. Infinite grid scrolling is simpler
\n
11. XTemplate improvements
\n
12. Grid plugins
\n
13. History
\n

\n

\n\n

This guide is meant to assist developers migrating from Ext JS 4.0.x to 4.1. Our goal was to maintain API compatibility\nas much as possible, despite the scope of the changes we are making to address bugs and user feedback. However, some\nchanges were needed, which you need to consider in further Ext JS development.

\n\n

If you encounter issues related to these API changes, please post your issues directly to our community forum found\nhere. If you are a support subscriber, you can also file your\nissue through our support portal found here.

\n\n

Component render called only on top-most components

\n\n

Previous releases used the render method to render all components in a top-down traversal. In 4.1, rendering is\nperformed in memory as markup which is then written to the DOM. This means that the render method of child components\nis not called. It's recommended that code in the render method be moved to either beforeRender (new to 4.1) or\nafterRender. For best performance, make style or add/removeCls adjustments in beforeRender so that these values\nare generated in the initial markup and not made to the DOM element as it would be in afterRender.

\n\n

Component onRender elements now exist in DOM at time of call

\n\n

Previous releases created the component's primary element (el) when calling the parent class method. This is no longer\npossible because of bulk rendering. Any logic that was performed prior to calling the parent method can be moved to\nthe new beforeRender method

\n\n

Component renderTpl now calls helper methods

\n\n

As part of bulk rendering, a renderTpl now calls helper methods on the template instance to inject content and\ncontainer items. This can be best seen in the default renderTpl for components and containers:

\n\n

Code for components:

\n\n

renderTpl: '{%this.renderContent(out,values)%}'\n

\n\n

Code for containers:

\n\n

renderTpl: '{%this.renderContainer(out,values)%}'\n

\n\n

callParent calls overridden method

\n\n

As part of formalizing Ext.define/override in Ext JS 4.1, it is now possible to name and require overrides just as\nyou would a normal class:

\n\n

Ext.define('My.patch.Grid', {\n    override: 'Ext.grid.Panel',\n    foo: function () {\n        this.callParent(); // calls Ext.grid.Panel.foo\n    }\n});\n

\n\n

The above code in Ext JS 4.0 would have called the base class foo method. You had to use the callOverridden to\naccomplish the above. In Ext JS 4.1, to bypass the overriden method, you just need to use the following code:

\n\n

Ext.define('My.patch.Grid', {\n    override: 'Ext.grid.Panel',\n    foo: function () {\n        Ext.grid.Panel.superclass.foo.call(this);\n    }\n});\n

\n\n

It is even possible for a class to require its own overrides. This enables breaking up a large class into independent\nparts expressed as overrides (a better approach than AbstractFoo and Foo).

\n\n

FocusManager no longer requires subscribe

\n\n

In previous releases, use of FocusManager was inefficient. FocusManager used to have to be pointed at a container\n(that is, it had to subscribe to the Container), and it would dig out all descendant components and add listeners to\nboth the descendants' elements and the descendant components themselves. It also had to monitor for adds and removes\nwithin that container tree.

\n\n

In Ext JS 4.1, onFocus and onBlur template methods in AbstractComponent are called on focus and blur of the\ncomponent's getFocusEl(). This is part of a component’s natural functionality. Non-focusable components won't\nimplement getFocusEl, and so they will not be part of the focus tree. Containers are focusable so that you can\nnavigate between and into them.

\n\n

Now, FocusManager hooks directly into AbstractComponent template methods and hears what is being focused. Once it's\nenabled it globally tracks focus, and adds framing which follows focus, and allows navigation into the\ncontainer->component tree.

\n\n

Component doLayout and doComponentLayout methods internal changes

\n\n

The doLayout and doComponentLayout methods have been modified. Their previous functionality has been combined into\nupdateLayout. As a component author, these methods can no longer be overridden to perform a custom layout since they\nwill not be called internally as they used to be. Instead you can override afterComponentLayout, which is given the\nnew size and old size as parameters, or you can respond to the resize event. Overriding afterComponentLayout is a\npossible way of postprocessing a Component's structure after a layout. If you are writing a derived component, the\nmethod override should be preferred. Just be sure to use callParent.

\n\n

Note that the size of the component should not be changed by this method,since the size has been determined already. If\nthe size is changed again, this could lead to infinite recursion at worst (since afterComponentLayout will be called\nagain) or just wrong layout.

\n\n

config setters are called to set default values

\n\n

In Ext JS 4.0, the config mechanism in Ext.define would create getter and setter methods, but the default value\nwould bypass the setter. In Ext JS 4.1 (and Touch 2), config defaults are now passed to the setter method. This can\naffect the timing of the first call to the setter method, but it is needed because setters are designed to enable\ntransformation-on-set semantics.

\n\n

The generated getter for a config property named “foo” looks like the following:

\n\n

getFoo: function () {\n    if (!this._isFooInitialized) {\n        this._isFooInitialized = true;\n        this.setFoo(this.config.foo);\n    }\n    return this.foo; // or call user-provided getFoo method\n},\n

\n\n

And the generated setter looks like this:

\n\n

setFoo: function (newValue) {\n    var oldValue = this.foo;\n\n    if (!this._isFooInitialized) {\n        this._isFooInitialized = true;\n    }\n\n    this.applyFoo(newValue, oldValue);\n\n    if (typeof newValue != ‘undefined’) {\n        this.foo = newValue;\n        if (newValue !== oldValue) {\n            this.updateFoo(newValue, oldValue);\n        }\n    }\n}\n

\n\n

If there is no applyFoo and/or updateFoo method, these calls are simply skipped. It is best to provide custom\nimplementations of applyFoo rather than a custom setFoo so that the rest of the provided boilerplate is preserved.\nAlternatively, responding only to changes in the property is often ideal, so implementing updateFoo may be better to\nignore setter calls that do not change the property.

\n\n

Ext.data.Model can now join multiple Ext.data.Stores

\n\n

A single record can belong to more than one store, especially in the case of a tree. The store property on a model\nnow only references the first store. Use the stores array to examine all stores.

\n\n

Ext.layout.container.Border adds splitter components to the container

\n\n

In Ext JS 4.1, when you configure components with split: true, Border layout inserts extra splitter components as\nsiblings of the current components. This simplifies Border and also allows enables it to dynamically modify regions.

\n\n

Infinite grid scrolling is simpler

\n\n

To scroll an indeterminate sized dataset within a grid, simply configure the Store with

\n\n

buffered: true,\nautoLoad: true,\n

\n\n

The grid will scroll through the whole dataset using natural scrolling, but only using as many table rows as are\nnecessary to display the visible portion of the data with a small (configurable) leading and trailing zone to provide\nscrolling.

\n\n

XTemplate improvements

\n\n

XTemplates now accept <tpl elseif> and <tpl else> tags between <tpl if> and </tpl>

\n\n

XTemplates now evaluate embedded script fragments as \"scriptlets\" using \"{% code %}\". The code is executed, but nothing\nis placed into the template’s output stream.

\n\n

Grid plugins

\n\n

Certain Sencha-supplied Grid plugins and Features may now be used with lockable grids. The non-locked columns of a\nlockable grid may be edited using a row or cell editor. The grouping Features divide into two to work on both sides of\nthe lockable grid and stay synchronized.

\n\n

See the examples/grid/locking-group-summary-grid.html example in your SDK for an example.

\n\n

History

\n\n

In previous versions of Ext JS, using the Ext.util.History class required you to manually add a form element to your\npage. This is no longer required. They will still be used if present, but it is best to remove them and allow the\nframework to generate what is required for the browser. The form that was required looked like this:

\n\n

<form id=\"history-form\" class=\"x-hide-display\">\n    <input type=\"hidden\" id=\"x-history-field\" />\n    <iframe id=\"x-history-frame\"></iframe>\n</form>\n

\n"});