Chapter 1. How to Get Up and Running with Titanium

This first chapter covers the installation of Titanium and associated tools needed to create and test cross-platform apps. By the end of this chapter you will have created a simple app that will run without modification on iOS and Android phones, and tablets.

Congratulations! Give yourself a pat on the back; you have taken a big step towards creating great apps that work on both iOS and Android. You have made a very wise choice. The Titanium application from Appcelerator allows you to design native apps, apps that run on the device itself and not via a browser or over the Internet. Furthermore, a Titanium app is written in JavaScript, which if you have not used before, is a really nice, flexible language to write code in. It's certainly not just a language for making small scripts in a browser which is what it is commonly known for.

You will be using tried and tested functionality. Appcelerator started releasing apps to the Apple App Store in 2009. Since then over 50,000 apps have been deployed to both iOS and Android stores including flagship apps from eBay and NBC. The company has attracted over $50 million of funding from venture capitalists who have seen the potential. You will be supported by both the company and an ever-growing group of nearly 500,000 registered developers. With support for HTML5 web apps and plans to support both Blackberry 10 and Windows 8 later this year, the case for success becomes stronger and stronger.

You have shown an interest in the best tool for creating cross-platform native apps; apps that can make use of the features of the dominant smartphone and tablet platforms. This book will take you from the initial installation of the tool right through to the publishing of a polished app.

