JavaScript style events are one of the features I miss most when building native applications. The fact that Titanium allows for this on mobile is one of things I enjoy most about the platform. When Appcelerator introduced the ability to create native extensions in version 3.5.x, I began to explore how to pass information through between native iOS extensions and a Titanium application.
In the native world, Mutual Mobile solved this with their MMWormhole project. MMWormhole uses the Darwin Notifications and your application’s shared directory to pass messages between your app and your extensions. This seemed exactly what was needed to create events between your Titanium app and extension (or Watch Apps).
After some experimentation and hacking, a Titanium friendly version of MMWormhole called Ti.Wormhole as created. This allows for events to be published/subscribed between native extensions and your Titanium app. This is done through a native Wormhole client that you add to your native extension communicating with a native Titanium module installed within your app.
Ti.Wormhole in Action
The following video shows a quick walk through of the Ti.Wormhole running in the iOS simulator.
Before you get started
Before you get started, this development approach requires you program largely in native ( Objective-C or Swift ). So if you are not comfortable in Xcode, you might want to explore another alternative. Next, you will need a nightly build of Titanium 3.5.x or greater.
How does it work?
The mechanics are of Ti.Wormhole are straightforward. Messages are passed from MMWormhole in your Titanium app using a native module to your native extension. In your native extension another version of MMWormhole receives your messages providing you the information passed from your Titanium app. All Ti.Wormhole really does it make MMWormhole work nicely with Titanium.
Native Extension to Titanium
The process of sending events from your native extension to Titanium is relatively straightforward. First you need to create your native extension… and yes you do this completely native without any JavaScript or Titanium helpers. Next add the MMWormholeClient classes to your project. These will give you all of the helpers you need to talk to your Titanium app. Next you add the Ti.Wormhole module to your Titanium project. This enables your Titanium project to end/receive notifications.
Native to Titanium
Your native extension will publish notifications that will later be turned into Titanium JavaScript events. The following diagram illustrates the end to end process for doing so.
A diagram is great but how does this actually work? Well… to broadcast events from your extension to a Titanium app the first thing you need to do is to create an instance of the MMWormholeClient class. This class is one half of the bridge you need between your Titanium app and extension. The below shows how to create this class in both Objective-C and Swift. The key thing to remember, is the GroupIdentifier and Directory need to match the parameters use by the Titanium module. Otherwise your messages will not be received.
Objective-C Example:
Swift Example:
Next your native extension needs to send a notification. This is done using the passMessageObject function of the MMWormholeClient class. The important thing to remember here is that the identifier provided, needs to be the same as the event you are listening to in your Titanium app. In the below example we are broadcasting to an event named wormEvent.
Objective-C Example:
Swift Example:
That is all we need to do from our native extension, the rest will be done in our Titanium app.
The first thing we need to do in our Titanium app is to require an instance of the Ti.Wormhole module.
var wormhole = require('ti.wormhole');
Next we use the start method to configure the module to interact with the MMWormholeClient class in our native extension. The key thing to remember here is that the suiteName and directory need to match the parameters used to create the MMWormholeClient class instance in your extension.
wormhole.start({
suiteName:"Your suite identifier",
directory:"Your message directory"
});
Finally, you just need to use the addWormhole method to create an event listener. This will listen for a specific event and generate a callback when it is triggered.
wormhole.addWormhole("wormEvent",function(e){
console.log("Event in ti app: " + JSON.stringify(e));
});
Titanium to Native
It is just as easy to go from Titanium to Native. The following diagrams the end to end process that is used in sending messages from Titanium to your native extension.
I know what you are thinking, another diagram great, show me the code. To save time we will skip over the requiring the Ti.Wormhole module and calling Start method. This would be the same as the Native to Titanium example.
The first step is to send a message from Titanium using the Ti.Wormhole module’s post method as shown below. Since you will want to background your app and access notification center, you might want to use setTimeout to give yourself a few seconds.
setTimeout(function(){
wormhole.post("wormEvent",{displayNumber:displayCount});
},10000);
By calling post, a message is placed into the notification queue to be picked up by your native extension. To receive these notifications you need to add a listener in your native extension as shown in the following Objective-C and Swift examples.
Objective-C Example:
Swift Example:
Examples
The Ti.Wormhole project has examples written in both Objective-C and Swift. You can see video overview of the project here. Everything else is at https://github.com/benbahrenburg/Ti.Wormhole.
