Issue 4399 - Add WebView inheritor with ad blocking

README.md

Index: README.md
diff --git a/README.md b/README.md
index ce2d29c550de70be4b3c4cb51557e0fd95199477..9cdb215ff3530a89de7f1614029225f1e203d0cf 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 Adblock Plus Library for Android
 ========================
 
-An Android library project that runs a proxy to block ads.
+An Android library project, tests and demo application for AdblockWebView widget.
 
 Updating the dependencies
 -------------------------
@@ -45,12 +45,19 @@ All 'Building with Ant' requirements and additional requirements:
 
 ### Building
 
+Go to android sdk directory '/platforms/android-21' and run:
+
+    mvn install:install-file -Dfile=./android.jar -DgroupId=com.google.android -DartifactId=android
+     -Dversion=5.0 -Dpackaging=jar -DgeneratePom=true
+
 Set environment variable ANDROID_HOME to your Android SDK directory or pass it in command-line (below).
-In the 'libadblockplus-android' directory run:
+In the root directory run:
 
 	mvn clean install [-Dandroid.sdk.path=/some/where/sdk]
 
-This will generate *.aar library artifact in the 'target' directory. 
+This will generate *.aar library artifacts in the 'libadblockplus-android/target',
+'libadblockplus-android-settings/target', 'libadblockplus-android-webview/target' directories
+and *.apk in 'libadblockplus-android-webviewapp/target' directory.
 
 Building with Gradle/Android Studio
 -----------------------------------
@@ -132,4 +139,187 @@ This will generate *.apk in 'libadblockplus-android-tests/build/outputs/apk/' di
 ### Testing with Gradle/Android Studio
 
 You can select test class/method and click 'Run ..Test'. The library and test app will be
-compiled, installed to emuator/device and launched automatically.
+compiled, installed to emulator/device and launched automatically.
+
+## Settings
+
+You can find adblock fragments in 'libadblockplus-android-settings' directory:
+* AdblockGeneralSettingsFragment - main fragment
+* AdblockWhitelistedDomainsSettingsFragment - whitelisted domains fragment
+
+### Usage
+
+Create `AdblockEngine` instance with factory methods and `AdblockSettingsStorage` instance.
+You can use `AdblockSettingsSharedPrefsStorage` implementation to store settings in `SharedPreferences`.
+Or you can use Adblock facade:
+
+    Adblock.get().init(this, true, Adblock.PREFERENCE_NAME);
+
+Retain
+
+Implement the following interfaces in your settings activity:
+
+* `AdblockGeneralSettingsFragment.Provider`
+* `AdblockGeneralSettingsFragment.Listener`
+* `AdblockWhitelistedDomainsSettingsFragment.Listener`
+
+and return created instance or Adblock facade instances:
+
+    Adblock.get().getEngine();  // engine
+    Adblock.get().getStorage(); // storage
+
+Retain Adblock facade instance in activity `onCreate`:
+
+    Adblock.get().retain();
+
+and release it in `onDestroy`:
+
+    Adblock.get().release();
+
+Insert `AdblockGeneralSettingsFragment` fragment instance in runtime to start showing settings UI.
+
+### Building
+
+Building with Ant
+-----------------

[diegocarloslima, 2016/11/08 16:30:37]

For me it's a bit weird that a subsection has a higher header hierarchy (h2)
than its parent (h3). Here, we can still deduce that 'Building with Ant' is
inside the context of 'Building', but with other titles that could lead to
confusion.

[anton, 2016/11/09 12:30:27]

Acknowledged.

+
+In the 'libadblockplus-android-settings' directory create the file _local.properties_ and set
+_sdk.dir_ to where you installed it, e.g.:
+
+    sdk.dir = /some/where/sdk
+
+Then run:
+
+    ant debug
+
+
+Building with Gradle
+--------------------
+
+In the project root directory run:
+
+    ./gradlew assemble
+
+This will generate *.aar in 'libadblockplus-android-settings/build/outputs/aar' directory.
+
+## WebView Application
+
+You can find demo application for 'AdblockWebView' class in
+'libadblockplus-android-webviewapp' directory.
+
+### Building
+
+Make sure _Library_ requirements are present.
+
+Building with Ant
+-----------------

