This documentation relates to previous versions of Titanium Studio.

To see the latest documentation, visit docs.appcelerator.com.

Skip to end of metadata
Go to start of metadata
Chapters

Summary

This guide covers getting up and running with Appcelerator Titanium™. After reading it, you should be familiar with:

  • What the Titanium Platform is and what the SDKs provide
  • Installing Titanium, creating a new Titanium application, and running the application in the simulator
  • The structure of a Titanium application
  • Where to go next after "Hello World"

Welcome to Titanium!

Thanks for checking out Titanium - we hope you'll have your first native application for desktop or mobile up and running before dinner. Before we get into installing and running Titanium, let's (very) briefly go over what the Titanium platform is, how it works at a shallow level, and the kinds of capabilities you can expect to find.

Titanium Desktop SDK

The Titanium Desktop SDK provides a runtime environment for creating native desktop applications in HTML, CSS, and JavaScript. Titanium Desktop packages up your application source code (HTML/CSS/JavaScript) with a heavily augmented build of the popular Webkit open source web browser engine. Your Titanium Desktop application is basically a web page (or pages) and a web browser packaged into a single executable program. But your desktop app is more than just a local web page - Titanium Desktop apps have access to enhanced native functionality, like file system access, media, the ability to run external processes, native UI chrome, and more. You can also package Ruby, Python, or PHP code with your application, further extending the capabilities of your always-on desktop application.

Titanium Mobile SDK

The Titanium Mobile SDK allows you to create, run, and package real native mobile applications for iOS, Android, and BlackBerry (beta) devices using our cross-platform JavaScript APIs. But unlike Titanium Desktop, where applications run inside a web browser engine, Titanium Mobile applications are run against a standalone JavaScript engine which invokes native APIs. As a developer, you are in fact writing a native application - it's just that you're using cross-platform JavaScript rather than non-portable Java or Objective-C.

Titanium Mobile apps use native UI and platform APIs, and run at close to full native speed. The Titanium Mobile SDK works with the native SDK tool chains to combine your JavaScript source code, a JavaScript interpreter, and your static assets into an application binary that will be installed to an emulator or mobile device. It's worth mentioning that you could write your application UI in HTML and CSS, but typically you will use native UI components through a Titanium JavaScript API.

Titanium Studio

Titanium Studio is an IDE (Integrated Development Environment) that will enhance the user's experience while developing on the Titanium Platform.  Titanium Studio will help you create, run, and package Titanium Mobile or Titanium Desktop application projects.  All of the latest Mobile and Desktop SDKs will be maintained and kept up to date by Titanium Studio.  In addition to the nice features of an IDE ( i.e. syntax highlighting, content assist, code validation etc.) Titanium Studio also provides tight integration with the scripts used to create and run Titanium Projects.

Installing Titanium

Titanium Studio and the Mobile and Desktop SDKs are tested using the operating systems listed in the Titanium Compatibility Matrix. You may find that other OS versions will work fine also, but these are not officially supported.

To install the Titanium Studio application, navigate to the Titanium Studio Download Page and download the Titanium Studio installer for your operating system. If the download doesn't begin automatically, you can manually select the download you are interested in.

After a push-button installation on your operating system, Titanium Studio will be available to launch. The first time you run Titanium Studio, it will automatically download and extract the most current versions of the Mobile and Desktop SDKs. This can take some time. For those of you interested in doing mobile development, you will also need to download and install the native development SDKs for the devices you are targeting.

Preparing for iOS development

For iOS you will need to have a Mac running OS 10.6 (Snow Leopard) and an iOS developer account (the account is free, but to run on device, you will need to pay a $99/year fee for the iOS developer program). Installing the iOS SDK is as easy as downloading the SDK and Xcode, mounting and running the disk image, and following the onscreen instructions.

Preparing for Android development

The best guide to the complete Android setup procedure for Windows 7 is available in Installing on Windows 7.

Before doing any sort of Android development, you will need Sun/Oracle Java SDK (JDK) installed on your system. Refer to the Titanium Compatibility Matrix to determine the JDK version required.

Before you install anything, search your system for the java and javac executables, and run the following commands to confirm that they are of the correct vendor and version:

If you have multiple versions installed, you will need to ensure that the correct one is being used by default. To do this, run the same commands without the full path, and compare the results to those produced above:

The default executables can be controlled by adjusting your system's PATH variable.

If any of the commands above produce errors, they must be resolved for Titanium to work correctly.

Ubuntu users can take advantage of the sudo update-alternatives --config java command for setting the default java version. See the Ubuntu Documentation for more information.

For Android, you will need to download and unzip the Android SDK somewhere on your system and then run the $ANDROID_SDK/tools/android command from the resulting directory structure. This will bring up an attractive Java Swing UI which will allow you to install the various Android SDK components from the "Available Packages" side-menu.

