Appcelerator Titanium Business Application Development Cookbook

Appcelerator Titanium Mobile is a platform for building cross-platform native mobile applications using modern web technologies, such as JavaScript, CSS, and HTML. Titanium Mobile is an open source project developed by Appcelerator Inc and licensed under the OSI-approved Apache Public License (Version 2).

The Titanium Mobile project is one of the most active on Github with a large number of commits each day. The Github repository is the focal point for many in the community including module developers, app developers needing night builds, and individual contributors to the Titanium project.

The Titanium ecosystem is one of the largest in the industry with a community of more than 450,000 worldwide developers running apps on 10 percent of the world's devices. Appcelerator boasts one of the largest mobile marketplaces providing third-party components for Titanium Mobile platform.

Titanium is a module-based mobile development platform consisting of JavaScript and native platform code (Java, Objective-C, and C++). The architectural goal of Titanium is to provide a cross-platform JavaScript runtime and API for mobile development; this differs from other frameworks' approaches of building "native-wrapped" web applications.

Titanium uses a JavaScript interpreter to create a bridge between your app's JavaScript code and the underlying native platform. This approach allows Titanium to expose a large number of APIs, and native UI widgets without sacrificing performance. Titanium's UI controls are truly native and not visually emulated through CSS. Thus, when you create a Ti.UI.Switch, it is actually using the native UISwitch control on iOS.

Each Titanium application is organized into layered architecture consisting of the following major components:

At runtime, the Titanium SDK embedded within your app creates a native code JavaScript execution context. This execution content is then used to evaluate your app's JavaScript code. As your JavaScript is executed, it will create proxy objects to access native APIs such as buttons and views. These proxies are special objects that exist both in the JavaScript and native contexts acting as a bridge between the two environments.

For example, if we have a Ti.UI.View object and we update the backgroundColor to blue, the property is changed in JavaScript and then the proxy then updates the correct property in the underlying native layer as shown in the following diagram:

Titanium provides a high-level cross-platform API, however it is not a write once, run anywhere framework. When building cross-platform apps, it is recommended to adopt a "write once, adapt everywhere" philosophy. With Titanium you can add platform-specific code to handle each platform's different UI requirements, while keeping your business logic 100 percent cross-platform compatible.

Building best of breed cross-platform applications, Titanium provides tools to:

In addition to platform tooling, the Titanium API is designed to assist with cross-platform development. Each major component such as Maps, Contacts, and FileSystem are separated into its own component namespaces under the top-level namespace called Ti or Titanium. These component namespaces then have their own child namespaces to segment platform-specific behavior.

An example of this segmentation is the Ti.UI namespace, which contains all UI components. This namespace contains common APIs such as Ti.UI.View and Ti.UI.TableView. Additionally, the Ti.UI namespace has platform-specific child namespaces such as Ti.UI.iPad containing controls such as Ti.UI.iPad.Popover. The same design applies to non-visual APIs such as Ti.Android, a namespace which contains Android-specific behavior.

The following example shows how to create a namespace for our app in our app.js called my with three subnamespaces called ui, tools, and controllers.

var my = {ui:{},tools:{},controllers:{}}

As we build our recipes, we will continue to add functionality to the preceding namespaces.

Adding the CommonJS modules used in this recipe is straightforward and consists of copying the datahelper.js and dateWin.js files into the root of our Titanium project as shown in the following screenshot:

The following recipe illustrates how to use CommonJS to create both UI and Tools modules. In the following example, a simple app is created, which allows the user to increase or decrease the date by a day.

//Create our application namespace
var my = {
  ui:{
    mod : require('dateWin')
  },
  tools:{},
  controllers:{}
};

my.ui.win = my.ui.mod.createWindow();

my.ui.win.open();

module.exports = helpers;

Creating a module is easy. You simply add a JavaScript file to your project and write your application code. By default, any variables, objects, or functions are private unless you have added them to the module or exports objects. The module and exports objects are special JavaScript objects created by Titanium and returned by the require method.

var myModule = require('datehelpers');

exports.myProperty = "I am a property";

exports.myObjectProperty = {
  foo:1,
  bar:'hello'
};

var _myObjectProperty = {
  foo:1,
  bar:'hello'
};

exports.myObjectProperty = _myObjectProperty

exports.AddDays = function(value,n){

  var workingValue = new Date(value.getTime());

  workingValue.setDate(workingValue.getDate()+n);

  return workingValue;
};

function addDays(value,n){
  var workingValue = new Date(value.getTime());
  workingValue.setDate(workingValue.getDate()+n);
  return workingValue;
};

exports.AddDays = addDays;

//Create our application namespace
var my = {
  tools: require('scope_test'),
  session:{
    foo: "Session value in context"
  }
};

my.tools.testScope();

exports.testScope = function(){
  Ti.API.log
  ("Test Module Scope - Foo =  " + my.session.foo);
  return my.session.foo;
};

The Ti.Platform namespace is helpful for providing platform and device-specific details, but often you need a high level of detail such as when you have a tablet running your app and if so if it is an iPad Mini.

Adding recipe components to your project

Adding the PlatformHelpers module to your project is easy. Simply copy the platform_helpers.js file into your project as shown in the following screenshot:

