Titanium 5.1.0 Sample App

The Titanium 5.1.0 SDK GA Release is now available along with a new Sample App that demonstrates most of the features, including a re-architected runtime permissions model, new Material Design elements, SafariDialog and also some major changes for iOS under the hood.

One of the most exciting new features is support for iPhone 6S 3D Touch with Peek & Pop and Home Screen Quick Actions. Exciting enough to deserve a dedicated 3D Touch Sample App.

For a full list of changes see the Release Notes.

Device Permissions

This Release re-architected the way an application requests device permissions in order to support the new Android 6.0 model for requesting device permissions during runtime and to achieve parity between the Android and iOS platforms. Support for the Windows platform will be added in a later release.


The Permissions tab has four buttons to test the new has*Permissions() and request*Permissions methods for Ti.Calendar, Ti.Contacts, Ti.Geolocation and Ti.Media. See permissions.js for how we’re using both these new methods as well as some existing to check and request permissions. Tap the top right Edit button to open the settings screen to change your initial response to the permission request.


Android requires uses-permission elements to be added to AndroidManifest.xml for any permission you may request at runtime. Titanium will do this automatically if it finds a call like Ti.Media.showCamera() in your code, but if all you use are the new has- and request permissions methods it will not. A more likely scenario where you run into this is when you don’t use the permissions in your JavaScript code but in a module. In this case you will have to manually declare the permissions in tiapp.xml.


On Android you can simply delete and reinstall the app for a blank slate. iOS remembers your permissions even after the app is removed. Change the app ID in tiapp.xml or reset the permissions for all your apps via Settings > General > Reset > Reset Location and Privacy. if you would like to test from a blank slate.

Platform-specific DefaultIcon

In Titanium 5.0 we introduced DefaultIcon.png to automatically generate all iOS app icons from a single source. In 5.1 we add support for Windows. With that we also introduce platform-specific DefaultIcons. iOS requires icons to be 24-bit with no alpha-channel. The other platforms do support or even promote the use of 32-bit PNGs with alpha-channel. To accomodate this the sample app has a 24-bit DefaultIcon-ios.png and a 32-bit DefaultIcon.png which will be used if you build the app for Windows:


NOTE: Other then showing off the DefaultIcon this sample app doesn’t do much on Windows. We will have another sample soon to show how you can now mix and match Titanium Views and views created via Runtime Direct API Access.


This release includes several new features for iOS.

Safari Dialog

With iOS 9 Apple introduced the SFSafariViewController. A great middle-road between having users leave your app by opening an URL in Safari or recreating a browser experience within your app using Ti.UI.WebView. Think of it as a modal window, webview plus Safari features like Reader, AutoFill etc.



The first two buttons on the iOS tab open the same URL in both Safari – using Ti.Platform.openURL – and the new Safari Dialog. Spot the differences!


Safari Dialog is not part of the Titanium SDK, but it is bundled as a separate module. This means we have to add it via tiapp.xml and require it in ios.js. As you can see it has an open and close event and methods to check if the iOS version supports it and if the dialog is currently open. You can also programmatically close the dialog, which we do after 5 seconds. You can set the tintColor of the buttons in the dialog to fit your app and tell it to automatically open Reader if available.


You can now change the height of a Ti.UI.Picker on creation. In our sample we have set a date-picker to a height of 50 so that it only shows one row at a time.


Starting in this release, when using the alert dialog style PLAIN_TEXT_INPUT or SECURE_TEXT_INPUT, you can set the placeholder, keyboardType and returnKeyType properties you will probably already known from Ti.UI.TextField and Ti.UI.TextArea. For LOGIN_AND_PASSWORD_INPUT you’ll have to use these properties prefixed with login and password.

The iOS tab of our sample demonstrates the use of these properties for all three styles. See the alertDialog() callback in ios.js for the implementation.

UserNotificationAction TEXTINPUT

Remember the Interactive Notifications Sample? With this release you can set an action’s new behavior property to TEXTINPUT to to have the user type and send a message directly from the notification:


I’ve updated the Interactive Notifications Sample so that you can reply with a custom chat message directly from the notification or even dictate it from your Apple Watch:


The iOS tab of our 5.1.0 sample allows you to test this small but significant new feature as well. Just hit the TEXTINPUT button and quickly lock your phone (⌘L in Simulator) or press the home button (⇧⌘H) to move the app to the background. The localnotificationaction event we listen to in ios.js will have the input in its new typedText property.

Under the hood

Also under the hood this release has a few major improvements for iOS. All three of them are optional for now.

App Thinning