By the end of this book you should be able to publish quality apps through both the Android and iOS stores. This book will not teach you to program in JavaScript, but that should not concern you. If you have programmed in other programming languages, then JavaScript will not be alien to you. Some of the more specific language elements such as events and callbacks will be covered in the book. Should you need a reference, I would highly recommend you to look at some of the articles written by the godfather of JavaScript, Douglas Crockford (http://javascript.crockford.com/). Be aware that most Titanium apps can be programmed using only a small subset of the features provided by the language.

This first chapter covers the following:

The installation of Titanium Studio
The installation of Android and iOS SDKs
Creating your first Titanium app
A look into the configuration of apps

System requirements and restrictions

You can run Titanium on Mac, Windows PC, or Linux. Great; however, your choice of operating system may restrict the types of app you can develop, as not all emulators are available on all operating systems. Apple only releases the SDK for iOS on its operating system.

Tip

If you don't have a Mac but would like to release your code on iOS, then you can rent a Mac from MacinCloud (http://www.macincloud.com/). You can install Titanium Studio with the Apple SDK. It is slower than having a Mac of your own, but cheaper if you only need a short-term solution.

The following table shows what is available on which operating system:

Operating system	Android emulator	iOS emulator
Mac OS X	Yes	Yes
Windows	Yes	No
Linux	Yes	No

The Appcelerator site states that the minimum memory required to run Titanium is 2 GB. It is advisable to have at least 4 GB of memory, especially if you plan to run the Android emulator.

Tip

You do not need a Google developer account to install and use Titanium within the emulator, but if you plan to release code or run the app on a device, then you do. If you are serious about writing an app, it's a good idea to get an account. You cannot download the iOS SDK without purchasing the iOS developer program membership, so you will need it before beginning to write apps for iOS.

Installing Titanium

Assuming that you meet the preceding requirements, you are ready to install Titanium.

Time for action – installing Titanium Studio

Titanium comprises of Titanium Studio and the SDK. Titanium Studio is the development environment that is built on top of the Eclipse tool. Previous users of Eclipse should find Titanium Studio familiar. The SDK comprises of the magic of Titanium where your JavaScript source code is compiled into native code. To install Titanium perform the following steps:

Navigate to the Appcelerator site http://www.appcelerator.com and create an account.
Then follow the link to Download Titanium Studio, selecting the appropriate file for your operating system.
Open the downloaded file to install Titanium Studio.

What just happened?

You have downloaded and installed Titanium Studio. There will be a link to Titanium Studio either on the Start menu (Windows installation) or within the Applications folder (Mac). You have made the first big step towards creating cross-platform native applications.

Setting up Titanium Studio

Now it's time to set up and configure Titanium Studio.

Time for action – setting up Titanium Studio

Open Titanium Studio to begin the process of setting up the tool and perform the following steps:

Select the location for your workplace. This will be the base directory for your apps. All of your Titanium projects, and therefore apps, will be stored in directories below this.
Tip
The workspace location should be free of spaces and punctuation characters as it can affect the compilation and deployment of your apps.
Enter your Appcelerator account details and click on Next. After a short delay you will be presented with the Titanium welcome screen.

What just happened?

Titanium Studio was opened and a base workspace directory was specified. That completes the installation and initial configuration of Titanium Studio. If you have not already downloaded and installed the platform SDKs you wish to use, you should do this next so you can run code in the simulator. Titanium handles this installation beautifully.

Installing the Android SDK

If you plan to release your app for the Android platform or to just merely evaluate how it looks in the emulator, then you need to install the Android SDK.

If you have a question mark against the Android SDKs on the welcome screen icon, then Titanium cannot find the Android SDK on your system. Click on the icon to start the installation.

Time for action – configuring the Android SDK

To configure the Android SDK, perform the following steps:

Select the installation directory. Note that this does not need to be your Titanium workspace directory, as shown in the following screenshot:
Wait while the Android SDKs are downloaded and installed—this will take some time, there is a lot of content to install.
Configure the versions of SDKs you wish to use. Make sure that you include Android 2.2 as this is required by Titanium. You can install as many as you like and including 2.2, it just takes extra time to install. If you are not sure which Android device you are targeting, then just install the latest version and Android 2.2 for now. You can always add others later:
Wait while the selected APIs are downloaded and installed. This may take some time if you have selected several SDK versions.
Once the installation process completes, the SDK installer will exit and you will be returned to the Titanium dashboard where the question mark will have been cleared from the Android SDK. The Android emulator is now installed and configured for use with Titanium.

What just happened?

The Android SDK was downloaded and you had the opportunity to install specific versions of Android emulator you wish to test against. Titanium Studio took note of the installation directory and stored it in its preferences so that it can communicate with the emulator.

Installing the iOS SDK

If you have a Mac, then the chances are that the SDK that you will want the most is the iOS SDK. It's faster to load and less strict compared to the Android SDK.

Time for action – configuring the iOS SDK

To configure the Android SDK perform the following steps:

If the Titanium dashboard shows a question mark against the iOS SDK, it means Titanium cannot locate a suitable iOS SDK. Click on the icon to begin the process of installation.
Depending on your version of iOS the App store will be launched with the Xcode application. Install the application.
Once the installation process completes, the Titanium dashboard will be updated and the question mark will be cleared from the iOS SDK. The iOS emulator is now ready for use.

What just happened?

The latest iOS SDK was downloaded and installed. Titanium Studio took note of the installation directory so that it can call the emulator and display the logs on the console.

Installation problems – did something go wrong?

This is by no means an exhaustive reference of all the problems that you might encounter. For issues beyond this section you should refer to the developer documentation at docs.appcelerator.com, the Question & Answers section of the Appcelerator website https://developer.appcelerator.com/questions/newest or Appcelerator support.

If you have a problem with the installation of any of the SDKs, you can investigate the settings by selecting Preferences from the Titanium Studio menu. From there navigate to Titanium Studio | Titanium, which will result in the following screen:

From this screen you can select the location of the Titanium SDK home and Android SDK home, and investigate the location of the iOS SDK.

Your first cross-platform app

Now that Titanium Studio and the mobile SDKs have been installed, it's time to create your first cross-platform app.

Time for action – creating an app from a template

To create an app from a template perform the following steps:

From the dashboard select the Develop option:

On this screen within the Template section click on the New Project button and on the Default Project option. The following screen will appear:

An explanation of the options shown on the New Titanium Project screen is given in the following table:

Value	Optional/required	Description
Project Name	Required	This contains the name of the project. This will be the name that appears in the Project Navigator window, and will also be the name of the base director of the app. It will probably be the intended name of the app when you release it although it doesn't have to be. You can release the app under a different name.
App Id	Required	This contains the unique identifier for the app. The convention is to use the reverse domain name such as `com.domain.project`. The minimum requirement is to have an app ID of `xxx.x` (meaning you must have a dot and something after it). Also note that the app ID does not have to relate to a real domain nor to a domain that you own, although you would be wise to choose a domain you own.
Company URL	Optional	This contains the URL of the company that owns the app. This is optional and will not be shown on the app store.
Titanium SDK Version	Required	This contains the version of the Titanium SDK used to build your app. This can be changed later.
Deployment Targets	Required	This contains a list of checkboxes of device types that you intend to release the app on. This can be changed later. Leaving them all checked as the default setting is not an issue and will not get in your way.
Automatically Cloud enable this application	Required	Do you want to connect to the cloud for this application? This should be left unchecked for this first app. We will cover the cloud enabling of apps later in this book.

For this app the settings used are shown in the following screenshot:

Click on Finish. The project will be created and you will be presented with the following screen:
The screen is a summary of the contents of the tiapp.xml file. This file contains the project settings and customizations. It's a file you will become familiar with and refer to often when creating Appcelerator apps. We will take a closer look at the contents of this file later in the chapter, but first let's get straight to business and run our first cross-platform app, using the code that was just generated.

What just happened?

We created our first Titanium app. Titanium will have created the project files and directories required to support the development of the app. The main configuration files will have been configured based on the entries specified on the New Titanium Mobile Project screen.

The blank template has created an app with a small amount of code in it. Enough for us to run it to see what we have done. Everything is in place. You have a project, you have configured your emulators, what are you waiting for? Let's run the app!

Time for action – running an app in the emulator

You can run an app from either the run menu or from the navigator window, as shown in the following screenshot:

The buttons from left to right are as follows:

Button	Text
Collapse All	Collapse all items in the navigator
Link	Highlight in the navigator the current file in the main editor window
Debug	Run the app using the debugger
Run	Run the app in the emulator or on a connected device (phone or tablet connected to the computer)
Distribute	Package the app for release to an Android or iOS app store

To run the app in the emulator click on the Run button on the navigator window and select your chosen emulator from the list. If you are using a Mac, you can really exploit the power of Titanium by running the app on both Android and iOS at the same time. Otherwise, you will have to content yourself with only running the Android version of the app.

The Android emulator can take a long time to start. It certainly takes much longer than the iOS emulator. On some Android emulator devices, you need to unlock the screen display to allow the app to start.

The Android emulator will generate a lot of console messages (colored white), warnings (yellow), and the occasional error (red). This is normal; however, you may need to keep an eye on the errors to see if anything significant is going wrong.

What just happened?

If you have chosen to run the app on both Android and iOS, you will have two emulators running the Titanium application at the same time, as shown in the following screenshot:

Take a moment to congratulate yourself. By getting to this point you have installed Titanium, configured the emulators, and created your first app. You have come a long way, and have all the tools you need installed and at your disposal. All that remains in this book is to teach you how to make better apps than this.

Did the app fail to run?

Did the following message appear on the console?

"[DEBUG] Session could not be started: Error Domain=DTiPhoneSimulatorErrorDomain Code=2 "Simulator session timed out."

It is fairly common to see the timeout error message the first time a new app is run. Titanium has to go through some extra stages running the app for the first time, or the fist time the app is run after a project clean.

Try running it again.

Still didn't run? It's always worth rebuilding the project from a clean build, as this can clear many problems up. First clear down the existing build by clicking on Project | Clean… and then try re-running.

A review of the first app

For this next section, we will review what has been created on this first app. A number of files were created and you will need to be aware of some of them. These are the core files that are created for all apps, even this most basic one.

tiapp.xml

This file lives in the base directory of your project and contains your global project settings and compile-time customizations. Titanium Studio provides a clean, simple overview interface to the main settings listed in the file, as shown in the screenshot under step 3 of the Time for action – creating an app from a template section. From the overview screen you can:

Add new external modules to your project such as a Twitter or PayPal module extension
Add Appcelerator cloud services
Change the Titanium SDK used to compile your app
Enable deployment targets for supported platforms
Change app version, description, and publisher details

When you open the tiapp.xml file you will notice that along with the overview there is a set of tabs at the bottom of the screen, which allows you to switch between the overview and the raw XML. There are a number of things that you can only change from the raw XML view of the file, for example allowed orientations, so it's worth getting familiar with it. The table given next provides a list of most configurable items within the file. You don't need to examine and learn the options now, in fact it doesn't make for great reading; you can refer to it when you need it. We will look at the effects of some of the settings later in the book.

tiapp XML structure explained

XML	Description
<?xml version="1.0" encoding="UTF-8"?> <ti:app xmlns:ti="http://ti.appcelerator.org">	This is the standard XML header.
<deployment-targets> <target device="mobileweb">false</target> <target device="iphone">true</target> <target device="ipad">false</target> <target device="android">true</target> <target device="blackberry">false</target> </deployment-targets>	This is the list of supported devices. This can be changed from the overview screen.
<sdk-version>3.0.0.GA</sdk-version> <id>com.mycompany.firstapp</id> <name>FirstProject</name> <version>1.0</version> <publisher>Darren</publisher> <url>http://</url> <description>not specified</description> <copyright>2012 by Darren</copyright> <icon>appicon.png</icon>	These settings can be changed from the overview screen.
<persistent-wifi>false</persistent-wifi>	Does your app require a persistent Wi-Fi connection, or is the default that turns off after a period of inactivity ok?
<prerendered-icon>false</prerendered-icon>	This controls the shine/gloss effect that is added to icons on iOS. Setting this to `true` will prevent the gloss being added.
<statusbar-style>default</statusbar-style>	This is the status bar style. See `Titanium.UI.iPhone.StatusBar` in the API documentation to see allowable values.
<statusbar-hidden>false</statusbar-hidden>	Should the status bar be hidden?
<fullscreen>false</fullscreen>	Should the app start up using the full screen?
<navbar-hidden>false</navbar-hidden>	Should the navigation bar be hidden?
<analytics>true</analytics>	Do you want to gather analytic information about the app that will be automatically uploaded to the Appcelerator site?
<guid>d047116f-4ddb-4007-a24f-8702df42e59e</guid>	This is the unique internal identifier of your app. It is used with the analytics services. Do not change this value.
<property name="ti.ui.defaultunit">system</property>
<iphone> <orientations device="iphone"> <orientation>Ti.UI.PORTRAIT</orientation> </orientations> <orientations device="ipad"> <orientation>Ti.UI.PORTRAIT</orientation> <orientation>Ti.UI.UPSIDE_PORTRAIT</orientation> <orientation>Ti.UI.LANDSCAPE_LEFT</orientation> <orientation>Ti.UI.LANDSCAPE_RIGHT</orientation> </orientations> </iphone>	This lists the allowed orientations for the iOS devices you support. The options shown to the left restrict any displays on an iPhone to portrait (that is with the button at the bottom of the phone). All orientations will be supported by the iPad.
<android xmlns:android="http://schemas.android.com/apk/res/android"/>	This lists compile-time directives for the Android generator if any. This is also where any `AndroidManifest` overrides are listed.
<mobileweb> <precache/> <splash> <enabled>true</enabled> <inline-css-images>true</inline-css-images> </splash> <theme>default</theme> </mobileweb>	These are the settings and controls for the generation of a mobile web app.
<modules/>	Any external modules added to the project will be listed here. This can all be done from the overview screen.
</ti:app>	This is the closing XML line.

The good news is that for this chapter you don't have to change any of these settings.

Other files in the base directory

There are several other files that were generated when the project was created.

The other files in the project root directory are all text files that do not affect the operation of the app. They will be bundled with your app when it is released. You can update them if you feel the need.

The Resources directory

The other main element created at project inception is the Resources directory that looks as follows:

It contains one important file, app.js.

app.js

app.js is the entry point of any Titanium project—the first line of code that is executed. It can be freely edited as you wish. We will look at the contents of this file in later chapters. For now just accept the contents of the file that have been generated.

KS_nav_ui.png and KS_nav_views.png

KS_nav_ui.png and KS_nav_views.png are the two icons that appear at the bottom of the screen on the tabs. They are needed for this app but are not important elements of other apps. They can be deleted if they are not used.

The Android and iPhone directories

The android and iphone directories under the Resources folder contain the app icons and splash screens for many different iOS and Android devices supported by your app. We will look in more detail at the contents of these directories in Chapter 11, Testing and Deploying.

Pop quiz - Titanium installation and configuration

Q 1. You want to develop apps on your windows PC using Titanium. What platforms can you test on the machine?

iOS
Android
Symbian

Q 2. You will often need to refer to the app configuration file to change settings. Where can you find it?

<project base directory>/manifest
<project base directory>/resources/app.json
<project base directory>/tiapp.xml
<project base directory>/app.js

Q 3. What is the name of the source code file that is first run when an app starts?

<project base directory>/app.js
<project base directory>/resources/app.js
<project base directory>/init.js
<project base directory>/build/start.exe

Summary

A lot has been achieved in this chapter without a single line of code being written. You have installed Titanium, downloaded and configured the Android and iOS emulator, created a simple app, and run the app in the emulator.

The rest of the book will redress the code imbalance by concentrating on the tools and commands Titanium provides to help you design and distribute beautiful apps.

Appcelerator Titanium Application Development by Example Beginner's Guide: Once you've got into Appcelerator Titanium you'll never look back. This book is the perfect introduction to developing native cross-platform apps for iOS, Android, and Windows 8.

What do you get with eBook?

Key benefits

Description

Who is this book for?

What you will learn

Product Details

What do you get with eBook?

Product Details

Packt Subscriptions

Frequently bought together

Table of Contents

Recommendations for you

Customer reviews

Filter reviews by

People who bought this also bought

About the author

FAQs