[diegocarloslima, 2016/11/08 16:30:37]

Same here, 'Building with Ant' and 'Building with Gradle' have higher header
hierarchy than 'Building'

[anton, 2016/11/09 12:30:27]

Acknowledged.

+
+In the 'libadblockplus-android-webviewapp' directory create the file _local.properties_ and set
+_sdk.dir_ to where you installed it, e.g.:
+
+    sdk.dir = /some/where/sdk
+
+Then run:
+
+    ant debug
+
+This will generate *.apk in 'libadblockplus-android-webviewapp/bin/' directory.
+
+Building with Gradle
+--------------------
+
+In the project root directory run:
+
+    ./gradlew assemble
+
+This will generate *.apk in 'libadblockplus-android-webviewapp/build/outputs/apk/' directory.
+
+
+## WebView
+
+You can find 'AdblockWebView' class in 'libadblockplus-android-webview' directory.
+
+`AdblockWebView` class provides built-in ad blocking
+(both resource loading filtering and element hiding) and inherits from Android
+['WebView'](https://developer.android.com/reference/android/webkit/WebView.html).
+
+### Usage
+
+In layout XML:
+
+    <org.adblockplus.libadblockplus.android.webview.AdblockWebView
+        android:id="@+id/main_webview"
+        android:layout_width="match_parent"
+        android:layout_height="match_parent"/>
+
+In java source code:
+
+    AdblockWebView webView = (AdblockWebView) findViewById(R.id.main_webview);
+
+Use `setAdblockEnabled(boolean adblockEnabled)` to enable/disable adblocking.
+
+Use `setDebugMode(boolean debugMode)` to turn debug log output (Android log and JS console) on/off.
+
+Use `setAllowDrawDelay(int allowDrawDelay)` to set custom delay to start render webpage after 'DOMContentLoaded' event is fired.
+
+Use `setAdblockEngine(AdblockEngine adblockEngine)` to use external adblock engine
+If adblock engine is not set, it's created by AdblockWebView instance automatically.
+
+Use `dispose(Runnable disposeFinished)` to release resources (**required**).
+Note it can be invoked from background thread.
+
+### Building
+
+Building with Ant
+-----------------

[diegocarloslima, 2016/11/08 16:30:37]

Same here, 'Building with Ant' and 'Building with Gradle' have higher header
hierarchy than 'Building'

+
+In the 'libadblockplus-android-webview' directory create the file _local.properties_ and set
+_sdk.dir_ to where you installed it, e.g.:
+
+    sdk.dir = /some/where/sdk
+
+Then run:
+
+    ant debug
+
+
+Building with Gradle
+--------------------
+
+In the project root directory run:
+
+    ./gradlew assemble
+
+This will generate *.aar in 'libadblockplus-android-webview/build/outputs/aar' directory.
+
+## WebView Application
+
+You can find demo application for 'AdblockWebView' class in
+'libadblockplus-android-webviewapp' directory.
+
+### Building
+
+Make sure _Library_ requirements are present.
+
+Building with Ant
+-----------------

[diegocarloslima, 2016/11/08 16:30:37]

Same here, 'Building with Ant' and 'Building with Gradle' have higher header
hierarchy than 'Building'

[anton, 2016/11/09 12:30:26]

Acknowledged.

+
+In the 'libadblockplus-android-webviewapp' directory create the file _local.properties_ and set
+_sdk.dir_ to where you installed it, e.g.:
+
+    sdk.dir = /some/where/sdk
+
+Then run:
+
+    ant debug
+
+This will generate *.apk in 'libadblockplus-android-webviewapp/bin/' directory.
+
+Building with Gradle
+--------------------
+
+In the project root directory run:
+
+    ./gradlew assemble
+
+This will generate *.apk in 'libadblockplus-android-webviewapp/build/outputs/apk/' directory.