Since Titanium 5.0 we generate asset catalogs for iOS app icons and launch images. This was the first step to support app thinning, a process in which the App Store generates a unique app with only the resources appropriate for the device which is downloading your app.

With 5.1 we introduce the option to enable app thinning for regular image assets as well. We use a hash of the original image path as the asset catalog name so that you can use them in ImageViews and backgrounds as usual. But you will no longer be able to access images via Ti.Filesystem. Because of this breaking change it is optional for now and can be enabled via tiapp.xml.


Build the app with and without app thinning (and clean in between builds: TIMOB-19968) to see that the ImageView on the iOS tab will always work, but Ti.Filesystem in ios.js won’t be able to find the file when it’s enabled.

JS Main Thread

For several reasons, we used to run the JavaScript engine on a dedicated KrollThread. We now give you the option to run it on the Main Thread instead. This will allow us to get rid of many workarounds in our SDK and improve its performance and stability. However, it can also produce unexpected behavior. Some of this are issues we need to solve, but a lot of is also a matter of understanding threads and callstacks and optimizing your code to run on a single thread with the UI.

Making the most of your Single Thread

Titan Ronald Treur gave an excellent talk about making the most of your Single Thread at tiConf EU 2014. As you go through his slides, remember that calls to Titanium proxies will now be on the same callstack and will have to wait till the stacked codeblocks have been executed before they run.



The last test on the iOS tab will loop over an array to generate thousands of UUIDs. Test with and without main thread enabled in tiapp.xml to see how with unoptimized code found in the testThread() callback in ios.js the progress bar won’t update until all operations are finished if main thread is enabled. This is because the calls to update the progress bar are stacked until after all of testThread() is done. To the user it will look like the progress bar fills up at once after waiting for all operations to be finished.

In both of the two optimized versions each iteration on the array is pushed to the callstack separately. This means that the updates to the progress bar can be executed after each iteration. Still not inmediately as with main thread disabled, but with similar result. As Ronald explains this can be achieved with JavaScript’s setTimeout() with no (0ms) delay. Both Underscore’s defer() bundeled with Alloy and the well-known async package on NPM wrap this method. As you will see async’s eachSeries() is faster (and also cleaner in code) then Underscore’s defer().

Auto Layout

With this release you also have the option to use Apple’s Auto Layout. This will allow us to support Slide Over and Split View in a future release.

We hide the complex API for Programmatically Creating Constrains so you can continue to use top, left etc and leave the rest up to us. Since this is quite a dramatic revision of our layout system it is optional for now and can be enabled via tiapp.xml. Please test it with your apps and report any issues.


The Auto Layout tab demonstrates one of the benefits of this change. Run the app in the Simulator both with and without the option enabled in tiapp.xml, activate Debug > Slow Animations (⌘T) and change the orientation of the device (⌘→) to see how with Auto Layout enabled the views slowly transition as the device rotates and also fixes a bug in the old layout system where the bottom percentage is not correctly calculated:


Android: Material Design

This release introduces a few new Material Design components and updates buttons and preference panes to use the AppCompat library for them to look identical on older Android versions as well.


Android Cards are meant to display heterogeneous (unique) content blocks and displayed with rounded corners and elevation. Create them with Ti.UI.Android.createCardView or <CardView> since Alloy 1.7.20.


NOTE: There are a few known issues with CardView, most prominently of which is that at the moment contentPadding and cardCornerRadius ignore the default unit and use pixels. This will be addressed in the next patch release.


The CardView tab demonstrates all of the different properties that you can use. It also discusses how cardUserCompatPadding, cardPreventCornerOverlap and cardMaxElevation determine how the cards look on Android 4 and older using the AppCompat library. Read more about these important properties in the Android Reference.

Reveal effect

Another new Material Design element is the reveal effect for Android 5 and later. Go to the Android tab and tap the first button to see how the square uses the reveal effect to hide and show when you pass animated:true to the methods:


ProgressBar Color

As the Android tab also demonstrates you can now set the color for the ProgressBar. Tap the bar to see it fill up in our primary brand color.

AppCompat Button & Preferences Dialog

Thanks to the AppCompat library the buttons throughout the app no longer look different between Android versions like they used to:


The same is true for the Preferences Dialog, which now has an Action Bar on older Android versions as well. If you’re not familiar with the Preferences Dialog, check our documentation and see how we define the dialog in preferences.xml.


To see the differences build the app with Titanium 5.1 for several Android versions to see the buttons always look the same. Then open tiapp.xml, remove the comments around <uses-sdk> and change the <sdk-version> to 4.1.1 or older. Build again for different Android versions to see that the buttons are like the above screenshot.


Comments are closed.