Ext JS 4.2 Upgrade Guide

This guide will assist developers migrating from Ext JS 4.1.x to 4.2. As always our goal
was to maintain API compatibility as much as possible. The areas where changes were needed
are described here to help you upgrade to Ext JS 4.2 as easily as possible.

ComboBox filters

Keystroke filtering of the store in a ComboBox is now implemented using the standard
Store filtering mechanism and is independent of any other filters an application may add
to the store.

Menus

Menu icon elements are now div elements in order that they can display the new glyph
configuration as well as background images. This means that any high-specificity rules
which made use of the img tag name to impose a background-image will have to change
to use the div tag name.

Grids

In addition to the new bufferedrenderer plugin (Ext.grid.plugin.BufferedRenderer),
many more grid features work together than in previous releases. If some combination of
standard grid features or plugins does not work together, please report it to us -
it is probably a bug!

A locking grid's View now aggregates the columns from both sides, and offers more of the
interface of a true grid view. In particular, the getGridColumns method has been added.

Row editing on a locked grid now produces one row editor which spans both sides.

MVC

• The Ext.app.EventBus is now a singleton, and is always available in the application.
• Ext.app.Controller no longer depends on Ext.app.Application to do things, and can
  be instantiated without bringing up the whole dependency tree.
• It is now possible to create your own Application class(es) extending from
  Ext.app.Application, and include custom logic in this class.
• Ext.application when passed the application class name just instantiates it. If
  passed a config object like before, it will declare new Ext.app.Application class with
  these config options, and instantiate it - same logic as with Application class.
• As the result of two items above, Ext.application no longer requires all of the
  dependency tree synchronously.
• It is now possible to explicitly declare all namespaces (project parts) in the
  Application class, to avoid any kind of ambiguities when resolving dependencies.
• Ext.app.Application now deals properly with its own ancestry and can be used as a
  top-level Controller in the application.
• A new concept of "event domains" was introduced; it is now possible to fire and
  listen to events not related to Components. Several domains are provided out of the box,
  and it's easy to add your own.
• You can pass method names to the control or listen methods on Controller.

Ext.Direct

• Direct namespaces can be nested, i.e. if the server side declares a class
  Foo.Bar.Baz with methods foo and bar, resulting stub methods will be
  Foo.Bar.Baz.foo and Foo.Bar.Baz.bar.
• Direct method callback can be canceled by listening to beforecallback events and
  returning false from event handler. This is true for both successful and failed calls,
  i.e. in case of server failures and such.
• Direct method accepts extra options Object as last parameter (after callback and
  scope), this object is applied to resulting Ext.Ajax.request parameters so it is now
  possible to set individual timeout and any other Ext.Ajax.request parameter per-method
  call.
• The options object is passed back to the Direct method callback function, so it is
  possible to pass any kind of data from caller to the callback.
• When the timeout option is specified, the Direct method is dispatched immediately,
  bypassing request queue.
• PollProvider now accepts empty "no events" responses without breaking.
• Each Provider can now be configured to have its events relayed by Ext.direct.Manager,
  so these can be listened to in centralized fashion.
• Direct proxy resolves string method names on first call, not at construction time as
  in previous release. This allows for late binding and fits better with MVC and builds.

Containers

Since version 4.0, i.e., in the Classic Theme, border:false was inherited by logic in the
Ext.container.AbstractContainer base class. This conflicted with the Neptune Theme
requirements and was removed. To restore this behavior, apply this override in your
application:

Ext.define('Compat.container.AbstractContainer', {
    override: 'Ext.container.AbstractContainer',

    onBeforeAdd : function(item) {
        this.callParent(arguments);

        // If the parent has no border, only use an explicitly defined border
        if (this.border === false || this.border === 0) {
            var b = item.border;
            item.border = Ext.isDefined(b) && b !== false && b !== 0;
        }
    }
});

Panel

Panel dragging has been enhanced to allow for simple, portal-like dragging. To enable this
mode on a draggable panels which are floating: true, add the new simpleDrag: true.

This causes the Panel to use a simple ComponentDragger the same as Windows use so
that it simply makes the Panel mobile. It does not use the default Panel drag mechanism
which uses the Ext.dd package (to allow the dragged Panel to interact with other
Ext.dd instances).

The default behavior is there to allow things like portal panel dragging to interact with
portal containers.

Borders in Neptune

Neptune is a (mostly) borderless design. Even so, you can always use the border config
to enable borders and bodyBorder to enable borders on the body element of a panel. This
implies there is some inherent border styling that is being enabled which is correct. As
in the Classic theme, there are CSS classes added to suppress the borders, but unlike in
Classic, the Neptune theme uses one CSS class to suppress the undesired borders.

While only one class is added to any element, there are 15 different classes declared in
"./packages/ext-theme-base/sass/src/layout/component/Dock.scss" for this purpose. If
none of these classes are added, then the element will present its natural border. The
classes that suppress the border edges are as follows:

• x-noborder-t
• x-noborder-r
• x-noborder-b
• x-noborder-l
• x-noborder-tl
• x-noborder-rl
• x-noborder-bl
• x-noborder-tr
• x-noborder-tb
• x-noborder-rb
• x-noborder-tbl
• x-noborder-trl
• x-noborder-trb
• x-noborder-rbl
• x-noborder-trbl

Also in Neptune, the borders of the panel, its body and docked items are "collapsed" using
another class, again from another set of 15 classes found in
"./packages/ext-theme-base/sass/etc/mixins/border-management.scss":

• x-panel-default-outer-border-t
• x-panel-default-outer-border-r
• x-panel-default-outer-border-b
• x-panel-default-outer-border-l
• x-panel-default-outer-border-tl
• x-panel-default-outer-border-rl
• x-panel-default-outer-border-bl
• x-panel-default-outer-border-tr
• x-panel-default-outer-border-tb
• x-panel-default-outer-border-rb
• x-panel-default-outer-border-tbl
• x-panel-default-outer-border-trl
• x-panel-default-outer-border-trb
• x-panel-default-outer-border-rbl
• x-panel-default-outer-border-trbl

Because this class has to impose the proper component and UI styling, these classes are
generated for each component/UI combination using the border-management mixin. So the
"panel" and "default" pieces of the above classes will vary for other components (such as
"window") and UI names.

Buttons and Tabs

The Ext.button.Button has changed its rendering to no longer render a button element.
This (greatly) simplifies the styling required for IE and the resulting button layout code.
The appropriate Aria role is added for accessibility concerns, but all Buttons now render
an a (anchor) tag.

Glyphs

Buttons, tabs, panel headers and menu items now support a glyph configuration that is
similar to iconCls and icon. The glyph uses Web Fonts to convert a character in to
a scalable image. To take advantage of this, you will need to pick out your own glyphs and
produce your own font-family. See the Ext.button.Button class and its glyph config
for further details.

Class System

We have added a callSuper method for situations where you need to patch/replace a method
on the target class in an override. This method should only be needed when an override
needs to workaround the behavior of a specific method it is designed to replace so is not
something to use in most cases. The typical use cases should still use callParent.