Getting Started with Sencha Touch

This document describes how to get started with Sencha Touch. It explains the basic steps for using Sencha Touch to create Web applications for touch-based devices. Additionally, it provides detailed steps for creating the GeoTweets example application, which is one of the example applications included in the Sencha Touch release package.

This document is written for Web developers who want to quickly get started using Sencha Touch to create Web applications for touch-based devices. It assumes you have downloaded the Sencha Touch libraries. have a properly installed and configured Web server, and are familiar with Web application development and concepts such as JavaScript, HTML, Cascading Style Sheets (CSS), Web servers, and so forth.

This document contains the following sections:

Introduction to Sencha Touch

Sencha Touch is a JavaScript framework for creating Web applications targeted to touch-based devices. With Sencha Touch, you can use the skills you already possess to create an elegant and consistent user experience with minimal effort. Sencha Touch makes use of technologies such as HTML and CSS to provide native-quality application experiences without needing plugins.

Using Sencha Touch: Main Steps

  1. Set up your Environment
  2. Create the HTML File
  3. Create the Application JavaScript File
  4. Test the Application
  5. Update the Application for Production
  6. Put the Application into Production

To use Sencha Touch to create JavaScript applications for touch-based devices, follow these main steps:

  1. Set up your Environment

  2. Create the HTML File

    3. In the editor of your choice, create the HTML file for your application. For an example of an application HTML file, see Detailed Steps: Creating the HTML File.

    The application HTML file is where you specify links to:

    Save the HTML file with a logical name such as myapp.html. After you have finished writing the application and have put it on your local Web server, you will point your browser to this file name on your local Web server in order to view and test your application.

  3. Create the Application JavaScript File

  4. Test the Application

    5. To test your application:

    1. Upload the library files to the destination directory on your Web server.
    2. Upload the application files (html, js, and css) and all referenced files to the destination directory on your Web server.
    3. Point your browser to http://localhost:8080/myapp.html where:
      • localhost is the Web server host name or IP address
      • 8080 is the Web server port number
      • myapp.html is the name of the application HTML file

  5. Update the Application for Production

    6. When you are done testing your application, change the application's HTML file to point to the production version of the Sencha Touch library. To do so:

    1. Open the HTML file.
    2. Locate the code that specifies the Sencha Touch Library. For example:
      3. 	<!-- Sencha Touch JS -->
	<script type="text/javascript" src="../../sencha-touch-debug.js"></script>
    3. Replace sencha-touch-debug.js with sencha-touch.js. sencha-touch.js is optimized for production. It is compressed and does not contain documentation.
    4. Save the HTML file.

  6. Put the Application into Production

    7. When your application is ready for production, simply put a copy of the application's source files and any other files the application references on your production Web server.

Using Sencha Touch: Detailed Steps for Creating the GeoTweets Application

This section expands on the main steps described in the previous section by walking you step-by-step through the process of creating a Sencha Touch application. This complete source for the application, GeoTweets, can be found in the /examples/guide subdirectory in the Sencha Touch release package.

The GeoTweets application demonstrates how easy it is to use Sencha Touch to create a simple yet powerful application. The application:

The following sections describe the application HTML and JavaScript files and break down creation of the application code into steps.

Creating the HTML File

The first step in creating a Sencha Touch application is to create an HTML file that links to Sencha Touch and application CSS files, the Sencha Touch library, and the application JavaScript file.

The GeoTweets application HTML file is index.html and its contents are as follows:

 <!DOCTYPE html>
 <html>
 <head>
     <meta charset="utf-8">
     <title>GeoTweets</title>

	 <!-- Sencha Touch CSS -->
	 <link rel="stylesheet" href="../../resources/css/sencha-touch.css" type="text/css">

	 <!-- Custom CSS -->
	 <link rel="stylesheet" href="css/guide.css" type="text/css">

	 <!-- Google Maps JS -->
	 <script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=true"></script>

	 <!-- Sencha Touch JS -->
	 <script type="text/javascript" src="../../sencha-touch-debug.js"></script>

	 <!-- Application JS -->
	 <script type="text/javascript" src="src/index.js"></script>


 </head>
 <body></body>
 </html>

The HTML file for the GeoTweets application links to five files:

NOTE: Notice that the <body> tag in the HTML file is empty. This is because Sencha Touch automatically generates the page content via JavaScript.

Creating the Application JavaScript File

Once you have created the HTML file, you are ready to create the application JavaScript file. This section shows the entire contents of the application JavaScript file and breaks down the creation of the application code into steps.

The GeoTweets application JavaScript file is index.js and its contents are as follows:

Ext.setup({
    tabletStartupScreen: 'tablet_startup.png',
    phoneStartupScreen: 'phone_startup.png',
    icon: 'icon.png',
    glossOnIcon: false,
    onReady: function() {
        var timeline = new Ext.Component({
            title: 'Timeline',
            cls: 'timeline',
            scroll: 'vertical',
            tpl: [
                '<tpl for=".">',
                    '<div class="tweet">',
                            '<div class="avatar"><img src="{profile_image_url}" /></div>',
                            '<div class="tweet-content">',
                                '<h2>{from_user}</h2>',
                                '<p>{text}</p>',
                            '</div>',
                    '</div>',
                '</tpl>'
            ]
        });

        var map = new Ext.Map({
            title: 'Map',
            getLocation: true,
            mapOptions: {
                zoom: 12
            }
        });

        var panel = new Ext.TabPanel({
            fullscreen: true,
            cardSwitchAnimation: 'slide',
            items: [map, timeline]
        });

        var refresh = function() {
            var coords = map.geo.coords;

            Ext.util.JSONP.request({
                url: 'http://search.twitter.com/search.json',
                callbackKey: 'callback',
                params: {
                    geocode: coords.latitude + ',' + coords.longitude + ',' + '5mi',
                    rpp: 30
                },
                callback: function(data) {
                    data = data.results;

                    // Update the tweets in timeline
                    timeline.update(data);

                    // Add points to the map
                    for (var i = 0, ln = data.length; i < ln; i++) {
                        var tweet = data[i];

                        // If the tweet is geo-tagged, use that to display marker
                        if (tweet.geo && tweet.geo.coordinates) {
                            var position = new google.maps.LatLng(tweet.geo.coordinates[0], tweet.geo.coordinates[1]);
                            addMarker(tweet, position);
                        }
                    }
                }
            });
        };

        // These are all Google Maps APIs
        var addMarker = function(tweet, position) {
            var marker = new google.maps.Marker({
                map: map.map,
                position: position
            });
        };

        map.geo.on('update', refresh);

        var tabBar = panel.getTabBar();
        tabBar.addDocked({
            xtype: 'button',
            ui: 'mask',
            iconCls: 'refresh',
            dock: 'right',
            stretch: false,
            align: 'center',
            handler: refresh
        });

    }
});

The JavaScript code in the GeoTweets application file defines:

Note: In this application, components are created with the following syntax:

    var objectName = new Ext.ComponentName({
        objectDefinition
    });

where:

The following sections walk you through the steps for creating the application script.

Beginning the Application Script File

In the editor of your choice, begin writing the application script. The first lines of JavaScript code for the application file (index.js) are as follows:

Ext.setup({
    tabletStartupScreen: 'tablet_startup.png',
    phoneStartupScreen: 'phone_startup.png',
    icon: 'icon.png',
    glossOnIcon: false,
    onReady: function() {

The Ext.setup method sets up a page for use on a touch-enabled device. It allows you to set various start up properties and behaviors for your application. For detailed information on the Sencha Touch API, including this method, see the Sencha Touch API Documentation.

The GeoTweets application code specifies the following start up properties: