Project Ace - Writing Platform-Specific Code

Writing Platform-Specific Code

Ace’s goal is for you to write as much cross-platform code/UI as possible, whether it’s interacting with HTML or native UI. However, sometimes you can’t avoid writing platform-specific code or using platform-specific UI. Ace provides several mechanisms to make this as easy as possible:

Conditional Logic

At any spot in your code, you can check the current platform and act accordingly:

if (ace.platform == "iOS") {
  var control = new ace.NativeObject("UISegmentedControl");
  ...
}
else if (ace.platform == "Android") {
  var control = new ace.NativeObject("android.widget.RatingBar");
  ...
}
else {
    ...
}

With logic like this, you could load different markup files, programmatically construct different UI, and so on.

In addition to this, the ace.android.ifVersionAtLeast API enables you to perform Android-specific logic conditionally based on the current Android version.

Conditional Markup

Perhaps you have a XAML file that defines an entire page in a cross-platform way, but you have a couple of spots that need to differ based on the current platform. You don’t need to construct separate markup files. Instead, you can use conditional XAML where needed:

<Page>
  <ListBox ... />
  ...
  <if.iOS>
    <ios:UISegmentedControl Name="platformSpecificControl" />
  </if.iOS>
  <if.Android>
    <android:RatingBar Name="platformSpecificControl" />
  </if.Android>
  ...
  <Button ... />
</Page>

A Shortcut for Platform-Specific Values

Sometimes you just need a single value to be different depending on the platform. Rather than writing a cumbersome if/else statement, you can use ace.valueOn. You give this method a set of values, one per platform, and it returns the correct result for the current platform.

var text = ace.valueOn({ ios: "string for iOS", android: "string for Android" });
var margin = ace.valueOn({ ios: 12, android: 20 });

This can be handy when instantiating a native class. Even if you write your own custom native class and give it the same API in Objective-C (for iOS) and Java (for Android), you still should use per-platform class names in JavaScript because the Java class name must be qualified by its package name:

// On iOS, instantiate MyClass, written in Objective-C
// On Android, instantiate my.package.MyClass, written in Java
var obj = new ace.NativeObject({ ios: "MyClass", android: "my.package.MyClass" });

However, for this case, Ace helpfully ignores the package prefix on iOS so you actually can get away with using the same string for both platforms:

// On iOS, ignore "my.package." and instantiate MyClass, written in Objective-C
// On Android, instantiate my.package.MyClass, written in Java
var obj = new ace.NativeObject("my.package.MyClass");

Platform Helpers

Currently, there are only platform-specific helpers for Android. These can be accessed via ace.android, and you can see all the APIs here. The helpers give your code access to the current context, activity, and intent, and enable you to do Android version checking. There are also app widget APIs, an event raised when the intent changes, and a helper for retrieving resource IDs.