Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Removed outdated references to releases

...

Titanium provides platform-identification properties in the Ti.Platform namespace that you can use for conditional branching within your code. These are:

Property

Description

Sample values

Ti.Platform.name

Returns the name of the platform returned by the device

iPhone OS for iPhone or iPod, android for Android, returns the navigator.userAgent string on Mobile Web

Ti.Platform.osname

Returns an abbreviated identifier of the platform

iphone for iPhone or iPod, ipad for iPad, android for Android, and mobileweb on Mobile Web

Ti.Platform.model

Returns device model identifier

iPhone 3GS or iPod Touch 2G or Droid (unsupported on Mobile Web)

...

Titanium gives you various ways to include platform-specific resources, like images, stylesheets, and scripts, in your project. Titanium uses an "overrides" system to make it easy to use platform-specific resources. Any file in the platform-specific Resources directories (Resources/androidResources/iphone, or Resources/mobileweb) will override, or be used in place of, those in the Resources directory. You don't have to use any special notation in your code to specify that these files should be used.

Code Block
linenumberstrue
languagejs
langjavascript
var img = Ti.UI.createImageView({
	image: 'logo.png'
	/* Resources/android/logo.png or Resources/iphone/logo.png  or 
	*  Resources/mobileweb/logo.png will be used automatically if they exist
	*  when you build for those platforms, respectively
	*/
});

...

Here's an example that shows this feature in action with a CommonJS require() module. The code simply calls the base name of the file. Titanium grabs the platform-specific version at build time, which you can see in the Android emulator, iPhone simulator, and Chrome running the Mobile Web preview.

Image Removed

Platform-specific JSS
Warning

As of Release 3.2.0, JavaScript Style Sheets (JSS) are deprecated and no longer supported.

JavaScript Style Sheets (JSS) are a means to separate presentation and code. You supply an external stylesheet (which uses a syntax closely matching CSS) giving the file a name that matches the associated JS file. So, the stylesheet for the ui.js file is named ui.jss. Add a class or id property when defining your UI components. Then, refer to them within the JSS file like you would in a CSS file.

Code Block
titleui.js
langjavascript
var appceleratorLabel = Ti.UI.createLabel({
	text:'Appcelerator',
	id:'appceleratorLabel'
});
Code Block
titleui.jss
langcss
#appceleratorLabel {
	width:149;
	text-align:'center';
	color:'#999';
	font-size:'13';
}

That was a lot of explanation to get to the point of this section. Titanium supports platform-specific JSS files as well. You can have ui.android.jss and ui.iphone.jss files and Titanium will make sure the correct one is applied when you build your app. (Make sure you don't have a ui.jss file, or it will be used rather than the platform-specific versions.)

Strategies and recommendations

...

Branching in code is useful when your code will be mostly the same across platforms, but vary here and there. Long blocks of if...then code are difficult to read and maintain. Also, excessive branching will slow your app's execution. If you must use this technique, try to group as much code as you can within a branch and defer loading as much as possible to mitigate the performance penalty of branching.

It's best practice to query the platform value once, then store it in a globally accessible variable. Each time you request one of those properties, Titanium has to query the operating system for the value. This "trip across the bridge" takes a few cycles and if used too frequently could possibly slow your program. Something like the following would be more efficient:

Code Block
linenumberstrue
languagejs
langjavascript
// create a JavaScript alias to the platform-specific property
var osname = Ti.Platform.osname;
// Booleans identifying the platforms are handy too
var isAndroid = (osname=='android') ? true : false;

if (isAndroid) {
	// do Android specific stuff
} else {
	// do iOS, mobileweb, or other platform stuff
}

You can use JavaScript's ternary operator when you need to branch on a specific property, like this:

Code Block
languagejs
langjavascript
var isAndroid = (Ti.Platform.osname=='android) ? true : false;
var win = Ti.UI.createWindow({
	softInputMode: (isAndroid) ? Ti.UI.Android.SOFT_INPUT_ADJUST_PAN : null
});

...

Code Block
titleAnti-pattern!
languagejs
langjavascript
var osname = Ti.Platform.osname;
if (osname != 'android') {
   // don't assume this means iOS! It could be mobile web or some future-supported platform.
}

...

Using platform-specific JS files is likely to be most useful when your code is mostly different across platforms. This removes long if...then blocks from your main code. Separating platform-specific code reduces the chances of an error that comes from accidentally using the wrong platform's API or property. However, you'll have to remember to apply changes and fixes to each of the platform-specific files. So this approach could increase your work rather than reduce it.

Code Block
languagejs
langjavascript
var label2 = require('ui').label;
// will include /android/ui.js on Android
// and /iphone/ui.js on iOS
// there doesn't even need to be a /ui.js file!

...

  • platform-specific JS files where you embed the platform-specific formatting within the component definitions.
  • using the "Tweetanium technique" where you define a global style object, in which you store style settings determined with platform-branching code. Then, you use that object's properties when setting styles on your UI components.

Hands-on Practice

Goal

In this activity, you will use platform-specific JavaScript style sheets files with a simple test project.

Steps

  1. Create a new mobile project named Platform Test. Replace all of the code in app.js with:\

    Code Block
    langjavascript
    var win = Ti.UI.createWindow({ id:'mainwin' });
    var label = Ti.UI.createLabel({ id:'ptlabel' });
    win.add(label);
    win.open();
    
  2. Create two new files, one named app.iphone.js and the other named app.android.jss. In them, enter this code:\

    Code Block
    titleapp.iphone.jss
    langjavascript
    #mainwin {
    	background-color: 'blue';
    }
    #ptlabel {
    	color:'#fff';
    	top:10;
    	width:'auto';
    	height:'auto';
    	text:'I am iPhone!'
    
    }
    
    Code Block
    titleapp.android.jss
    langjavascript
    #mainwin {
    	background-color: '#f00';
    }
    #ptlabel {
    	color:'#fff';
    	top:10;
    	width:'auto';
    	height:'auto';
    	text:'I am Android!'
    }
    
  3. Build the project for both the iPhone and Android simulator/emulator (if your development computer supports both). The labels and colors should be specific to the platforms as set in the stylesheets.

References and Further Reading

...