Newbie Tuesday: Hybrid App Basics Part 1

Computer Science as a Abstract Background Art

The following is the latest entry in a series of Tuesday blog posts covering basic topics in Titanium and JavaScript development.

Titanium allows developers to use local HTML inside a WebView component. There are a variety of compelling use cases for this, in situations where the browser provides the best tools for a given job. Whether it’s badass canvas libraries like three.js, as seen in the “Twisti” series on Forging Titanium, or simply displaying structured text in HTML, there are lots of places where a WebView and local HTML content may be the best solution.

Beyond these targeted uses of HTML in native applications, some apps choose to use HTML and CSS to render their entire user interface. These types of apps are popularly referred to as “hybrid” applications, where an HTML page is wrapped in a native shell, giving it access to native functions not usually available to a web application. Now, generally we believe that native UI is best for native applications, and will produce the most performant, familiar, and responsive interface. However, there may be use cases where an HTML/CSS-based UI may make sense given your app’s requirements.

In these situations, Titanium presents a very flexible hybrid application solution, while still retaining access to the thousands of native APIs and full native extensibility provided by the Titanium Mobile SDK. In this tutorial, we will show how local web pages can access native APIs in Titanium, using jQuery Mobile for our hybrid app’s user interface.

Embedding Local HTML

Creating an embedded WebView which references local HTML is trivial in the Titanium JavaScript API:

var win = Ti.UI.createWindow();

var webView = Ti.UI.createWebView({

Now, we place our index.html file, and the dependencies from jQuery Mobile, in our resources directory.


After throwing together some HTML to showcase basic jQuery Mobile UI, we’ll end up with a user interface which looks something like this.


Important note: By default, Titanium processes all JavaScript in the resources directory on Android to optimize for native apps. For a hybrid app today, you must prevent this behavior to keep your application HTML’s directory paths intact. To accomplish this, add the following line to your tiapp.xml:


So that’s the first part of the puzzle – in this way, we can embed and use local HTML in out native app just like we would if we were programming in the browser. But how do we access native functionality? Titanium doesn’t actually expose native APIs directly to the WebView. Native APIs are accessed indirectly using Ti.App.fireEvent and Ti.App.addEventListener. Using these messaging APIs, we can communicate between the JavaScript context of the web view wrapper and the native app.

We’ll explore techniques for doing that in the next article in this series.


  1. Just wondering about this approach with the upcoming support for Mobile Web as a ‘compile destination’ for appcelerator applications. What is going to be the ‘recommended approach’ going forward?

  2. We don’t believe the hybrid app approach is best for all applications. Nor will it ever be the preferred method of creating Titanium apps. But there are use cases for the hybrid approach, such as migrating from a browser-only or browser-based framework to a native app. Maybe you want to use a canvas-based game engine. There are some situations in which it makes sense.

    But as a general rule, as stated in the article, we think native UI is best for native applications. You will be best able to meet user expectations for a native app going that route. And if you want to have UI and non-visual code reuse from your native app your mobile web app, building out the UI with mobile web JavaScript APIs will still be more advantageous to you.

  3. Cool post! A lot of educational and government agencies require a hybrid approach because of certain accessibility rules they have to play by.

  4. After taking a quick stab at cross-platform (iOS and Android) webviews in Titanium Mobile, I ran into problems when trying to do anything interesting (because you’ll want to include images, stylesheets, or scripts from your HTML file). There’s a ton of issues in the Q&A section suggesting all sorts of crazy jumping jacks with URLs and stuff. I was relieved to find this post, and even better a GitHub project! It actually worked first try in my Android emulator and iOS simulator. It also worked on my Android device.

    It didn’t quite work on my iOS device, though. The javascript would load, but on my iOS device (iPhone in this case) the jQuery Mobile CSS would not be applied. If I created a new style sheet with only one simple rule in it, that style would be applied. If I copy+pasted the JQM CSS into that same file… no dice.

    I found this fix which works:

    From the HTML, you have to include the NON minified CSS and JavaScript files. It is not good enough to just include the NON min CSS. You have to include the NON min jQuery and JQM files, too. I even deleted all the minified files from my Resources folder just to be on the safe side.

    Once I did that, the styles loaded correctly on my iOS device.

    I’m working with an iPhone 4 on iOS 4.3.5.
    TitaniumMobile SDK 2.1.0.GA
    Building against iOS 4.3 SDK with Xcode 4.3.3 on Mac OS X 10.7.4

Comments are closed.