Using Native Libraries in NativeScript

native_libs_header

NativeScript provides what I consider to be the greatest feature that any mobile framework can provide – the ability to reuse native libraries in your app. The best part is that it’s not even that difficult.

I’ve found the most efficient approach is to use Gradle for Android and CocoaPods for iOS apps. You can also reuse native code that is not available to download/install via Gradle or CocoaPods. The NativeScript site goes into very good detail on how to do this:

Knowing that we can use a native library to achieve something with NativeScript, let’s see just how easy it is to integrate one. In this post, I’ll explore how to integrate an open-source Android native library.

Finding Libraries

I usually go hunting on Android Arsenal – you can find some amazing open source libraries in the catalog.

The other day I was looking for something simple and fun to work on. I love animations, so I searched for animation libraries and came across SmallBang. This library provides a nice animation mocking the Twitter heart “fireworks” animation for ‘favoriting’ tweets.

SmallBang

Pretty sweet, right? Yeah, I thought it was awesome. NativeScript does provide a nice Animation API and it’s definitely possible to create this with the the NativeScript Animation API, but the SmallBang library was perfect for my use case.

Getting Started

Now that you have a library selected, check out the public repo on GitHub. You’ll find a link to the repo on the library’s page on Android Arsenal.

Thankfully, the developer who created SmallBang took the time to write up a very nice README. I encourage everyone to write nice documentation for any open source project – projects with good documentation will always have a better adoption rate than those without.

If you’re following along with the README for this library, you’ll notice the section under the Usage heading says to add the following to your build.gradle file:

dependencies {
     compile 'hanks.xyz:smallbang-library:0.1.2'
}

This is the information you’ll need to pull this library using your build.gradle file within your NativeScript application. Do that first – create a new project from the command prompt/terminal by executing the following, then path into your new app, and add the Android platform.

tns create smallbangApp
cd smallbangApp
tns platform add android

Next, make sure to add the library to your build.gradle file so that you have access to this library when you start running your app. Open up your editor/IDE and find the build.gradle file, in this example, it’s located at smallbangApp/platforms/android/. Once this file is open, scroll down to around line 160 and you’ll notice some dependencies already added, NativeScript includes these in the apps by default. So right beneath the last compile"......." line add the SmallBang dependency from earlier – compile "hanks.xyz:smallbang-library:0.1.2".

Don’t Be Intimidated

I’d like to take this time to point out that I’ve never built a native Android application, and, before working with NativeScript, I was intimidated by everything I’ve mentioned in this article. So I understand if you’re a little hesitant about using Java, Gradle, and the native Android SDKS/APIs. However, once you start working on it, try some things, and ultimately have your app crash – time after time – it will all start to make sense and you will at least have a sense of direction when looking at Java code and the Android SDKs.

Diving Into The Code

The documentation for SmallBang gives us pretty simple instructions to run the animation in two steps.

  1. Initialize SmallBang;

  2. Animate to view.

Step 1

Here is step one in Java:

mSmallBang = SmallBang.attach2Window(this);

Since this is Java code and you can’t just copy and paste this into your app and expect it to work. In order make this work within your NativeScript app, you have to handle it differently.

mSmallBang is the variable and it’s set to an instance of the library SmallBang that is returned via the attach2Window() method. At this point, you need to go look at the source code to find the attach2Window() method.

Once you open the source code, take note that this is within the Java package xyz.hanks.library – you will need this, so make note of it. Scroll down to the attach2Window() method to determine what the this is that you need to pass, so you can make the correct call from your JavaScript. The method is expecting an Activity. Thankfully, NativeScript provides a lot of modules that abstract many things for you to easily access in your JavaScript code.

The application module is what you’ll need. So you’ll need to require("application") first in order to have access to the application module in your JavaScript file from which you’ll get the activity to pass into the native attach2Window() method.

At this point you can convert the library’s Java example code into JavaScript for your NativeScript app:

var mSmallBang = new xyz.hanks.library.SmallBang.attach2Window(app.android.foregroundActivity);

Step 2

Step two in Java looks like:

mSmallBang.bang(view);

You are referencing the mSmallBang variable from the first step and calling bang(view) to trigger the animation. Okay that’s simple. In fact, your JavaScript code would be the same, but what is the view you need to pass?

Well in Android almost everything visible on the screen in your app is considered a “View” and inherits from the android.view.view class. For now, just copy the code and when you want to execute the animation with bang(), you just need to remember to pass in a native Android view/element and everything should work fine (you’ll see how in a moment).

Go to the main-page.xml of your app and change it to the following:

<Page xmlns="http://schemas.nativescript.org/tns.xsd" loaded="pageLoaded">
    <StackLayout>
        <button text="This" tap="bangThis" margin="10" />
        <label text="LIKE" class="tiny" tap="bangThis" margin="10" />
    </StackLayout>
</Page>

You now have a simple page with two views/elements on it: a button and a label. They both reference the same tap function, so you’ll need to define this function to create the animation.

Open your main-page.js file and change it to the following:

var app = require("application");
var platformModule = require("platform");

function bangThis(args) {
  var mSmallBang = new xyz.hanks.library.SmallBang.attach2Window(app.android.foregroundActivity);
  mSmallBang.bang(args.object.android);
}
exports.bangThis = bangThis;

In the bangThis function, you’ll see the code from earlier that you converted from Java to Javascript. Now when you run the app and click the button or label it will trigger the animation. If you aren’t familiar with the tap event on views in NativeScript, args contains the EventData from the view/element, which let’s you easily get the native component by calling args.object.android (or on iOS it’s args.object.ios). Since this library is expecting a native Android view, you need to use args.object.android as your view argument to the bang() method.

Run The Code

Go back to your command line/terminal and run the app, making sure you have a device connected or an emulator ready.

tns run android

If all went well, you should be able to click on the button and label in your app and see the animation.

NativeScript TwitterBang

Conclusion

I hope this has shown just how easy it is to reuse an existing Android library with NativeScript. I liked the animation so much that I went ahead and made a plugin for it. Converting code like this into a plugin is a great way to make it reusable and abstract away some of the different platform specific code necessary to use libraries. If you’d like to reuse this animation without going through these steps over and over with every app you make, you can find the plugin here.

Comments