Initial revamp for the docs. Needs topic links! (1caebe1d) · Commits · codevise / cordova-plugin-adm

CONTRIBUTING.md

+59 −3

Original line number	Diff line number	Diff line
		@@ -8,13 +8,21 @@ We love pull requests from everyone.
		git clone git@github.com:your-username/phonegap-plugin-push.git
		```

		Set up a branch for your feature or bugfix with a link to the original repo:

		```
		git checkout -b my-awesome-new-feature
		git push --set-upstream origin my-awesome-new-feature
		git remote add upstream https://github.com/phonegap/phonegap-plugin-push.git
		```

		Set up the project:

		```
		npm install
		```

		Make sure the tests pass:
		Make sure the tests pass before changing anything:

		```
		npm test
		@@ -26,7 +34,26 @@ Make your change. Add tests for your change. Make the tests pass:
		npm test
		```

		Push to your fork and [submit a pull request](https://help.github.com/articles/creating-a-pull-request/).
		Commit changes:

		```
		git commit -m "Cool stuff"
		```

		Make sure your branch is up to date with the original repo:

		```
		git fetch upstream
		git merge upstream/master
		```

		Review your changes and any possible conflicts and push to your fork:

		```
		git push origin
		```

		[Submit a pull request](https://help.github.com/articles/creating-a-pull-request/).

		At this point you're waiting on us. We do our best to keep on top of all the pull requests. We may suggest some changes, improvements or alternatives.

		@@ -35,3 +62,32 @@ Some things that will increase the chance that your pull request is accepted:
		- Write tests.
		- Write a [good commit message](http://chris.beams.io/posts/git-commit/).
		- Make sure the PR merges cleanly with the latest master.
		- Describe your feature/bugfix and why it's needed/important in the pull request description.


		### Editor Config

		The project uses [.editorconfig](http://editorconfig.org/) to define the coding
		style of each file. We recommend that you install the Editor Config extension
		for your preferred IDE. Consistenty is key.

		### JSHint

		The project uses [.jshint](http://jshint.com/docs) to define the JavaScript
		coding conventions. Most editors now have a JSHint add-on to provide on-save
		or on-edit linting.

		#### Install JSHint for vim

		1. Install [jshint](https://www.npmjs.com/package/jshint).
		1. Install [jshint.vim](https://github.com/wookiehangover/jshint.vim).

		#### Install JSHint for Sublime

		1. Install [Package Control](https://packagecontrol.io/installation)
		1. Restart Sublime
		1. Type `CMD+SHIFT+P`
		1. Type _Install Package_
		1. Type _JSHint Gutter_
		1. Sublime -> Preferences -> Package Settings -> JSHint Gutter
		1. Set `lint_on_load` and `lint_on_save` to `true`

README.md

+12 −690

File changed.

Preview size limit exceeded, changes collapsed.

docs/API.md

0 → 100644

+247 −0

Original line number	Diff line number	Diff line
		# API

		## PushNotification.init(options)

		Initializes the plugin on the native side.

		### Returns

		- Instance of `PushNotification`.

		### Parameters

		Parameter \| Type \| Default \| Description
		--------- \| ---- \| ------- \| -----------
		`options` \| `Object` \| `{}` \| An object describing relevant specific options for all target platforms.

		All available option attributes are described bellow. Currently, there are no Windows specific options.

		#### Android

		Attribute \| Type \| Default \| Description
		--------- \| ---- \| ------- \| -----------
		`android.senderID` \| `string` \| \| Maps to the project number in the Google Developer Console.
		`android.icon` \| `string` \| \| Optional. The name of a drawable resource to use as the small-icon. The name should not include the extension.
		`android.iconColor` \| `string` \| \| Optional. Sets the background color of the small icon on Android 5.0 and greater. [Supported Formats](http://developer.android.com/reference/android/graphics/Color.html#parseColor(java.lang.String))
		`android.sound` \| `boolean` \| `true` \| Optional. If `true` it plays the sound specified in the push data or the default system sound.
		`android.vibrate` \| `boolean` \| `true` \| Optional. If `true` the device vibrates on receipt of notification.
		`android.clearNotifications` \| `boolean` \| `true` \| Optional. If `true` the app clears all pending notifications when it is closed.
		`android.forceShow` \| `boolean` \| `false` \| Optional. If `true` will always show a notification, even when the app is on the foreground.

		#### iOS

		All iOS boolean options can also be specified as `string`

		Attribute \| Type \| Default \| Description
		--------- \| ---- \| ------- \| -----------
		`ios.alert` \| `boolean` \| `false` \| Optional. If `true` the device shows an alert on receipt of notification. Note: the value you set this option to the first time you call the init method will be how the application always acts. Once this is set programmatically in the init method it can only be changed manually by the user in Settings>Notifications>`App Name`. This is normal iOS behaviour.
		`ios.badge` \| `boolean` \| `false` \| Optional. If `true` the device sets the badge number on receipt of notification. Note: the value you set this option to the first time you call the init method will be how the application always acts. Once this is set programmatically in the init method it can only be changed manually by the user in Settings>Notifications>`App Name`. This is normal iOS behaviour.
		`ios.sound` \| `boolean` \| `false` \| Optional. If `true` the device plays a sound on receipt of notification. Note: the value you set this option to the first time you call the init method will be how the application always acts. Once this is set programmatically in the init method it can only be changed manually by the user in Settings>Notifications>`App Name`. This is normal iOS behaviour.
		`ios.clearBadge` \| `boolean` \| `false` \| Optional. If `true` the badge will be cleared on app startup.

		### Example

		```javascript
		var push = PushNotification.init({
		android: {
		senderID: "12345679"
		},
		ios: {
		alert: "true",
		badge: true,
		sound: 'false'
		},
		windows: {}
		});
		```

		## push.on(event, callback)

		### Parameters

		Parameter \| Type \| Default \| Description
		--------- \| ---- \| ------- \| -----------
		`event` \| `string` \| \| Name of the event to listen to. See below for all the event names.
		`callback` \| `Function` \| \| Is called when the event is triggered.

		## push.on('registration', callback)

		The event `registration` will be triggered on each successful registration with the 3rd party push service.

		### Callback parameters

		Parameter \| Type \| Description
		--------- \| ---- \| -----------
		`data.registrationId` \| `string` \| The registration ID provided by the 3rd party remote push service.

		### Example

		```javascript
		push.on('registration', function(data) {
		console.log(data.registrationId);
		});
		```

		## push.on('notification', callback)

		The event `notification` will be triggered each time a push notification is received by a 3rd party push service on the device.

		### Callback parameters

		Parameter \| Type \| Description
		--------- \| ---- \| -----------
		`data.message` \| `string` \| The text of the push message sent from the 3rd party service.
		`data.title` \| `string` \| The optional title of the push message sent from the 3rd party service.
		`data.count` \| `string` \| The number of messages to be displayed in the badge iOS or message count in the notification shade in Android. For windows, it represents the value in the badge notification which could be a number or a status glyph.
		`data.sound` \| `string` \| The name of the sound file to be played upon receipt of the notification.
		`data.image` \| `string` \| The path of the image file to be displayed in the notification.
		`data.additionalData` \| `Object` \| An optional collection of data sent by the 3rd party push service that does not fit in the above properties.
		`data.additionalData.foreground` \| `boolean` \| Whether the notification was received while the app was in the foreground

		### Example

		```javascript
		push.on('notification', function(data) {
		console.log(data.message);
		console.log(data.title);
		console.log(data.count);
		console.log(data.sound);
		console.log(data.image);
		console.log(data.additionalData);
		});
		```

		## push.on('error', callback)

		The event `error` will trigger when an internal error occurs and the cache is aborted.

		### Callback parameters

		Parameter \| Type \| Description
		--------- \| ---- \| -----------
		`e` \| `Error` \| Standard JavaScript error object that describes the error.

		### Example

		```javascript
		push.on('error', function(e) {
		console.log(e.message);
		});
		```

		## push.off(event, callback)

		Removes a previously registered callback for an event.

		### Parameters

		Parameter \| Type \| Default \| Description
		--------- \| ---- \| ------- \| -----------
		`event` \| `string` \| \| Name of the event type. The possible event names are the same as for the `push.on` function.
		`callback` \| `Function` \| \| The same callback used to register with `push.on`.

		### Example
		```javascript
		var callback = function(data){ /.../};

		//Adding handler for notification event
		push.on('notification', callback);

		//Removing handler for notification event
		push.off('notification', callback);
		```

		WARNING: As stated in the example, you will have to store your event handler if you are planning to remove it.

		## push.unregister(successHandler, errorHandler)

		The unregister method is used when the application no longer wants to receive push notifications. Beware that this cleans up all event handlers previously registered, so you will need to re-register them if you want them to function again without an application reload.

		### Parameters

		Parameter \| Type \| Default \| Description
		--------- \| ---- \| ------- \| -----------
		`successHandler` \| `Function` \| \| Is called when the api successfully unregisters.
		`errorHandler` \| `Function` \| \| Is called when the api encounters an error while unregistering.

		### Example

		```javascript
		push.unregister(function() {
		console.log('success');
		}, function() {
		console.log('error');
		});
		```

		## push.setApplicationIconBadgeNumber(successHandler, errorHandler, count) - iOS only

		Set the badge count visible when the app is not running

		### Parameters

		Parameter \| Type \| Default \| Description
		--------- \| ---- \| ------- \| -----------
		`successHandler` \| `Function` \| \| Is called when the api successfully sets the icon badge number.
		`errorHandler` \| `Function` \| \| Is called when the api encounters an error while trying to set the icon badge number.
		`count` \| `number` \| \| Indicates what number should show up in the badge. Passing 0 will clear the badge. Each `notification` event contains a `data.count` value which can be used to set the badge to correct number.

		### Example

		```javascript
		push.setApplicationIconBadgeNumber(function() {
		console.log('success');
		}, function() {
		console.log('error');
		}, 2);
		```

		## push.getApplicationIconBadgeNumber(successHandler, errorHandler) - iOS only

		Get the current badge count visible when the app is not running

		### Parameters

		Parameter \| Type \| Default \| Description
		--------- \| ---- \| ------- \| -----------
		`successHandler` \| `Function` \| \| Is called when the api successfully retrieves the icon badge number.
		`errorHandler` \| `Function` \| \| Is called when the api encounters an error while trying to retrieve the icon badge number.

		### Callback parameters

		#### `successHandler`

		Parameter \| Type \| Description
		--------- \| ---- \| -----------
		`n` \| `number` \| An integer which is the current badge count.

		### Example

		```javascript
		push.getApplicationIconBadgeNumber(function(n) {
		console.log('success', n);
		}, function() {
		console.log('error');
		});
		```

		## push.finish(successHandler, errorHandler) - iOS only

		Tells the OS that you are done processing a background push notification.

		### Parameters

		Parameter \| Type \| Default \| Description
		--------- \| ---- \| ------- \| -----------
		`successHandler` \| `Function` \| \| Is called when the api successfully completes background push processing.
		`errorHandler` \| `Function` \| \| Is called when the api encounters an error while processing and completing the background push.

		### Example

		```javascript
		push.finish(function() {
		console.log('success');
		}, function() {
		console.log('error');
		});
		```
		No newline at end of file

docs/EXAMPLES.md

0 → 100644

+32 −0

Original line number	Diff line number	Diff line
		## Quick Example

		```javascript
		var push = PushNotification.init({
		android: {
		senderID: "12345679"
		},
		ios: {
		alert: "true",
		badge: "true",
		sound: "true"
		},
		windows: {}
		});

		push.on('registration', function(data) {
		// data.registrationId
		});

		push.on('notification', function(data) {
		// data.message,
		// data.title,
		// data.count,
		// data.sound,
		// data.image,
		// data.additionalData
		});

		push.on('error', function(e) {
		// e.message
		});
		```
		No newline at end of file

docs/INSTALLATION.md

0 → 100644

+102 −0

Original line number	Diff line number	Diff line
		# Installation

		This requires phonegap/cordova CLI 5.0+ ( current stable v1.4.4 )

		```
		phonegap plugin add phonegap-plugin-push
		```
		or

		```
		cordova plugin add phonegap-plugin-push
		```

		It is also possible to install via repo url directly ( unstable )

		```
		phonegap plugin add https://github.com/phonegap/phonegap-plugin-push
		```

		or

		```
		cordova plugin add https://github.com/phonegap/phonegap-plugin-push
		```

		## Android details

		### Compilation

		As of version 1.3.0 the plugin has been switched to using Gradle/Maven for building.

		You will need to ensure that you have installed the following items through the Android SDK Manager:

		- Android Support Library version 23 or greater
		- Android Support Repository version 20 or greater
		- Google Play Services version 27 or greater
		- Google Repository version 22 or greater

		![android support library](https://cloud.githubusercontent.com/assets/353180/10230226/0627931e-684a-11e5-9a6b-72d72997f655.png)

		For more detailed instructions on how to install the Android Support Library visit [Google's documentation](https://developer.android.com/tools/support-library/setup.html).

		### Co-existing with FaceBook Plugin

		There are a number of Cordova FaceBook Plugins available but the one that we recommend is [Jeduan's fork](https://github.com/jeduan/cordova-plugin-facebook4) of the original Wizcorp plugin. It is setup to use Gradle/Maven and the latest FaceBook SDK properly.

		To add to your app:

		```
		phonegap plugin add --save cordova-plugin-facebook4 --variable APP_ID="App ID" --variable APP_NAME="App Name"
		```
		or

		```
		cordova plugin add --save cordova-plugin-facebook4 --variable APP_ID="App ID" --variable APP_NAME="App Name"
		```

		### Common errors

		#### minSdkVersion === 14

		If you have an issue compiling the app and you are getting an error similar to this:

		```
		* What went wrong:
		Execution failed for task ':processDebugManifest'.
		> Manifest merger failed : uses-sdk:minSdkVersion 14 cannot be smaller than version 15 declared in library .../platforms/android/build/intermediates/exploded-aar/com.facebook.android/facebook-android-sdk/4.6.0/AndroidManifest.xml
		Suggestion: use tools:overrideLibrary="com.facebook" to force usage
		```

		Then you can add the following entry into your config.xml file in the android platform tag.

		```xml
		<platform name="android">
		<preference name="android-minSdkVersion" value="15"/>
		</platform>
		```

		#### Multidex

		If you have an issue compiling the app and you're getting an error similar to this (`com.android.dex.DexException: Multiple dex files define`):

		```
		UNEXPECTED TOP-LEVEL EXCEPTION:
		com.android.dex.DexException: Multiple dex files define Landroid/support/annotation/AnimRes;
		at com.android.dx.merge.DexMerger.readSortableTypes(DexMerger.java:596)
		at com.android.dx.merge.DexMerger.getSortedTypes(DexMerger.java:554)
		at com.android.dx.merge.DexMerger.mergeClassDefs(DexMerger.java:535)
		at com.android.dx.merge.DexMerger.mergeDexes(DexMerger.java:171)
		at com.android.dx.merge.DexMerger.merge(DexMerger.java:189)
		at com.android.dx.command.dexer.Main.mergeLibraryDexBuffers(Main.java:502)
		at com.android.dx.command.dexer.Main.runMonoDex(Main.java:334)
		at com.android.dx.command.dexer.Main.run(Main.java:277)
		at com.android.dx.command.dexer.Main.main(Main.java:245)
		at com.android.dx.command.Main.main(Main.java:106)
		```

		Then at least one other plugin you have installed is using an outdated way to declare dependencies such as `android-support` or `play-services-gcm`.
		This causes gradle to fail, and you'll need to identify which plugin is causing it and request an update to the plugin author, so that it uses the proper way to declare dependencies for cordova.
		See [this for the reference on the cordova plugin specification](https://cordova.apache.org/docs/en/5.4.0/plugin_ref/spec.html#link-18), it'll be usefull to mention it when creating an issue or requesting that plugin to be updated.

		Common plugins to suffer from this outdated dependency management are plugins related to facebook, google+, notifications, crosswalk and google maps.