Issue 4399 - Add WebView inheritor with ad blocking

README.md

 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
 -------------------------
 
 Adblock Plus Library for Android has dependencies that aren't in this repository.
 To update those, call:
 
     ./ensure_dependencies.py
 
 ## Library
@@ skipping 23 matching lines @@
 -------------------
 
 ### Requirements
 
 All 'Building with Ant' requirements and additional requirements:
 
 * [Maven](https://maven.apache.org)
 
 ### 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
 -----------------------------------
 
 ### Requirements
 
 * [The Android SDK](http://developer.android.com/sdk)
 * Android SDK Build tools 22.0.1
 * [The Android NDK](https://developer.android.com/tools/sdk/ndk)
 
@@ skipping 61 matching lines @@
 Make sure you've created _local.properties_ file to build the library (see above).
 In the project root directory run:
 
     ./gradlew assembleDebugAndroidTest
 
 This will generate *.apk in 'libadblockplus-android-tests/build/outputs/apk/' directory.
 
 ### 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.