Sencha Touch Cookbook

Before you begin, check that JDK is installed and the following environment variables are set correctly:

Carry out the following steps:

With the preceding steps, you will be able to develop and test your application.

In steps 1 through 3, we downloaded and installed Android SDK, its Eclipse plugin, and PhoneGap, which are required for the development of the Android-based application. The SDK contains the Android platform-specific files, an Android emulator, and various other tools required for the packaging, deployment, and running of Android-based applications. The ADT plugin for Eclipse allows us to create Android-based applications, build, test, and deploy them using Eclipse.

In step 4, we created an Android 2.2 project by using the ADT plugin.

In steps 5 through 12, we created the required folders and kept the files in those folders, and updated some of the files to make this Android project a PhoneGap-based Android project. In step 5, we created two folders: libs and assets\www. The libs folder is where the PhoneGap and other third party libraries (JAR files) need to be kept. In our case, we only had to put in the PhoneGap JAR file (step 7). This JAR contains the PhoneGap implementation, which takes care of packaging the application for the target device (in this case, Android). The www folder is where the complete application code needs to be kept. PhoneGap will use this folder to create the deployment package.

In step 6, we copied the PhoneGap's JavaScript file which contains the implementation of the PhoneGap APIs. You will do this if you intend to use the PhoneGap APIs in your application (for example, to get the contacts list in your application).

In steps 8 and 9, we added the PhoneGap JAR file to our project's Build Path, so that it becomes available for the application development (and takes care of the compilation errors).

Then, in steps 10 through 13, we made changes to the manifest file to add the required application privileges, for example, access to the phone book, access to the phone status, and so on, when it is run on the Android 2.2 platform. You may learn more about the content of the manifest file and each of the elements that we added to it by referring to http://developer.android.com/guide/topics/manifest/manifest-intro.html.

In step 14, we moved the Sencha Touch library files to the www folder, so that they are included in the package. This is required to run Touch-based applications.

In step 15, we created the ch01_01.js JavaScript file, which contains the entry point for our Sencha Touch application. We have used the Ext.setup API. The important property is onReady, which is a function that Ext.setup registers to invoke as soon as the document is ready.

In step 16, we modified the index.html to include the Sencha Touch library related JavaScript: sencha-touch-debug.js and CSS file: sencha-touch.css, and our application specific JavaScript file: ch01_01.js. The sencha-touch-debug.js file is very useful during development as it contains the nicely formatted code which can be used to analyze the application errors during development. You also need to include the PhoneGap JS file, if you intend to use its APIs in your application. The order of inclusion of the JavaScript and CSS files is PhoneGap | Sencha Touch | Application specific files.

In step 17, we created an Android Virtual Device (an emulator), and deployed and tested the application on it.

Finally, in step 18 we deployed the application on a real Android 2.2 compatible device.

JDK is installed and the following environment variables are set correctly:

You should have created the ch01_01.js file as mentioned in the previous recipe.

Carry out the following steps:

In steps 1 and 2, we downloaded and installed XCode and other required tools and libraries. XCode is the IDE provided by Apple for the iOS-based application development.

In steps 3 through 6, we created a PhoneGap-based iOS project, using XCode.

In steps 7 through 14, we prepared the www folder for the application. Its contents are described in the Setting up the Android-based development environment recipe.

In step 15, we included the Sencha Touch related files and the application specific JS file—ch01_01.js—in index.html.

In steps 16 and 17, we deployed and tested the application in the simulator, as well as a real iOS device, such as iPhone.

The recipe named Setting up the Android-based development environment in this chapter.

JDK is installed and the following environment variables are set correctly:

Carry out the following steps:

In steps 1 and 2, we downloaded and installed the Blackberry SDK and PhoneGap required for Blackberry-based development.

In steps 3 through 6, we created a PhoneGap-based project for Blackberry.

In steps 7 through 9, we prepared the www folder by creating and copying our application specific folders and files.

In step 10, we built the project. In addition, we modified index.html to make it look exactly like the one created in the Setting up the Android-based development environment recipe.

In steps 11 and 12, we deployed and tested the application in the simulator, as well as in the real Blackberry device.

The recipe named Setting up the Android-based development environment in this chapter.

Make sure that your device has a WebKit compatible browser—Opera, Safari, or Chrome.

Verify that you have your GPRS or Wi-Fi enabled and working on your device, so that you are able to access the Internet.

You should have a web server such as Apache or Nginx deployed on a server, which is accessible on the Internet. For example, I have my web server running on http://walkingtree.in.

Carry out the following steps:

In step 1, we created the touch folder as a placeholder to keep our application code inside it. This would help us avoid polluting the web server's root folder.

