Merge pull request #1598 from NativeScript/trifonov/gradle-hooks

docs(android): add gradle hooks page

Author: tsonevn

docs/core-concepts/android-runtime/advanced-topics/V8-heap-snapshots.md

@@ -2,7 +2,7 @@
 nav-title: "V8 Heap Snapshot"
 title: "V8 Heap Snapshot"
 description: "Using V8 heap snapshots with the Android Runtime"
-position: 3
+position: 7
 ---
 
 # Deprecated

docs/core-concepts/android-runtime/advanced-topics/custom-flags.md

@@ -1,7 +1,7 @@
 ---
 title: "Custom Flags"
 description: "Configure various V8 engine flags in order to improve the performance of your app, or to obtain more comprehensive information during debugging"
-position: 5
+position: 4
 previous_url: /core-concepts/android-runtime/advanced-topics/v8-flags
 slug: android-custom-flags
 ---

docs/core-concepts/android-runtime/advanced-topics/debug-android-runtime.md

@@ -1,7 +1,7 @@
 ---
 title: Debugging the Android Runtime within your app's Android Studio project
 description: Add the Android Runtime library module to an existing app
-position: 0
+position: 6
 slug: debug-android-runtime
 ---
 
@@ -21,15 +21,15 @@ In certain scenarios where runtime errors occur, the debug info provided by the
 
 ### 1. Create a new NativeScript application using one of the following commands depending on your language/technology preference:
 
-NativeScript with Angular: 
+NativeScript with Angular:
 
 `tns create debug-android-runtime --ng`
 
-NativeScript with TypeScript: 
+NativeScript with TypeScript:
 
 `tns create debug-android-runtime --tsc`
 
-NativeScript with plain JavaScript: 
+NativeScript with plain JavaScript:
 
 `tns create debug-android-runtime`
 
@@ -116,7 +116,7 @@ The symbols can be found in the cloned android runtime repo in: `<android-runtim
 
 ![Set CPP Breakpoint](set-cpp-runtime-breakpoint.png)
 
-* Run Debug 
+* Run Debug
 
 ![Run In Debug](hit-debug.png)
 

docs/core-concepts/android-runtime/advanced-topics/execution-flow.md

@@ -2,91 +2,91 @@
 nav-title: "Execution Flow"
 title: "Execution Flow"
 description: "NativeScript Android Runtime Execution Flow"
-position: 1
+position: 0
 ---
 
 # Application Workflow
 
-Android Runtime 
+Android Runtime
 ---
 _Disclaimer: The author of this article assumes that you are familiar with the core concepts of [NativeScript](http://docs.nativescript.org/) and the [NativeScript Android Runtime](../overview.md)_
 
 The Android Runtime is built on top of **[Google's V8 JavaScript Virtual Machine](#googles-v8)**. Pre-generated **[Metadata](#metadata-generator)** is embedded in the resulting application and as a result we get very efficient native access, while the **[Binding Generator](#binding-generator)** component takes care of the creation of custom Java classes build-time to extend Java/Android class functionality or serve as proxy.
- 
+
 ---
- 
+
 ## Google's V8
  V8 is the JavaScript Engine which compiles and executes the JavaScript code. It takes advantage of the [Just-In-Time Compilation technique](http://whatis.techtarget.com/definition/just-in-time-compiler-JIT) to process JavaScript code with great efficiency. [Read more.](https://developers.google.com/v8/)
- 
+
 ## JNI
  JNI is the **Java Native Interface** that provides means for Java code to interact with native code. Put shortly - it allows a Java program to invoke functions in another C/C++ program and vice versa. In the context of a NativeScript application JNI is the communicational layer between the V8 JavaScript Engine and the platform - Java/Android code. [Read more.](http://developer.android.com/training/articles/perf-jni.html)
- 
-## Metadata Generator 
+
+## Metadata Generator
  The [Metadata Generator](../metadata/overview.md) uses Apache Commons BCEL to iterate through all native dependencies added to the project, and exposes their public API to the Android Runtime.
-     
+
 ## Bindings Generator
  The [Bindings Generator](../generator/overview.md) is responsible for the dynamic generation of implemented classes and interfaces. When the user implements an Android object, a custom Java proxy object is created. The process of generating Java classes at build-time is highly optimized.
- 
+
 ---
- 
-# Application Workflow 
+
+# Application Workflow
  Much like in a Node.js application, a NativeScript application needs a virtual machine that understands the JavaScript code we write. Google's V8 parses JavaScript already, but would not know of Java syntax or objects. That is why pre-generated metadata is necessary. The Metadata Generator creates binaries of all Android types at build-time, that will later be consumed by the Android Runtime and exposed to JavaScript. But JavaScript and Java are two entirely different programming languages with no means to communicate directly. The Android Runtime uses JNI to bridge the gap between V8 and Android's Dalvik, allowing the two to send instructions back and forth despite their discrepancies where data types and objects are concerned.
- 
+
  Let's look at an example where, much like in JavaScript, we can write an event and attach it to a view (button) to respond to user's actions.
- 
+
 ```javascript
  // ... code omitted for brevity