The following app.js demonstrates the PlatformHelpers module described earlier in this chapter. This sample app presents a window with your device details. Give it a try on all of your Android and iOS devices.

The device platform lookups will frequently be accessed across your app. To avoid performance issues by repeatedly crossing the JavaScript Bridge, we import the values we will use and assign them to properties in our CommonJS PlatformHelpers module.

exports.osname = Ti.Platform.osname;
exports.manufacturer = Ti.Platform.manufacturer;
exports.deviceModel = Ti.Platform.model;
exports.deviceHeight = Ti.Platform.displayCaps.platformHeight;
exports.deviceWidth = Ti.Platform.displayCaps.platformWidth;
exports.densitylevel = Ti.Platform.displayCaps.density;
exports.deviceDPI = Ti.Platform.displayCaps.dpi;

It is often helpful to have a Boolean indicator for the platform with which you are working. The following snippet shows how to create isAndroid and isIOS properties to accomplish this:

exports.isAndroid = exports.osname === 'android';
exports.isIOS = (exports.osname === 'ipad' || 
exports.osname === 'iphone');

exports.isSimulator = (function(){
  return (Ti.Platform.model.toUpperCase() === 'GOOGLE_SDK' || 
  Ti.Platform.model.toUpperCase()  === 'SIMULATOR' || 
  Ti.Platform.model.toUpperCase()  === 'X86_64')
})();

exports.supportsBackground = (function(){

//Determine if running on a tablet
exports.isTablet = (function() {

  var tabletCheck = exports.osname === 'ipad' || 
    (exports.osname === 'android' && 
    (!(Math.min(
    exports.deviceHeight,
    exports.deviceWidth
    ) < 700)));
    return tabletCheck;
})();

exports.newIPhoneSize = (function(){

  if(exports.osname !== 'iphone'){
    return false;
  }

  return (Math.max(
    exports.deviceHeight,
    exports.deviceWidth
  ) > 480);
});

exports.iPad = exports.osname === 'ipad';

exports.iPadMiniNonRetina= (function() {

Adding the CommonJS modules used in this recipe is straightforward and consists of copying the logger.js and mainWin.js files into the root of our Titanium project as shown in the following screenshot:

Application-level events allow you to implement a publish/subscribe pattern globally in your app, even across execution contexts. By simply adding a listener such as the following, you can receive messages fired from anywhere in your app:

Ti.App.addEventListener('app:myEvent', myFunctionToHandleThisEvent);

Firing a custom event in Titanium is easy. You simply use the Ti.App.fireEvent and provide the event name and an optional parameter payload. This example shows how to call the app:myEvent listener we defined earlier.

Ti.App.fireEvent('app:myEvent',"My parameter objects");

//Create our application namespace
var my = {
  ui:{
    mainWindow : require('mainWin').createWindow()
  },
  logger : require('logger')
};

//Run setup to create our logging db
my.logger.setup();

//Add a global event to listen for log messages
Ti.App.addEventListener('app:log',function(e){
  //Provide Log Message to CommonJS Logging Component
  my.logger.add(e);
});

//Open our sample window
my.ui.mainWindow.open();

var LOG_DB_NAME = "my_log_db";

exports.setup=function(){
  var createSQL = 'CREATE TABLE IF NOT EXISTS LOG_HISTORY '; 
  createSQL +='(LOG_NAME TEXT, LOG_MESSAGE TEXT, ';
  createSQL += 'LOG_DATE DATE)';
  //Install the db if needed
  var db = Ti.Database.open(LOG_DB_NAME);
  //Create our logging table if needed
  db.execute(createSQL);
  //Close the db
  db.close();
};

exports.add=function(logInfo){
  var insertSQL ="INSERT INTO LOG_HISTORY ";
  insertSQL +=" (LOG_NAME,LOG_MESSAGE,LOG_DATE)"; 
  insertSQL +=" "VALUES(?,?,?)";
  var db = Ti.Database.open(LOG_DB_NAME);
  //Create our logging table if needed
  db.execute(insertSQL,logInfo.name,logInfo.message, 
  new Date());
  //Close the db
  db.close();
};

var _press_Count = 0;

exports.fetchWindow=function(){

  var win = Ti.UI.createWindow({
    backgroundColor:'#fff'
  });

  var addLogButton = Ti.UI.createButton({
    title:"Fire Log Event", top:180, 
    left:5,right:5, height:50
  });

  addLogButton.addEventListener('click',function(e){		

    _press_Count ++;

    var logObject = {
      name:'test log',
      message:'example message ' + 
      _press_Count
    };

    Ti.App.fireEvent('app:log',logObject);
  });    
  win.add(addLogButton);
    
  //Return window
  return win;
};

Since application-level listeners are globally scoped, you need to take caution where and when they are defined. A general rule of thumb is to define application-level listeners in an area of your app that is always available and never reloaded, such as your app.js, CommonJS file which is only loaded once, or another bootstrapping method.

If you must define them within a window or other module that is loaded repeatedly, make sure you remove the listener when the object is no longer needed. To remove the event listener, you need to call the Ti.App.removeEventListener method with the same arguments used on creation. The following snippet shows how to remove the app:myEvent listener created earlier:

Ti.App.removeEventListener('app:myEvent', myFunctionToHandleThisEvent);