README.md

GoldenGate

GoldenGate is an Android annotation processor for generating type safe javascript bindings (Bridges). The library is very similar in usage to something like retrofit in that only an interface has to be declared and annotated (though retrofit does not do any compile time code generating). This annotated interface is at compile time used to generate an type safe wrapper around a webview for interfacing with the javascript.

Installation

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'com.neenbedankt.gradle.plugins:android-apt:1.4'
    }
}

apply plugin: 'com.neenbedankt.android-apt'

dependencies {
    apt 'com.flipboard:goldengate-compiler:1.4.2'
    compile 'com.flipboard:goldengate-api:1.4.2'
}

Usage

Before starting you will need to configure how object should be serialized to json. By default GoldenGate will use gson but does not package this dependency in case you would like to use something else. If you want to use gson add it as a dependency to your build.gradle.

dependencies {
    compile 'com.google.code.gson:gson:x.x.x'
}

If you would like to use some other library like jackson or maybe a custom json implementation you can register a JsonSerializer with JavascriptBridge.

JavaScriptBridge.setJsonSerializer(new JsonSerializer(){
    @Override
    <T> String toJson(T stuff) {
        // do stuff
    }

    @Override
    <T> T fromJson(String json, Class<T> type) {
        // do stuff
    }
});

Start by creating an interface and annotate it with @Bridge and also add a method which you want to call in javascript.

@Bridge
interface MyJavascript {
	void alert(String message);
}

This will automatically generate a class called MyJavascriptBridge which is the implementation which wraps a webview and implements the interface we just defined. Now we have a compile time checked type safe way of opening a javascript alert.

Webview webview = ...;
MyJavascript bridge = new MyJavascriptBridge(webview);
bridge.alert("Hi there!");

The above example is just a fire and forget example. We often want to get some result back. For this we have Callback<T>, because javascript runs asynchronously we can't just return this value and must therefor use a callback. The callback argument must allways be the argument specified last in the method decleration. Here is an example of using Callback<T>.

@Bridge
interface MyJavascript {
	void calculateSomeValue(Callback<Integer> value);
}

Webview webview = ...;
MyJavascript bridge = new MyJavascriptBridge(webview);
bridge.calculateSomeValue(new Callback<Integer>() {
	@Override
	void onResult(Integer result) {
		// do something with result
	}
});

That's it for simple usage! There are two other annotations for customized usage, @Method and @Property. @Method can be used to override the name of the method on the javascript side of the bridge (The java name of the method is automatically chosen if this annotation is not supplied).

@Bridge
interface MyJavascript {
	@Method("console.Log")
	void alert(String message);
}

The @Property annotation should be used for when setting or getting a property on the javascript side of things. In this case the method may only have one parameter (either a callback for result or a value which should be set). Just like with the @Method declaration a custom name can be chosen for the property. The default name for properties however is the name of the parameter to the method.

@Bridge
interface MyJavascript {
	@Property("window.innerHeight")
	void getWindowHeight(Callback<Integer> height);
}

The @JavascriptCallback annotation should be used on method parameters of type Callback which will be passed to javascript as a javascript callback. This allows javascript functions to call back into your java code with a result at a later time, perhaps after a network request has finished.

@Bridge
interface MyJavascript {
    @Method("[1,2,3,4,5,6,7,8,9,10].forEach")
    void looptyLoop(@JavascriptCallback Callback<Integer> val);
}

And lastly if things aren't working as expected there is a @Debug annotation that can be added to your @Bridge annotated interface which will cause the javascript being executed to be logged to the console beforehand.

@Debug
@Bridge
interface MyJavascript {
	void alert(String message);
}

Proguard

If you use Proguard, you'll want to make sure you add the following to your config

# GoldenGate
-keep class * extends com.flipboard.goldengate.JavaScriptBridge { *; }
-keepattributes JavascriptInterface
-keepclassmembers class ** {
    @android.webkit.JavascriptInterface public *;
}

Contributing

We welcome pull requests for bug fixes, new features, and improvements to GoldenGate. Contributors to the main GoldenGate repository must accept Flipboard's Apache-style Individual Contributor License Agreement (CLA) before any changes can be merged.