At the time of writing, a correctly-configured system showed the following packages listed on the "Installed Packages" screen. Refer to the Titanium Compatibility Matrix to see the Android SDKs currently supported by Titanium.

This table explains the significance of these packages.

Package Type

Description

Android SDK Tools

Contains the executables contained in the $ANDROID_SDK/tools directory, including Android SDK and AVD Manager itself

Android SDK Platform-tools

Contains tools such as adb that Titanium Studio requires to function

SDK Platform Android x, API y

Android OS version x, plus support for API y. Note, some devices are only licensed to use the standard Android OS API, and so will not support advanced features such as maps etc. The advanced API must be installed separately (see below)

Google APIs by Google Inc., Android API y

Google API version y. Note, this advanced API should be used when targetting devices explicitly licensed to use it. In reality, this includes the majority of devices.

Every time you install or uninstall Android packages, it is crucial that you delete all of your virtual devices from the "Virtual Devices" screen (see screenshot below). A valid AVD will then automatically be recreated next time you launch your application from Titanium Studio.


You can find out more about all the useful tools available to assist with Android development from the Android SDK documentation.

Preparing for BlackBerry development

At this time, the BlackBerry version of Titanium Mobile is available as a beta preview. Be advised, however, that the BlackBerry version of Titanium Mobile requires a Windows environment, on which you will install the Eclipse-based development tool chain provided by RIM. Full instructions on how to prepare your system to a BlackBerry development can be found at the BlackBerry Support page.

Hello World!

When Studio launches for the first time, you will be prompted to sign in with your Appcelerator Network account. If you don't have an Appcelerator Network account, you can create one by clicking on the signup link. Once you are signed in, you will be ready to proceed with creating your first Titanium project.

To create a new 'Titanium Project go to File > New > Titanium Desktop Project' or 'Titanium Project go to File > New > Titanium Mobile Project'

Depending on which type of Titanium Project you decided to create, you will reach one of the following wizards:

In the fields provided, you will specify:

  • A project name - this will be the name that shows up on the App Explorer View
  • A directory under which your project will be generated (Location) - if you specify /Users/kevin, your project folder is created as /Users/kevin/YourProjectName
  • An application ID - this will be used for packaging/distribution later, and is usually specified in reverse-domain format
  • Your company/personal URL, whatever that may be
  • A Titanium Mobile/Desktop SDK version to use - this specifies which build scripts and libraries will be used to generate and run your application
  • For Mobile Projects, you will also need to select the Deployment targets.  If the Android check box is grayed out, you may need to configure the Android SDK path by clicking on the "configure..." link
  • For Desktop Projects, you will also need to specify the language modules used

If you didn't configure the Android SDK path during the project creation process, you can do so manually under the preferences window:  'Titanium Studio > Mobile'.  When browsing for the SDK, you will want to select the top-level folder of the Android SDK, containing the tools folder and other Android platform artifacts.

Click the "Finish" button to generate your new Titanium project.

What just happened?

Titanium will generate the necessary files to run a Desktop or Mobile project in the directory you specified during project creation. Your new project will appear in Titanium Studio in the App Explorer view.

Titanium Studio also has a Project Explorer view that provides the same basic functionality as the App Explorer view.

Where's my code?

After your project is created, a starter project will be created for you in the directory you specified. All project types share a similar layout:

  • A build directory, which contains the assets necessary for actually running your application code on your target OS(es). This directory can be safely ignored in version control, as it is dynamically generated by the Titanium SDK build scripts.
  • A Resources directory, which contains your application source code and any other assets (images, files, etc.) you will ship with your application.
  • A tiapp.xml file, which contains static configuration for your application.  When you open the tiapp.xml file, there will be a special editor to help the user edit the fields.

Running your application

Let's fire up the default application to make sure everything is working properly. Under the App Explorer view, hit the play icon and select "Android Emulator" to launch your app depending on your project type.

A default mobile application should look like this:

A default desktop application should look like this:

What's Next?

Now that you have a functional Titanium environment, there are numerous guides available here to further your education. The following are the recommended next steps for mobile developers:

Wiki book: Building Native Mobile Apps with Titanium

Our ever-growing wiki e-book will guide you from novice to expert as we cover topics like:

  • Building your user interface in Titanium
  • Coding and cross-platform strategies
  • Handling gestures and orientation
  • Debugging and managing memory
  • Publishing your app to the App Store and Market.

Sample apps

Check out our list of Example Applications for code to reuse or just to get an idea of what's possible in a Titanium app.

Video tutorials

Prefer to learn by watching? Check out videos from our Forging Titanium blog series, Codestrong conference videos, or the video version of the Building Native Mobile Apps course. They're all listed on our Videos page.

Labels
  • None