- 
+
  var Color = android.graphics.Color; // 1
  var colors = [Color.BLUE, Color.RED, Color.MAGENTA, Color.YELLOW, Color.parseColor("#FF7F50")] // 2
  var taps = 0;
- 
+
  var button = new android.widget.Button(this); // 3
  button.setText("Hit me"); // 4
  layout.addView(button);
- 
+
  button.setOnClickListener(new android.view.View.OnClickListener({ // 5
     onClick:  function() {
     	button.setBackgroundColor(colors[taps % colors.length]);
     	taps++;
  }}));
-            
+
  // ... code omitted for brevity
 ```
- 
+
 In plain* JavaScript in the browser that same code would look like this *(Depending on your choice of framework, if any, some lines may differ):
- 
+
 ```javascript
  var colors = ["#0000FF", "#FF0000", "#FF00FF", "#FFFF00", "#FF7F50"];
  var taps = 0;
- 
- var button = document.createElement("button");        
+
+ var button = document.createElement("button");
  var btnText = document.createTextNode("Hit me");
  button.appendChild(btnText);
  document.body.appendChild(button);
- 
+
  button.addEventListener("click", function() {
     button.style.background = colors[taps % colors.length];
     taps++;
  });
 ```
- 
+
 And now let's go through the steps of exactly what happens when we write the above:
- 
+
  1. We access a native [Class](https://docs.oracle.com/javase/tutorial/java/concepts/class.html) through JavaScript and save it to a variable for the purposes of writing shorter code later. From here on we can call any of the class Color's public static methods, access its public fields and constants, or make an instance of it, if a public constructor is present. On the following line we save the [constants' values](http://developer.android.com/reference/android/graphics/Color.html) in an array, as they have different representations than in JavaScript.
  2. As mentioned above, we get access to a [Class object](https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html)'s methods, and we take advantage of that to produce another color that was not in the predefined values of the class.
  3. We create a new instance of an Android button. In normal scenarios of writing JavaScript none of it would make sense, but in the context of NativeScript that is a totally valid syntax, and will in fact work and create a button for us. Similar to how we handled colors earlier, we can save the Button class in a variable and use it to make a Button instance - `var Button = android.widget.Button; var button = new Button(this);`. This not only creates an object in JavaScript, but in Android as well. What this means is that any changes made to the object using the relevant API will be reflected on the button that will appear on the screen of your device.
  4. We then proceed to set the button instance's text to a string. A marshalling service will take care of converting any arguments passed to functions to their respective data type representation in the Java world, in our case - JavaScript `string` to Java `java.lang.String`. The button's content will be changed to "Hit me".
  5. Finally, we add event listener to our button. Again, similar to the way we do it in JavaScript, we need to provide a callback that will be executed when an action - a click, hold, load, etc., occurs. The way this is done using the NativeScript Android Runtime is by passing our button instance's method `setOnClickListener` an argument which contains the callback implementation.
 
 ---
- 
+
 # Execution Flow Illustration
 Now that we know how to access the native API, let's have a look at the common execution flow of an application written in NativeScript.
-Triggering an event in Android will always be handled by the Dalvik Virtual Machine ([ART](https://en.wikipedia.org/wiki/Android_Runtime)) which acts as the first responder in a native application. Any implementation included in the body of the event will then be executed by the NativeScript Android runtime, and the result of the operation returned to JavaScript. If a change to a native variable or view is made, instructions will again go through Dalvik. 
+Triggering an event in Android will always be handled by the Dalvik Virtual Machine ([ART](https://en.wikipedia.org/wiki/Android_Runtime)) which acts as the first responder in a native application. Any implementation included in the body of the event will then be executed by the NativeScript Android runtime, and the result of the operation returned to JavaScript. If a change to a native variable or view is made, instructions will again go through Dalvik.
 
 **Note**: If no changes to native variables are present as a result of the execution of the callback (for example, when a local JavaScript variable that doesnt hold a reference to an Android object is modified - a number, a string, an array of JavaScript Objects, etc.), no calls to Dalvik will be made.
- 
+
 Execution Flow illustration:
 ![How a NativeScript program's execution flow looks like on Android devices](app_process.png)
 

docs/core-concepts/android-runtime/advanced-topics/extend-application-activity.md

@@ -2,11 +2,11 @@
 nav-title: "Extending Application and Activity"
 title: "Extending Application and Activity"
 description: "Extending Application and Activity for Android"
-position: 2
+position: 1
 ---
 
 # Extending Application and Activity
-This article describes how to create custom `android.app.Application` and `android.support.v7.app.AppCompatActivity` implementations in a NativeScript application. 
+This article describes how to create custom `android.app.Application` and `android.support.v7.app.AppCompatActivity` implementations in a NativeScript application.
 
 > **Note**: Demo code below is taken from the Android Extend demos for [plain JavaScript](https://github.com/NativeScript/nativescript-dev-webpack/blob/master/demo/JavaScriptApp/app/activity.android.js), [TypeScript](https://github.com/NativeScript/nativescript-dev-webpack/blob/master/demo/TypeScriptApp/app/activity.android.ts) or [Angular](https://github.com/NativeScript/nativescript-dev-webpack/blob/master/demo/AngularApp/app/activity.android.ts) applications.
 
@@ -30,11 +30,11 @@ The following steps are needed to create custom native `android.app.Application`
     ```javascript
     const superProto = android.app.Application.prototype;
 
