(For more resources on this topic, see here.)
Setting up your folder structure
Before we get started, you need to be sure that you’ve set up your development environment properly.
Root folder
You will need to have the folders and files for your application located in the correct web server folder, on your local machine.
On the Mac, this will be the Sites folder in your Home folder.
On Windows, this will be C:xamphtdocs (assuming you installed xampp).
Setting up your application folder
Before we can start writing code, we have to perform some initial set up, copying in a few necessary resources and creating the basic structure of our application folder. This section will walk you through the basic setup for the Sencha Touch files, creating your style sheets folder, and creating the index.html file.
- Locate the Sencha Touch folder you downloaded.
- Create a folder in the root folder of your local web server. You may name it whatever you like. I have used the folder name TouchStart in this article.
- Create three empty sub folders called lib, app, and css in your TouchStart folder.
- Now, copy the resources and src folders, from the Sencha Touch folder you downloaded earlier, into the TouchStart/lib folder.
- Copy the following files from your Sencha Touch folder to your TouchStart/lib folder:
- sencha-touch.js
- sencha-touch-debug.js
- sencha-touch-debug-w-comments.js
- Create an empty file in the TouchStart/css folder called TouchStart.css. This is where we will put custom styles for our application.
- Create an empty index.html file in the main TouchStart folder. We will flesh this out in the next section.
Icon files
Both iOS and Android applications use image icon files for display. This creates pretty rounded launch buttons, found on most touch-style applications.
If you are planning on sharing your application, you should also create PNG image files for the launch image and application icon. Generally, there are two launch images, one with a resolution of 320 x 460 px, for iPhones, and one at 768 x 1004 px, for iPads. The application icon should be 72 x 72 px. See Apple’s iOS Human Interface Guidelines for specifics, at http://developer.apple.com/library/ios/#documentation/userexperience/conceptual/mobilehig/IconsImages/IconsImages.html.
When you’re done, your folder structure should look as follows:
Creating the HTML application file
Using your favorite HTML editor, open the index.html file we created when we were setting up our application folder. This HTML file is where you specify links to the other files we will need in order to run our application.
The following code sample shows how the HTML should look:
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;
charset=utf-8">
<title>TouchStart Application - My Sample App</title>
<!-- Sencha Touch CSS -->
<link rel="stylesheet" href="lib/resources/css/sencha-touch.css"
type="text/css">
<!-- Sencha Touch JS -->
<script type="text/javascript" src="lib/sencha-touch-debug.js"></
script>
<!-- Application JS -->
<script type="text/javascript" src="app/TouchStart.js"></script>
<!-- Custom CSS -->
<link rel="stylesheet" href="css/TouchStart.css" type="text/css">
</head>
<body></body>
</html>
Comments
In HTML, anything between <!– and –> is a comment, and it will not be displayed in the browser. These comments are to tell you what is going on in the file. It’s a very good idea to add comments into your own files, in case you need to come back later and make changes.
Let’s take a look at this HTML code piece-by-piece, to see what is going on in this file.
The first five lines are just the basic set-up lines for a typical web page:
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;
charset=utf-8">
<title>TouchStart Application - My Sample App</title>
With the exception of the last line containing the title, you should not need to change this code for any of your applications. The title line should contain the title of your application. In this case, TouchStart Application – Hello World is our title.
The next few lines are where we begin loading the files to create our application, starting with the Sencha Touch files.
The first file is the default CSS file for the Sencha Touch library—sencha-touch.css.
<link rel="stylesheet" href="lib/resources/css/ext-touch.css"
type="text/css">
CSS files
CSS or Cascading Style Sheet files contain style information for the page, such as which items are bold or italic, which font sizes to use, and where items are positioned in the display.
The Sencha Touch style library is very large and complex. It controls the default display of every single component in Sencha Touch. It should not be edited directly.
The next file is the actual Sencha Touch JavaScript library. During development and testing, we use the debug version of the Sencha Touch library, sencha-touchdebug.js:
<script type="text/javascript" src="lib/sencha-touch-debug.js"></
script>
The debug version of the library is not compressed and contains comments and documentation. This can be helpful if an error occurs, as it allows you to see exactly where in the library the error occurred.
When you have completed your development and testing, you should edit this line to use sencha-touch.js instead. This alternate file is the version of the library that is optimized for production environments and takes less bandwidth and memory to use; but, it has no comments and is very hard to read.
Neither the sencha-touch-debug.js nor the sencha-touch.js files should ever be edited directly.
The next two lines are where we begin to include our own application files. The names of these files are totally arbitrary, as long as they match the name of the files you create later, in the next section of this chapter. It’s usually a good idea to name the file the same as your application name, but that is entirely up to you. In this case, our files are named TouchStart.js and TouchStart.css.
<script type="text/javascript" src="app/TouchStart.js"></script>
This first file, TouchStart.js, is the file that will contain our JavaScript application code.
The last file we need to include is our own custom CSS file, called TouchStart.css. This file will contain any style information we need for our application. It can also be used to override some of the existing Sencha Touch CSS styles.
<link rel="stylesheet" href="resources/css/TouchStart.css"
type="text/css">
This closes out the </head> area of the index.html file. The rest of the index.html file contains the <body></body> tags and the closing </html> tag.
If you have any experience with traditional web pages, it may seem a bit odd to have empty <body></body> tags, in this fashion. In a traditional web page, this is where all the information for display would normally go.
For our Sencha Touch application, the JavaScript we create will populate this area automatically. No further content is needed in the index.html file, and all of our code will live in our TouchStart.js file.
So, without further delay, let’s write some code!
Starting from scratch with TouchStart.js
Let’s start by opening the TouchStart.js file and adding the following:
new Ext.Application({
name: 'TouchStart',
launch: function() {
var hello = new Ext.Container({
fullscreen: true,
html: '<div id="hello">Hello World</div>'
});
this.viewport = hello;
}
});
This is probably the most basic application you can possibly create: the ubiquitous “Hello World” application. Once you have saved the code, use the Safari web browser to navigate to the TouchStart folder in the root folder of your local web server. The address should look like the following:
- http://localhost/TouchStart/, on the PC
- http://127.0.0.1/~username/TouchStart, on the Mac (username should be replaced with the username for your Mac)
As you can see, all that this bit of code does is create a single window with the words Hello World. However, there are a few important elements to note in this example.
The first line, NewExt.Application({, creates a new application for Sencha Touch. Everything listed between the curly braces is a configuration option of this new application. While there are a number of configuration options for an application, most consist of at least the application’s name and a launch function.
Namespace
One of the biggest problems with using someone else’s code is the issue of naming. For example, if the framework you are using has an object called “Application”, and you create your own object called “Application”, the two functions will conflict. JavaScript uses the concept of namespaces to keep these conflicts from happening.
In this case, Sencha Touch uses the namespace Ext. It is simply a way to eliminate potential conflicts between the frameworks’ objects and code, and your own objects and code.
Sencha will automatically set up a namespace for your own code as part of the new Ext.Application object.
Ext is also part of the name of Sencha’s web application framework called ExtJS. Sencha Touch uses the same namespace convention to allow developers familiar with one library to easily understand the other.
When we create a new application, we need to pass it some configuration options. This will tell the application how to look and what to do. These configuration options are contained within the curly braces ({}) and separated by commas. The first option is as follows:
name: 'TouchStart'
The launch configuration option is actually a function that will tell the application what to do once it starts up. Let’s start backwards on this last bit of code for the launch configuration and explain this.viewport.
By default, a new application has a viewport. The viewport is a pseudo-container for your application. It’s where you will add everything else for your application. Typically, this viewport will be set to a particular kind of container object.
At the beginning of the launch function, we start out by creating a basic container, which we call hello:
launch: function() {
var hello = new Ext.Container({
fullscreen: true,
html: '<div id="hello">Hello World</div>'
});
this.viewport = hello;
}
Like the Application class, a new Ext.Container class is passed a configuration object consisting of a set of configuration options, contained within the curly braces ({}) and separated by commas. The Container object has over 40 different configuration options, but for this simple example, we only use two:
- fullscreen sets the size of the container to fill the entire screen (no matter which device is being used).
- html sets the content of the container itself. As the name implies, this can be a string containing either HTML or plain text.
Admittedly, this is a very basic application, without much in the way of style. Let’s add something extra using the container’s layout configuration option.
My application didn’t work!
When you are writing code, it is an absolute certainty that you will, at some point, encounter errors. Even a simple error can cause your application to behave in a number of interesting and aggravating ways. When this happens, it is important to keep in mind the following:
- Don’t Panic.
- Retrace your steps and use the tools to track down the error and fix it.