In step 2, we copied the contents from the assets\www folder, which we prepared in the Setting up the Android-based development environment recipe. In step 3, we removed the <script> tag including the PhoneGap JS file, as we are not going to use its APIs in this book. Finally, in step 4, we accessed the application from a browser.

The recipe named Setting up the Android-based development environment in this chapter.

Make sure that you have completed the steps outlined in the Setting up the browser-based development environment recipe.

Carry out the following steps:

In step 1, we removed the unwanted folders and files which are not required for a typical production deployment.

In step 2, we replaced the debug version of the library with the production ready version, which is a compressed and minified version of the debug version. This file will not have the comments and also the code is obfuscated.

In step 3, we merged all the JS/CSS files into one single file and minified them. You may want to find out the best way to combine the files. This is generally done to load the application quickly. You may choose to combine one or more files into one or create individual minified files. It is totally based on your project design and code structure.

In steps 4 and 5, we removed the individual inclusion of the JS and CSS files from index.html and included the merged and minified ones. This recipe does not show the PhoneGap-related JS file. However, if your application is using it, then make sure that you also minify it, as the default one is not the production ready file.

Carry out the following steps:

The Ext.is class is instrumental in detecting the target device on which your application is being run. It uses the JavaScript's navigator object to detect the browser details, including the platform/device. For example, if the platform property in the navigator object has iPhone in it, then the target platform is iPhone, whereas if the userAgent property in the navigator object has Android, then the platform is Android.

Carry out the following steps:

Check that the support for different features is encapsulated inside the Sencha Touch's Ext.supports class. This class applies different mechanisms to find out whether a requested feature is supported by the target platform/device. For example, to find out whether the device supports touch, this class checks whether ontouchstart is present in the window object. Another example is, to find out whether SVG is supported on the target platform, it tries to add an SVG element (which it removes after successful creation and setting the flag to indicate that the device supports SVG) to the document.

Carry out the following steps:

Ext.Application provides various configuration options, which can be specified while constructing the Application instance. The name property provides the application name, which is also used as the namespace for the application being initialized. In addition, by default, the following namespaces are registered using the name property value:

Another property is launch. The launch function creates the application's viewport and runs any actions the application needs to perform when it boots up. The launch function is run once. In the preceding code, we are creating a panel in the full screen mode which will show Welcome to My App! in its body.

The recipe named Setting up browser-based development environment in this chapter.

Carry out the following steps:

The Application class provides a property named profiles, which is used to set up multiple profiles, as shown in the preceding code. When the application is launched, each of the configured profile functions such as phoneBlackberry , phoneAndroid , and so on, is evaluated in the order of their definition. The first profile function that returns true is the one which becomes the profile of the application. For example, if we are running the application on the Android phone, then phoneAndroid is the first function that will return true and, hence, the profile of the application will be set to phoneAndroid.

The current profile can be fetched from the application or any component. You can use the getProfile() method which returns the name of the profile, for example, phoneAndroid.

The profile is applied, by default, at the time of the application launch.

There are few more interesting options and features that the Application class provides to have a better control of the profiles and their application. Let's see what else can be done with the profiles.

setProfilesOnLaunch : false

new Ext.Application({
    name: 'MyApp',
    setProfilesOnLaunch: false,
    profiles: {
……..

new Ext.Application({
    name: 'MyApp',
    setProfilesOnLaunch: false,
    profiles: {
……..
},
    beforeprofilechange: function(profile, oldProfile) {
      return false;
    }

Carry out the following steps:

The Sencha Touch framework provides certain properties on the components, which directly affect the orientation change detection and notification. There are certain properties on the components based on which it derives whether the orientation change needs to be notified. The monitorOrientation property on the component directly instructs the library whether it has to monitor for the orientation change. This property is, by default, set to false—meaning, do not monitor for the orientation change. Hence, beforeorientationchange and orientationchange events will not be fired. However, the property fullscreen affects the monitorOrientation value. In the preceding code, fullscreen has been set to true, which sets the monitorOrientation to true and due to this, the library will monitor for the orientation change. When that happens, it fires the beforeorientationchange and orientationchange events. Any component which intends to handle the orientation change must implement the handler for these events.

On the container components (for example, Panel, TabPanel, and so on) enabling scrolling immediately sets the monitorOrientation to true.

Say, in your application, monitoring of the orientation change has been enabled, but some components neither want to handle the orientation change-related events, nor do they want the default behavior to be executed. In this case, these components will have to stop the orientation change and the subsequent section shows how to achieve that.

beforeorientationchange: function(thisPnl, orientation, width, height) {
   return false;
}