All About Applications
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.
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.
Public classes and class members are available for use by any other class or application code and may be relied upon as a stable and persistent within major product versions. Public classes and members may safely be extended via a subclass.
Protected class members are stable public members intended to be used by the
owning class or its subclasses. Protected members may safely be extended via a subclass.
Private classes and class members are used internally by the framework and are not intended to be used by application developers. Private classes and members may change or be omitted from the framework at any time without notice and should not be relied upon in application logic.
static label next to the
method name. *See Static below.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).
Let's look at each part of the member row:
lookupComponent in this example)( item ) in this example)Ext.Component in this case). This may be omitted for methods that do not
return anything other than undefined or may display as multiple possible values
separated by a forward slash / signifying that what is returned may depend on the
results of the method call (i.e. a method may return a Component if a get method calls is
successful or false if unsuccessful which would be displayed as
Ext.Component/Boolean).PROTECTED in
this example - see the Flags section below)Ext.container.Container in this example). The source
class will be displayed as a blue link if the member originates from the current class
and gray if it is inherited from an ancestor or mixed-in class.view source in the example)item : Object in the example).undefined a "Returns" section
will note the type of class or object returned and a description (Ext.Component in the
example)Available since 3.4.0 - not pictured in
the example) just after the member descriptionDefaults to: false)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.
classInstance.method1().method2().etc();false is returned from
an event handler- 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
- 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
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.
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.
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.
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, inheritance, and read only. 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.
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:
Ext.button.Button class has an alternate class name of Ext.Button). Alternate class
names are commonly maintained for backward compatibility.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.
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:
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 is optimized for building apps that work across multiple platforms. To make writing apps as simple as possible, we provide a simple but powerful app architecture that leverages the Model View Controller (MVC) pattern. This approach keeps your code clean, testable, and easy to maintain, and provides you with a number of benefits when it comes to writing your apps:
An app is a collection of Models, Views, Controllers, Stores, and Profiles, plus additional metadata for app-related entities, such as application icons and launch screen images.
Note In this guide, Application indicates an instance of
Ext.application,
whereas application or app is the program you're coding.
Application is usually the first entity you define in a Sencha Touch app, for example:
Ext.application({
name: 'MyApp',
models: ['User', 'Product', 'nested.Order'],
views: ['OrderList', 'OrderDetail', 'Main'],
controllers: ['Orders'],
launch: function() {
Ext.create('MyApp.view.Main');
}
});
The name is used to create a single global namespace for your entire app, including all of its models, views, controllers, and other classes. For example, an app called MyApp should have its constituent classes follow the pattern MyApp.model.User, MyApp.controller.Users, MyApp.view.Main, and so on. This keeps the entire app under a single global variable, thus minimizing the chance of other code on the same page conflicting with it.
The app uses the defined models, views and controllers configurations to automatically load these classes into your app. The classes follow a simple file structure convention - models are expected to be in the app/model directory, controllers in the app/controller directory and views inside the app/view directory - for example app/model/User.js, app/controllers/Orders.js and app/view/Main.js.
Note that one of the models we previously specified is different than the others, in the sense that we specified its full class name ("MyApp.model.nested.Order"). We are able to specify the full class name for any of these configurations, if we do not follow the normal naming conventions. See the Dependencies section of the Ext.app.Application docs for details on how to specify custom dependencies.
Controllers are the glue that bind an app together. Controllers listen for events fired by the UI and take an action based on the event. Using Controllers helps keep your code clean and readable, and separates the view logic from the control logic.
For example, let's assume you require users to log in to your app via a login form. The view in this case is the form with all its fields and other controls. A controller should listen to the tap event on the form's submit button and perform the authentication itself. Anytime we deal with manipulating data or state, the controller should be the class that activates that change, not a view.
Controllers expose a small but powerful set of features, and follow a few simple conventions. Each Controller in your app is a subclass of Ext.app.Controller - although you can subclass existing Controllers, as long as they inherit from Ext.app.Controller at some point. Controllers exist in the MyApp.controller.* namespace. For example, if your app has a Sessions controller, it would be called MyApp.controller.Sessions and would exist in the file, app/controller/Sessions.js.
Although each Controller is a subclass of Ext.app.Controller, each one is instantiated only once by the Application that loaded it. At any time, there is only one instance of each Controller and the set of Controller instances are managed internally by the Application. Using an app's controllers config (as previously shown) loads all of the Controllers and instantiates them automatically.
Here is how we might quickly define the Sessions controller we described previously. We are using two Controller configurations:
Refs are an easy way to find Components on your page - in this case the Controller looks for all Components that match the formpanel xtype and assigns the first one found to the loginForm property. We subsequently use that property in the doLogin function.
The second configuration is control.
Similar to the ref's
config, this uses a ComponentQuery selector
to find all formpanel xtypes that contain a button
(for example, this finds the Submit button in our hypothetical login form).
Whenever a button of this type fires its tap event,
our Controller's doLogin function is called:
Ext.define('MyApp.controller.Sessions', {
extend: 'Ext.app.Controller',
config: {
refs: {
loginForm: 'formpanel'
},
control: {
'formpanel button': {
tap: 'doLogin'
}
}
},
doLogin: function() {
var form = this.getLoginForm(),
values = form.getValues();
MyApp.authenticate(values);
}
});
The doLogin function itself is straightforward. Because we defined
a loginForm ref, the Controller automatically generates
a getLoginForm function that returns the formpanel that it matches.
Once we have that form reference, we pull out its values
(username and password) and pass them to an authenticate function.
That is mostly what a Controller does - listens for events that fire
(usually by the UI) and initiate some action, in this case authenticating.
For more information on Controllers and their capabilities see the controllers guide.
Stores are an important part of Sencha Touch and power most of the
data-bound widgets. At its simplest, a Store is not much more than
an array of Model instances. Data-bound Components such
as [[touch:Ext.List List} and DataView
render one item for each Model instance contained in the Store.
As Model instances are added or removed from the Store, events fire,
which the data-bound Components listen to and use to update themselves.
See the Stores guide for more information on Stores, how they fit with Components in your app, and specific integration points with your Application instance that you should be aware of.
Sencha Touch operates across a wide range of devices with differing capabilities and screen sizes. A user interface that works well on a tablet may not work very well on a phone and vice versa, so it makes sense to provide customized views for different device types. However, we do not want to have to write our app multiple times just to provide a different UI, but we would like to share as much code as possible.
Device Profiles are simple classes that enable you to define the different types of devices supported by your app and how they should be handled differently. They are optional, meaning you can develop your app without profiles at first and add them in later, or never use them at all. Each profile simply defines an isActive function that should return true if that profile should be active on the current device, plus a set of additional models, views, and controllers that load if that profile is detected.
To add Profile support to your app, you need to tell your Application about the Profiles and create Ext.app.Profile subclasses for each, for example:
Ext.application({
name: 'MyApp',
profiles: ['Phone', 'Tablet']
// as before
});
By defining the Phone and Tablet profiles, the Application loads the app/profile/Phone.js and app/profile/Tablet.js files. Let's assume that the tablet version of the app supports additional capabilities, for example managing groups. This example shows how you can define a Tablet profile:
Ext.define('MyApp.profile.Tablet', {
extend: 'Ext.app.Profile',
config: {
controllers: ['Groups'],
views: ['GroupAdmin'],
models: ['MyApp.model.Group']
},
isActive: function() {
return Ext.os.is.Tablet;
}
});
The isActive function returns true whenever the app runs on what Sencha Touch determines to be a tablet. This is a slightly subjective determination because there is a near-continuous spectrum of device shapes and sizes with no clear distinction between phones and tablets. Because there is no secure way to state which devices are tablets and which are phones, Sencha Touch's Ext.os.is.Tablet is set to true when running on an iPad and false otherwise. If you need more fine-grained control, it is easy to provide any implementation you like inside your isActive function, as long as it returns true or false.
You should ensure that only one of your Profiles returns true from
its isActive function. If more than one profile returns true, only the
first one is used and the rest are ignored. The first profile that returns true
sets the Application's currentProfile,
which you can query at any time.
If the detected currentProfile defines additional models, views, controllers, and stores, these are automatically loaded by the Application, along with all of the models, views and controllers defined on the Application itself. However, all of the dependencies named in the Profile are prepended with the Profile name, unless the fully-qualified class name is provided. For example:
Most of the time, a Profile only defines additional controllers and views, as the models and stores are typically shared between all variants of the app. For a more detailed discussion of Profiles see the device profiles guide.
Each Application can define a launch function, which is called as soon as all of your app's classes have been loaded and the app is ready to launch. This is usually the best place to place any app startup logic, typically creating the main view structure for your app.
In addition to the Application launch function, there are two other places where you can place app startup logic. First, each Controller is able to define an init function, which is called before the Application launch function. Second, if you are using Device Profiles, each Profile can define a launch function, which is called after the Controller init functions, but before the Application launch function.
Note Only the active Profile has its launch function called - for example if you define profiles for Phone and Tablet and then launch the app on a tablet, only the Tablet Profile's launch function is called.
The launch order is:
When using Profiles, it is common to place most of the bootup logic inside the Profile launch function, because each Profile has a different set of views that need to be constructed at startup.
Sencha Touch has full Routing and History support. Several of the SDK examples, including the Kitchen Sink application, use history support to enable the back button for easily navigating between screens. This is especially useful on Android devices.
The following guides provide additional information on using the Sencha Touch application architecture:
Sencha Touch | Terms of Use