-    // the first parameter of the `extend` call defines the package and the name for the native *.JAVA file generated. 
+    // the first parameter of the `extend` call defines the package and the name for the native *.JAVA file generated.
     android.app.Application.extend("org.myApp.Application", {
         onCreate: function() {
             superProto.onCreate.call(this);
-            
+
             // At this point modules have already been initialized
 
             // Enter custom initialization code here
@@ -47,12 +47,12 @@ The following steps are needed to create custom native `android.app.Application`
     });
     ```
     ```typescript
-    // the `JavaProxy` decorator specifies the package and the name for the native *.JAVA file generated. 
+    // the `JavaProxy` decorator specifies the package and the name for the native *.JAVA file generated.
     @JavaProxy("org.myApp.Application")
     class Application extends android.app.Application {
         public onCreate(): void {
             super.onCreate();
-            
+
             // At this point modules have already been initialized
 
             // Enter custom initialization code here
@@ -152,7 +152,7 @@ The core modules ship with a default `android.support.v7.app.AppCompatActivity`
         public isNativeScriptActivity;
 
         private _callbacks: AndroidActivityCallbacks;
-        
+
         public onCreate(savedInstanceState: android.os.Bundle): void {
             // Set the isNativeScriptActivity in onCreate (as done in the original NativeScript activity code)
             // The JS constructor might not be called because the activity is created from Android.

docs/core-concepts/android-runtime/advanced-topics/gradle-hooks.md

@@ -0,0 +1,78 @@
+---
+title: "Gradle Hooks"
+description: "Extensibility hooks for the gradle build"
+position: 2
+slug: gradle-hooks
+---
+
+# Gradle Hooks
+
+NativeScript uses gradle to build android applications. The gradle build files are part of the application template that comes from the android runtime package. Sometimes, if you want to use any external plugins or libraries you need to add some code to the gradle files. There are several locations for gradle files that can be used for adding your code. They are applied in the build process in the following order:
+
+`App_Resources/Android/buildscript.gradle`\
+plugins' `buildscript.gradle`\
+`App_Resources/Android/before-plugins.gradle`\
+plugins' `include.gradle`\
+`App_Resources/Android/app.gradle`
+
+## app.gradle
+
+In this file you can set the default Android configurations like `minSdkVersion` and `targetSdkVersion`. You can also add your native dependencies here. In most of the cases, this is the file which you should use when you need to add some gradle code in your application. The reason for applying `app.gradle` last is that it should be able to override any properties or settings that any plugin might have set.
+
+```Groovy
+android {
+  defaultConfig {
+    minSdkVersion 17
+    generatedDensities = []
+  }
+  aaptOptions {
+    additionalParameters "--no-version-vectors"
+  }
+}
+dependencies {
+  implementation 'com.android.support:recyclerview-v7:+'
+}
+```
+
+## Plugins' include.gradle
+
+Every NativeScript plugin, which contains native Android dependencies, should also provide a valid `include.gradle` file located in the root of its `platforms/android` directory. This `include.gradle` file must meet the following requirements:
+
+* It must contain its own [configuration](http://developer.android.com/tools/building/configuring-gradle.html).
+* It may contain native dependencies required to build the plugin properly.
+* Any native dependencies should be available in [jcenter](https://bintray.com/bintray/jcenter) or in the Android SDK installed on your machine, if you want it to work out of the box. You can see an example of a compile dependency [here](https://github.com/NativeScript/nativescript-fresco/blob/master/platforms/android/include.gradle).
+
+This file can be used for many kinds of native project configuration, depending on the purpose of the plugin. You can find more information [here](http://developer.android.com/tools/building/configuring-gradle.html)
+
+```Groovy
+// optional elements
+dependencies {
+    compile "groupName:pluginName:ver"
+}
+```
+
+## before-plugins.gradle
+
+Sometimes you need to change something right before the execution of all the `include.gradle` files of your project's plugins. An example is setting `googlePlayServicesVersion` when you use **nativescript-google-maps-sdk** plugin. If you set the value with the following code in the `app.gradle` file:
+
+```Groovy
+ext {
+  googlePlayServicesVersion = "10.0.1"
+}
+```
+it will be too late for the plugin to receive it, as all plugins' `include.gradle`s will have been applied beforehand. So, the correct place to set this property will be in `before-plugins.gradle` instead.
+
+## buildscript.gradle
+
+When using a plugin like [this one](https://docs.embrace.io/docs/android-integration-guide) there are some **buildscript** configurations which need to be added in the application's **build.gradle** file. Unfortunately this cannot be achieved through the `app.gradle` file nor through plugin's `include.gradle` files. They are being applied too late in the build process and the changes in the **buildscript** do not have any effect.
+In this case a `buildscript.gradle` file needs to be used. These files can be placed either in `App_Resources/Android` folder in the NativeScript application, or in the `platforms/android` folder of a plugin. All such files will be applied to the **buildscript** of the application's `build.gradle`.
+
+```Gradle
+repositories {
+    google()
+    jcenter()
+}
+dependencies {
+    classpath 'embrace-io:embrace-swazzler:3.1.6'
+}
+```

docs/core-concepts/android-runtime/advanced-topics/marking-mode-none.md

@@ -1,7 +1,7 @@
 ---
 title: "Optimizing Performance Using markingMode: none"
 description: "How to enable markingMode:none in your NativeScript mobile app and prevent potential problems"
-position: 4
+position: 3
 slug: marking-mode-none
 ---
 
@@ -13,7 +13,7 @@ The code inside `tns-core-modules` and all plugins published by the NativeScript
 
 ## Benefits and drawbacks of using markingMode: none
 
-The biggest benefit of setting `markingMode` to `none` is a more responsive app – an app that does not slow down if you use it for an extended amount of time. 
+The biggest benefit of setting `markingMode` to `none` is a more responsive app – an app that does not slow down if you use it for an extended amount of time.
 The main drawbacks are:
 - It is up to the plugin developer to manage the plugin-related memory correctly. There might be plugins that do not support the feature and could crash the app with a "cleared reference" exception.
 - It is up to the app developer to manage the app memory correctly. The app code itself might also need to be updated in order to keep JS object references and prevent unwanted collection.
@@ -29,7 +29,7 @@ First, to instruct any app to use this feature we need to add the following in t
 ```
 If the app behaves correctly after this change - great. Sometimes, however, some sporadic errors/crashes occur, especially related to memory management, like any of the following:
 - `Error: com.tns.NativeScriptException: Attempt to use cleared object reference id=<some-object-id-number>`
-- `The JavaScript instance no longer has available Java instance counterpart`  
+- `The JavaScript instance no longer has available Java instance counterpart`
 
 In such cases additional work has to be done. Have in mind the problem could be either in the app code, or in some plugin(s) used by the app. In both cases the resolution is identical.
 
@@ -45,7 +45,7 @@ var callback = new android.native.NCallback({           // native interface
 android.native.Executor.printWithDelay(callback, 3s);
 ```
 
-The implementor is enclosed by the callback implementation, but with `markingMode: none` enabled the framework no longer takes care of finding out that connection. So, when GC happens in V8 or in Android the `implementor` instance (or its native representation) is GC'ed. This can result in either Java or JavaScript instance missing and upon calling of the `callback` an "Attempt to use cleared object reference" or "JavaScript instance no longer has available Java counterpart" error is very likely to occur. 
+The implementor is enclosed by the callback implementation, but with `markingMode: none` enabled the framework no longer takes care of finding out that connection. So, when GC happens in V8 or in Android the `implementor` instance (or its native representation) is GC'ed. This can result in either Java or JavaScript instance missing and upon calling of the `callback` an "Attempt to use cleared object reference" or "JavaScript instance no longer has available Java counterpart" error is very likely to occur.
 
 ### Solution
 

docs/core-concepts/android-runtime/advanced-topics/memory-management.md

@@ -1,7 +1,7 @@
 ---
 title: "Memory Management"
 description: "Best practices and recommendations on how to improve the performance of your NativeScript mobile app by tuning the memory management"
-position: 4
+position: 5
 slug: android-memory-management
 ---