Callbacks in Appcelerator Titanium Modules

Today’s guest post comes from Titanium developer Andrew Glover. Andrew talks about implementing “JavaScript-ish callbacks” associated with a native App47 Agent call in his post. Thanks, Andrew, for pulling this together.
Do you have a cool tutorial you’d like to share? Let us know and we’ll post it on our blog

I recently found myself implementing both an Android and iOS Appcelerator module for App47’s respective Agent libraries. Like PhoneGap plugins, Appcelerator modules are a way to bridge an Appcelerator app with native code running on a device; in this case, the native code happens to be App47’s Android and IOS Agents, which capture usage analytics and facilitate a few security features. Naturally, these Agent libraries are coded in Java and Objective-C.
In the end, what I wanted to implement was a JavaScript-ish callback associated with a native App47 Agent call. Alas, it took me a lot of digging to achieve this goal.
For example, for a timed event (which, as you’ve probably guessed, captures how long an event took), rather than the more traditional call which is inline:

var id = agent.startTimedEvent("openCrust 2.0.27");
openCrust({});
agent.endTimedEvent(id);

I wanted a more JavaScript friendly call that wraps the timed code like so:

agent.timedEvent("openCrust 2.0.27", function() {
  openCrust({});
});

This has the benefit of wrapping a desired event – there is no explicit need for anyone to code the ending – it is automatically done via the timedEvent call after invoking the passed in function.
The Titanium module documentation is a bit hard to find (that is, finding up-to-date valid documentation is challenging); your best bet to see how to do something interesting is to look at the various code repositories on Github followed by studying the API docs (i.e. JavaDocs and .h/.m files for iOS).
It turns out, invoking a JavaScript callback in either Android or iOS is fairly straightforward. In the case of Android, you need to use the KrollFunction type like so:

@Kroll.method
public void timedEvent(String name, KrollFunction callback) {
  String id = EmbeddedAgent.startTimedEvent(name);
  callback.call(getKrollObject(), new HashMap());
  EmbeddedAgent.endTimedEvent(id);
}

As you can see in the above code, I’m not doing anything special like passing in any arguments to the KrollFunction instance. If you want to do that, say in the case of passing in some special value that the corresponding callback will use, then you can either pass in a Map or an Object[].
For example, you can implement this style of callback where a custom value is passed in for a timed event like so:

@Kroll.method
public void startTimedEvent(String name, KrollFunction callback) {
  String id = EmbeddedAgent.startTimedEvent(name);
  HashMap map = new HashMap();
  map.put("id", id);
  callback.call(getKrollObject(), map);
}

This results in a JavaScript call like so:

agent.startTimedEvent("openCrust 2.0.27", function(result) {
  var id = result['id'];
  openCrust({});
  agent.endTimedEvent(id);
});

In iOS land, invoking a callback is a bit different, but certainly as easy. The same timedEvent JavaScript method that takes a callback to be wrapped by the timed event can be implemented as follows:

- (void)timedEvent:(id)args
{
  NSString* eventName = [args objectAtIndex:0];
  NSString* eventID = [EmbeddedAgent startTimedEvent:eventName];
  KrollCallback* callback = [args objectAtIndex:1];
  if(callback){
    [callback call:nil thisObject:nil];
  }
  [EmbeddedAgent endTimedEvent:eventID];
}

In this case, I’m using the KrollCallback type, which appears to be analogous to Appcelerator’s Android KrollFunction.
If you need to pass values to a corresponding JavaScript function, they need to be in NSArray form, thus, you can do something like this to pass in parameters to the underlying JavaScript function:

- (void)startTimedEvent:(id)args
{
  NSString* eventName = [args objectAtIndex:0];
  NSString* eventID = [EmbeddedAgent startTimedEvent:eventName];
  KrollCallback* callback = [args objectAtIndex:1];
  if(callback){
    NSDictionary* dict = [[[NSDictionary alloc] initWithObjectsAndKeys:@"id", eventID, nil] autorelease];
    NSArray* array = [NSArray arrayWithObjects: dict, nil];
    [callback call:array thisObject:nil];
  }
}

As you can see in the above code, a callback instance takes as a parameter an NSArray, thus, I have to covert my NSDictionary into an array via Objective-C’s handy arrayWithObjects function.
The default module examples provided by Appcelerator naturally work, but alas, the non-callback style of invocation was less than appealing, especially if you are going to be coding an Appcelerator app in JavaScript. Nevertheless, you can do it easily enough provided you are willing to dig through myriad repositories…or you could save yourself the headache and read this blog post.