From b78cb18065a63b9517c3e26d2ea79c4417474772 Mon Sep 17 00:00:00 2001 From: darryncampbell Date: Tue, 18 Apr 2017 09:43:49 +0100 Subject: [PATCH] Tidied code and updated readme --- README.md | 237 +++++++++++++++++++++++++++++++++++- package.json | 2 +- plugin.xml | 3 - src/android/IntentShim.java | 11 -- www/IntentShim.js | 35 ++---- 5 files changed, 247 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index b4e47f5..56c34fc 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,234 @@ -# Under Development -# darryncampbell-cordova-plugin-intent -General purpose intent shim layer for cordova appliations on Android. Handles various techniques for sending and receiving intents. +*This plugin is provided without guarantee or warranty* +========================================================= + +[![npm version](http://img.shields.io/npm/v/com-darryncampbell-cordova-plugin-intent.svg?style=flat-square)](https://npmjs.org/package/com-darryncampbell-cordova-plugin-intent "View this project on npm") +[![npm downloads](http://img.shields.io/npm/dm/com-darryncampbell-cordova-plugin-intent.svg?style=flat-square)](https://npmjs.org/package/com-darryncampbell-cordova-plugin-intent "View this project on npm") +[![npm downloads](http://img.shields.io/npm/dt/com-darryncampbell-cordova-plugin-intent.svg?style=flat-square)](https://npmjs.org/package/com-darryncampbell-cordova-plugin-intent "View this project on npm") +[![npm licence](http://img.shields.io/npm/l/com-darryncampbell-cordova-plugin-intent.svg?style=flat-square)](https://npmjs.org/package/com-darryncampbell-cordova-plugin-intent "View this project on npm") + +# Overview +This Cordova plugin provides a general purpose shim layer for the Android intent mechanism, exposing various ways to handle sending and receiving intents. + +## Credits +This project uses code released under the following MIT projects: +- https://github.com/napolitano/cordova-plugin-intent (marked as no longer maintained) +- https://github.com/Initsogar/cordova-webintent.git (no longer available on github but the project is forked here: https://github.com/darryncampbell/cordova-webintent) +This project is also released under MIT. Credit is given in the code where appropriate + +## IntentShim +This plugin defines a `window.plugins.intentShim` object which provides an API for interacting with the Android intent mechanism on any Android device. + +## Testing / Example +An example application is available at https://github.com/darryncampbell/plugin-intent-api-exerciser to demonstrate the API and can be used to test the functionality. + +## Installation + cordova plugin add https://github.com/darryncampbell/darryncampbell-cordova-plugin-intent.git + +## Supported Platforms +- Android + +## intentShim.registerBroadcastReceiver + +Registers a broadcast receiver for the specified filters + + window.plugins.intentShim.registerBroadcastReceiver(filters, callback); + +### Description + +The `intentShim.registerBroadcastReceiver` function registers a dynamic broadcast receiver for the specified list of filters and invokes the specified callback when any of those filters are received + +### Android Quirks + +Any existing broadcast receiver is unregistered when this method is called. To register for multiple types of broadcast, specify multiple filters. + +### Example + +Register a broadcast receiver for two filters: + + window.plugins.intentShim.registerBroadcastReceiver({ + filterActions: [ + 'com.darryncampbell.cordova.plugin.broadcastIntent.ACTION', + 'com.darryncampbell.cordova.plugin.broadcastIntent.ACTION_2' + ] + }, + function(intent) { + console.log('Received broadcast intent: ' + JSON.stringify(intent.extras)); + } + ); + + +## intentShim.unregisterBroadcastReceiver + +Unregisters the broadcast receiver + + window.plugins.intentShim.unregisterBroadcastReceiver(); + +### Description + +The `intentShim.unregisterBroadcastReceiver` function unregisters the broadcast receiver registered with `intentShim.registerBroadcastReceiver(filters, callback);`. No further broadcasts will be received for any registered filter after this call. + +### Android Quirks + +The developer is responsible for calling unregister / register when their application goes into the background or comes back to the foreground, if desired. + +### Example + +Unregister the broadcast receiver when the application receives an onPause event: + + bindEvents: function() { + document.addEventListener('pause', this.onPause, false); + }, + onPause: function() + { + window.plugins.intentShim.unregisterBroadcastReceiver(); + } + +## intentShim.sendBroadcast + +Sends a broadcast intent + + window.plugins.intentShim.sendBroadcast(action, extras, successCallback, failureCallback); + +### Description + +The `intentShim.sendBroadcast` function sends an Android broadcast intent with a specified action + +### Example + +Send a broadcast intent to a specified action that contains a random number in the extras + + window.plugins.intentShim.startActivity( + { + action: "com.darryncampbell.cordova.plugin.intent.ACTION", + extras: { + 'random.number': Math.floor((Math.random() * 1000) + 1) + } + }, + function() {}, + function() {alert('Failed to open URL via Android Intent')} + ); + + +## intentShim.onIntent + +Returns the content of the intent used whenever the application activity is launched + + window.plugins.intentShim.onIntent(callback); + +### Description + +The `intentShim.onIntent` function returns the intent which launched the Activity and maps to the Android Activity's onNewIntent() method, https://developer.android.com/reference/android/app/Activity.html#onNewIntent(android.content.Intent). The registered callback is invoked whenever the activity is launched + +### Android Quirks + +By default the android application will be created with launch mode set to 'SingleTop'. If you wish to change this to 'SingleTask' you can do so by modifying `config.xml` as follows: + + + ... + + +See https://www.mobomo.com/2011/06/android-understanding-activity-launchmode/ for more information on the differences between the two. + +### Example + +Registers a callback to be invoked + + window.plugins.intentShim.onIntent(function (intent) { + console.log('Received Intent: ' + JSON.stringify(intent.extras)); + }); + +## intentShim.startActivity + +Starts a new activity using an intent built from action, url, type, extras or some subset of those parameters + + window.plugins.intentShim.startActivity(params, successCallback, failureCallback); + +### Description + +The `intentShim.startActivity` function maps to Android's activity method startActivity, https://developer.android.com/reference/android/app/Activity.html#startActivity(android.content.Intent) to launch a new activity. + +### Android Quirks + +Some common actions are defined as constants in the plugin, see below. + +### Examples + +Launch the maps activity + + window.plugins.intentShim.startActivity( + { + action: window.plugins.intentShim.ACTION_VIEW, + url: 'geo:0,0?q=London' + }, + function() {}, + function() {alert('Failed to open URL via Android Intent')} + ); + +Launch the web browser + + window.plugins.intentShim.startActivity( + { + action: window.plugins.intentShim.ACTION_VIEW, + url: 'http://www.google.co.uk' + }, + function() {}, + function() {alert('Failed to open URL via Android Intent')} + ); + +## intentShim.startActivityForResult + +Starts a new activity and return the result to the application + + window.plugins.intentShim.startActivityForResult(params, resultCallback, failureCallback); + +### Description + +The `intentShim.startActivityForResult` function maps to Android's activity method startActivityForResult, https://developer.android.com/reference/android/app/Activity.html#startActivityForResult(android.content.Intent, int) to launch a new activity and the resulting data is returned via the resultCallback. + +### Android Quirks + +Some common actions are defined as constants in the plugin, see below. + +### Example + +Pick an Android contact + + window.plugins.intentShim.startActivityForResult( + { + action: window.plugins.intentShim.ACTION_PICK, + url: "content://com.android.contacts/contacts", + requestCode: 1 + }, + function(intent) + { + if (intent.extras.requestCode == 1) + { + console.log('Picked contact: ' + intent.data); + } + }, + function() + { + console.log("StartActivityForResult failure"); + }); + + +## Predefined Constants + +The following constants are defined in the plugin for use in JavaScript +- window.plugins.intentShim.ACTION_SEND +- window.plugins.intentShim.ACTION_VIEW +- window.plugins.intentShim.EXTRA_TEXT +- window.plugins.intentShim.EXTRA_SUBJECT +- window.plugins.intentShim.EXTRA_STREAM +- window.plugins.intentShim.EXTRA_EMAIL +- window.plugins.intentShim.ACTION_CALL +- window.plugins.intentShim.ACTION_SENDTO +- window.plugins.intentShim.ACTION_GET_CONTENT +- window.plugins.intentShim.ACTION_PICK + +## Tested Versions + +Tested with Cordova version 6.5.0 and Cordova Android version 6.2.1 + + + diff --git a/package.json b/package.json index 3279641..04e0e9d 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,7 @@ }, "keywords": [ "cordova", - "Intent" + "Intent" ], "author": "Darryn Campbell", "license": "MIT" diff --git a/plugin.xml b/plugin.xml index 06d694a..0fc2b9a 100644 --- a/plugin.xml +++ b/plugin.xml @@ -12,9 +12,6 @@ - - - diff --git a/src/android/IntentShim.java b/src/android/IntentShim.java index 77daccf..7f0ee1b 100644 --- a/src/android/IntentShim.java +++ b/src/android/IntentShim.java @@ -9,11 +9,9 @@ import android.net.Uri; import android.os.Build; import android.os.Bundle; -import android.provider.ContactsContract; import android.text.Html; import android.util.Log; import android.webkit.MimeTypeMap; -import android.widget.Toast; import org.apache.cordova.CallbackContext; import org.apache.cordova.CordovaActivity; @@ -25,13 +23,10 @@ import org.json.JSONObject; import java.lang.reflect.Array; -import java.net.URI; import java.util.Arrays; import java.util.HashMap; import java.util.Map; -import static android.R.attr.filter; - public class IntentShim extends CordovaPlugin { private static final String LOG_TAG = "Cordova Intents Shim"; @@ -54,7 +49,6 @@ public boolean execute(String action, JSONArray args, final CallbackContext call return false; } - // Parse the arguments final CordovaResourceApi resourceApi = webView.getResourceApi(); JSONObject obj = args.getJSONObject(0); String type = obj.has("type") ? obj.getString("type") : null; @@ -250,8 +244,6 @@ public void onNewIntent(Intent intent) { } } - - @Override public void onActivityResult(int requestCode, int resultCode, Intent intent) { @@ -288,7 +280,6 @@ public void onReceive(Context context, Intent intent) { * Return JSON representation of intent attributes * * @param intent - * @return * Credit: https://github.com/napolitano/cordova-plugin-intent */ private JSONObject getIntentJson(Intent intent) { @@ -399,8 +390,6 @@ private static Object toJsonValue(final Object value) throws JSONException { return String.valueOf(value); } } - - } diff --git a/www/IntentShim.js b/www/IntentShim.js index d2f9974..a75921d 100644 --- a/www/IntentShim.js +++ b/www/IntentShim.js @@ -1,4 +1,3 @@ - var argscheck = require('cordova/argscheck'), channel = require('cordova/channel'), utils = require('cordova/utils'), @@ -7,31 +6,25 @@ var argscheck = require('cordova/argscheck'), /** - * This represents the mobile device, and provides properties for inspecting the model, version, UUID of the - * phone, etc. + * This represents a thin shim layer over the Android Intent implementation * @constructor */ function IntentShim() { - this.available = false; var me = this; } - IntentShim.prototype.ACTION_SEND = "android.intent.action.SEND"; - IntentShim.prototype.ACTION_VIEW= "android.intent.action.VIEW"; - IntentShim.prototype.EXTRA_TEXT = "android.intent.extra.TEXT"; - IntentShim.prototype.EXTRA_SUBJECT = "android.intent.extra.SUBJECT"; - IntentShim.prototype.EXTRA_STREAM = "android.intent.extra.STREAM"; - IntentShim.prototype.EXTRA_EMAIL = "android.intent.extra.EMAIL"; - IntentShim.prototype.ACTION_CALL = "android.intent.action.CALL"; - IntentShim.prototype.ACTION_SENDTO = "android.intent.action.SENDTO"; - // StartActivityForResult - IntentShim.prototype.ACTION_GET_CONTENT = "android.intent.action.GET_CONTENT"; - IntentShim.prototype.ACTION_PICK = "android.intent.action.PICK"; +IntentShim.prototype.ACTION_SEND = "android.intent.action.SEND"; +IntentShim.prototype.ACTION_VIEW= "android.intent.action.VIEW"; +IntentShim.prototype.EXTRA_TEXT = "android.intent.extra.TEXT"; +IntentShim.prototype.EXTRA_SUBJECT = "android.intent.extra.SUBJECT"; +IntentShim.prototype.EXTRA_STREAM = "android.intent.extra.STREAM"; +IntentShim.prototype.EXTRA_EMAIL = "android.intent.extra.EMAIL"; +IntentShim.prototype.ACTION_CALL = "android.intent.action.CALL"; +IntentShim.prototype.ACTION_SENDTO = "android.intent.action.SENDTO"; +// StartActivityForResult +IntentShim.prototype.ACTION_GET_CONTENT = "android.intent.action.GET_CONTENT"; +IntentShim.prototype.ACTION_PICK = "android.intent.action.PICK"; -/** - * @param {Function} successCallback The function to call when the heading data is available - * @param {Function} errorCallback The function to call when there is an error getting the heading data. (OPTIONAL) - */ IntentShim.prototype.startActivity = function(params, successCallback, errorCallback) { argscheck.checkArgs('off', 'IntentShim.startActivity', arguments); exec(successCallback, errorCallback, "IntentShim", "startActivity", [params]); @@ -72,10 +65,6 @@ IntentShim.prototype.onActivityResult = function(callback) { exec(callback, null, "IntentShim", "onActivityResult", [callback]); }; - - - -//module.exports = new IntentShim(); window.intentShim = new IntentShim(); window.plugins = window.plugins || {}; window.plugins.intentShim = window.intentShim;