Docs Help

Terms, Icons, and Labels

Many classes have shortcut names used when creating (instantiating) a class with a configuration object. The shortcut name is referred to as an alias (or xtype if the class extends Ext.Component). The alias/xtype is listed next to the class name of applicable classes for quick reference.

Access Levels

Framework classes or their members may be specified as private or protected. Else, the class / member is public. Public, protected, and private are access descriptors used to convey how and when the class or class member should be used.

Member Types

Member Syntax

Below is an example class member that we can disect to show the syntax of a class member (the lookupComponent method as viewed from the Ext.button.Button class in this case).

lookupComponent ( item ) : Ext.Component
protected

Called when a raw config object is added to this container either during initialization of the items config, or when new items are added), or {@link #insert inserted.

This method converts the passed object into an instanced child component.

This may be overridden in subclasses when special processing needs to be applied to child creation.

Parameters

item :  Object

The config object being added.

Returns
Ext.Component

The component to be added.

Let's look at each part of the member row:

Member Flags

The API documentation uses a number of flags to further commnicate the class member's function and intent. The label may be represented by a text label, an abbreviation, or an icon.

Class Icons

- Indicates a framework class

- A singleton framework class. *See the singleton flag for more information

- A component-type framework class (any class within the Ext JS framework that extends Ext.Component)

- Indicates that the class, member, or guide is new in the currently viewed version

Member Icons

- Indicates a class member of type config

- Indicates a class member of type property

- Indicates a class member of type method

- Indicates a class member of type event

- Indicates a class member of type theme variable

- Indicates a class member of type theme mixin

- Indicates that the class, member, or guide is new in the currently viewed version

Class Member Quick-Nav Menu

Just below the class name on an API doc page is a row of buttons corresponding to the types of members owned by the current class. Each button shows a count of members by type (this count is updated as filters are applied). Clicking the button will navigate you to that member section. Hovering over the member-type button will reveal a popup menu of all members of that type for quick navigation.

Getter and Setter Methods

Getting and setter methods that correlate to a class config option will show up in the methods section as well as in the configs section of both the API doc and the member-type menus just beneath the config they work with. The getter and setter method documentation will be found in the config row for easy reference.

History Bar

Your page history is kept in localstorage and displayed (using the available real estate) just below the top title bar. By default, the only search results shown are the pages matching the product / version you're currently viewing. You can expand what is displayed by clicking on the button on the right-hand side of the history bar and choosing the "All" radio option. This will show all recent pages in the history bar for all products / versions.

Within the history config menu you will also see a listing of your recent page visits. The results are filtered by the "Current Product / Version" and "All" radio options. Clicking on the button will clear the history bar as well as the history kept in local storage.

If "All" is selected in the history config menu the checkbox option for "Show product details in the history bar" will be enabled. When checked, the product/version for each historic page will show alongside the page name in the history bar. Hovering the cursor over the page names in the history bar will also show the product/version as a tooltip.

Search and Filters

Both API docs and guides can be searched for using the search field at the top of the page.

On API doc pages there is also a filter input field that filters the member rows using the filter string. In addition to filtering by string you can filter the class members by access level and inheritance. This is done using the checkboxes at the top of the page.

The checkbox at the bottom of the API class navigation tree filters the class list to include or exclude private classes.

Clicking on an empty search field will show your last 10 searches for quick navigation.

API Doc Class Metadata

Each API doc page (with the exception of Javascript primitives pages) has a menu view of metadata relating to that class. This metadata view will have one or more of the following:

Expanding and Collapsing Examples and Class Members

Runnable examples (Fiddles) are expanded on a page by default. You can collapse and expand example code blocks individually using the arrow on the top-left of the code block. You can also toggle the collapse state of all examples using the toggle button on the top-right of the page. The toggle-all state will be remembered between page loads.

Class members are collapsed on a page by default. You can expand and collapse members using the arrow icon on the left of the member row or globally using the expand / collapse all toggle button top-right.

Desktop -vs- Mobile View

Viewing the docs on narrower screens or browsers will result in a view optimized for a smaller form factor. The primary differences between the desktop and "mobile" view are:

Viewing the Class Source

The class source can be viewed by clicking on the class name at the top of an API doc page. The source for class members can be viewed by clicking on the "view source" link on the right-hand side of the member row.

Sencha Touch 2.4

Guides
API
top

Upgrading from Sencha Touch 1.x to 2.x

Sencha Touch 2 brings a number of refinements to the framework. Since some of these changes require you to update parts of your application's code, this guide takes you through the changes you will need to make.

In addition to the guide, Sencha Touch 2 comes with a backwards-compatibility build that makes the migration process easier. Note that this build does not automatically guarantee that your 1.x app works out of the box. Wherever possible, the compatibility build figures out what your 1.x app code is trying to do and route it through to the 2.x API. Whenever it does this, the compatibility build logs a warning to the console indicating the items that you need to update.

If you follow the steps below and then correct any warnings the compatibility layer informs you about, you should obtain an application that runs on Sencha Touch 2.x.

SenchaCon 2011: Migrating from Touch 1.x to 2.0 from Sencha on Vimeo.

Class System

When migrating your app, the biggest change required is related to the way in which classes are defined. Sencha Touch 2 uses the upgraded class system derived from Ext JS 4, which brings powerful new capabilities such as mixins, dynamic loading, and the config system.

In Sencha Touch 1.x, there were two main ways of defining classes - using Ext.extend and using one of the MVC-specific convenience functions, such as regModel and regController. In Sencha Touch 2, all classes are defined the same way, using the Ext.define method. Let us consider the following 1.x example class and see how we could migrate it to the 2.x framework:

Geo.views.BillSummary = Ext.extend(Ext.Panel, {
    scroll: 'vertical',
    html: "Loading...",
    styleHtmlContent: true,
    initComponent: function() {
        this.tpl = Ext.XTemplate.from('billsummary');
        Geo.views.BillSummary.superclass.initComponent.call(this);
    },

    /**
     * Get the billSummary and update the contents of the panel.
     */
    getBill: function(bill) {
        Geo.CongressService.getBillSummary({
            bill: bill
        }, this.onBillSummaryResponse, this);
    },

    // private
    onBillSummaryResponse: function(billSummary) {
        if (Ext.isArray(billSummary.Paragraph)) {
            this.update(billSummary);
        } else {
            this.update('No Bill Summary Available');
        }

    }
});

In Sencha Touch 2.x, the previous code is written as follows:

Ext.define('Geo.view.BillSummary', {
    extend: 'Ext.Panel',

    config: {
        scroll: 'vertical',
        html: 'Loading...',
        styleHtmlContent: true
    },

    initialize: function() {
        this.callParent(arguments);

        this.tpl = Ext.Template.from('billsummary');
    },

    /**
     * Get the billSummary and update the contents of the panel.
     */
    getBill: function(bill) {
        Geo.CongressService.getBillSummary({
            bill: bill
        }, this.onBillSummaryResponse, this);
    },

    // private
    onBillSummaryResponse: function(billSummary) {
        if (Ext.isArray(billSummary.Paragraph)) {
            this.setHtml(billSummary);
        } else {
            this.setHtml('No Bill Summary Available');
        }
    }
});

The first thing to note is that we have swapped out Ext.extend for Ext.define. All of the old constituent parts are still present, but we have shuffled them around to use the new syntax. You can note that in version 2.x all of the class names are string based. This enables the dynamic loading system to automatically load these classes onto the page, if they are not already present. See the class system guide for more details.

Another change relates to moving all of the configuration options into a config object. The configuration options for each class can be found in the class documentation. When defining a class, any parameter found in the configuration section of the class should be placed into a config object.

The config system provides some key benefits, primarily a guarantee of the API's consistency. For example, the html config option guarantees that we can call getHtml and setHtml at any time, removing the guesswork from figuring out which functions to call. Every single config option has getter and setter functions that follow the same pattern as getHtml and setHtml. We use this to our advantage in the onBillSummaryResponse function, where we replaced the old 'update' function with the clearer setHtml function.

Finally, we replaced initComponent with initialize. In version 1.x of the framework, initComponent was only available on Component classes, which excluded all the other classes, such as Models, Controllers and utilities. In version 2.x, every class has an initialize function that you can implement if you want some logic to be performed on instantiation. Another detail to note here is that you no longer need the long Geo.views.BillSummary.superclass.initComponent.call(this); call - you can instead always use this.callParent(arguments) to call the superclass function.

MVC Migration

The MVC architecture in Sencha Touch 2 is a refinement of the approach taken in Sencha Touch 1. Although most of the concepts are the same, the syntax has been improved to make the API more expressive, and to make your code more readable and testable.

Models

Similar to all other classes in Sencha Touch 2, the Model classes and the rest of the data package now expect their configurations to be placed into a config block. Sencha Touch 2 also unifies the way you define all of your application's classes: Ext.regModel is no longer needed - instead a Model is just defined like any other class. Migrating your Models is very simple - considering you once had a Model like in the following code sample:

Ext.regModel('MyApp.model.User', {
    fields: [
        {name: 'name',  type: 'string'},
        {name: 'age',   type: 'int'},
        {name: 'alive', type: 'boolean', defaultValue: true}
    ],

    validations: [
        {type: 'presence', field: 'age'},
        {type: 'length',   field: 'name', min: 2}
    ],

    sayName: function() {
        alert(this.get('name'));
    }
});

In Sencha Touch 2 the same Model would look like the following:

Ext.define('MyApp.model.User', {
    extend: 'Ext.data.Model',

    config: {
        fields: [
            {name: 'name',  type: 'string'},
            {name: 'age',   type: 'int'},
            {name: 'alive', type: 'boolean', defaultValue: true}
        ],

        validations: [
            {type: 'presence', field: 'age'},
            {type: 'length',   field: 'name', min: 2}
        ]
    },

    sayName: function() {
        alert(this.get('name'));
    }
});

A Model migration is generally done in four steps:

  1. Replace Ext.regModel with Ext.define
  2. Create a new Model class by extending Ext.data.Model
  3. Move all of your Model's configurations into its config block
  4. Leave any custom functions (for example sayName in the previous code) outside of the config block

Views

Aside from migrating to the new class system syntax, view migration is quite simple. The main point to keep in mind is the convention regarding view class names. In Sencha Touch 2 and onward we recommend that your view class names follow the pattern MyApp.view.SomeViewName. Note that the 'view' is singular, which enables the class system to automatically load the view class from the file app/view/SomeViewName.js.

Application

When it comes to the Ext.application definition, you can keep most of the syntax from your 1.x app:

Ext.application({
    name: 'MyApp',

    icon: 'resources/images/logo.png',

    launch: function() {
        Ext.create('MyApp.view.Main');
    }
});

The only change is that we use Ext.create to instantiate MyApp.view.Main, which is our app's main screen.

In addition to this change, there is another slight change in approach when it comes to loading the models, views, controllers, and stores your application needs. In 1.x, it was common to define all of your controllers inside the Ext.application block, along with some of your models, views and stores. The rest of the dependencies could be scattered throughout your application, making it difficult to easily understand exactly what the app is composed of.

In Sencha Touch 2 we encourage you to define all of your application's dependencies inside the Ext.application block, instead of placing some of them inside Controllers. An example might look like this:

Ext.application({
    name: 'MyApp',

    icon: 'resources/images/logo.png',

    models: ['User', 'Group'],
    controllers: ['Users', 'Login'],
    views: ['Main', 'Users'],
    stores: ['Users'],

    launch: function() {
        Ext.create('MyApp.view.Main');
    }
});

Controllers

Similar to Model, Sencha Touch 2 expects any Controller to be defined like any other class, so the Ext.regController function is deprecated. In version 1.x we might have a controller such as the following:

Ext.regController("searches", {
    showSomething: function() {
        alert('something');
    }
});

which in version 2.x becomes as shown in the following sample code:

Ext.define('MyApp.controller.Searches', {
    extend: 'Ext.app.Controller',

    showSomething: function() {
        alert('something');
    }
});

As mentioned previously, if your 1.x controller defines additional model, view or store dependencies, you should move these into the Application instead. The compatibility build will still attempt to load those dependencies, but the non-compat build will not.

Routes

In Sencha Touch 1.x, a Controller was largely a collection of functions that could be dispatched to externally. Often this would mean that an Application would call Ext.dispatch, specifying the Controller name, which function to call and which arguments to pass to the function. Other times, the dispatching would be automatic, triggered by a change in the url picked up by the Router.

In 2.x, the Controller becomes a lot more proactive, actively registering inside its config block routes that it cares about:

Ext.define('MyApp.controller.Searches', {
    config: {
        routes: {
            'search/:query': 'doSearch'
        }
    },

    doSearch: function(query) {
        alert('searching for ' + query);
    }
});

This bypasses the need for a separate routes file and allows the Controller to indicate that whenever the page URL matches 'search/:query', the doSearch function will be called with the query. For example, if the page URL is currently http://myapp.com/#searches/abc123, doSearch will be called with 'abc123'. If the page URL later becomes '#searches/sencha', doSearch is called again with 'sencha'.

New Capabilities

In Sencha Touch 2 Controllers gained new capabilities, the most powerful of which are refs and control. For more information see the controllers guide.

Further Help

Once you have migrated everything you can and updated all of your code such that there are no more console warnings, your app should be mostly functional. For any specific problems the best place to get help is on the Sencha Touch 2 Forums.

Sencha Touch 2.4

Ext JS
Sencha Test
Cmd
Sencha Themer
GXT
IDE Plugins
Sencha Inspector
Architect
Sencha Fiddle
Touch
Offline Documentation

Sencha Test

2.0.1 2.0.0 1.0.3

Cmd

Cmd

Sencha Themer

1.1.0 1.0.2

GXT

4.x 3.x

IDE Plugins

IDE Plugins

Sencha Inspector

Sencha Inspector

Sencha Fiddle

Sencha Fiddle

Offline Documentation

Offline Documentation