public/awesome-cordova-plugins
public/awesome-cordova-plugins
9
0
Fork 0
forked from github/awesome-cordova-plugins
Code Pull Requests Activity

README

Browse Source
This commit is contained in:
Max Lynch 2017-03-21 12:55:10 -05:00
parent 5001b9bd25
commit 073535102b
1 changed files with 50 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
README.md
View File

@ -8,6 +8,8 @@
Ionic Native is a curated set of wrappers for Cordova plugins that make adding any native functionality you need to your [Ionic 2](http://ionicframework.com/) mobile app easy.
Ionic Native wraps plugin callbacks in a Promise or Observable, providing a common interface for all plugins and making it easy to use plugins with Angular change detection.
## Installation
Run following command to install Ionic Native in your project.
@ -15,47 +17,75 @@ Run following command to install Ionic Native in your project.
npm install @ionic-native/core --save
```
You also need to install the Ionic Native package for each plugin you want to add. Please see the Ionic Native documentation for complete instructions on how to add and use the plugins.
You also need to install the Ionic Native package for each plugin you want to add. Please see the [Ionic Native documentation](http://ionicframework.com/docs/v2/native/) for complete instructions on how to add and use the plugins.
## Documentation
For the full Ionic Native documentation, please visit [http://ionicframework.com/docs/v2/native/](http://ionicframework.com/docs/v2/native/).
### Promises and Observables
### Basic Usage
Ionic Native wraps plugin callbacks in a Promise or [Observable](https://gist.github.com/staltz/868e7e9bc2a7b8c1f754), providing a common interface for all plugins and ensuring that native events trigger change detection in Angular 2.
To use a plugin, import and add the plugin provider to your `@NgModule`, and then inject it where you wish to use it.
```typescript
// app.module.ts
import { Camera } from '@ionic-native/camera';
...
@NgModule({
...
providers: [
...
Camera
...
]
...
})
```
```
export class AppModule { }
import { Geolocation } from '@ionic-native/geolocation';
import { Platform } from 'ionic-angular';
import { NgZone } from '@angular/core';
@Component({ ... })
export class MyComponent {
constructor(private geolocation: Geolocation, private platform: Platform) {
constructor(private geolocation: Geolocation, private platform: Platform, private ngZone: NgZone) {
platform.ready().then(() => {
// get position
geolocation.getCurrentPosition().then(pos => {
console.log(`lat: ${pos.coords.latitude}, lon: ${pos.coords.longitude}`)
});
// watch position
const watch = geolocation.watchPosition().subscribe(pos => {
console.log(`lat: ${pos.coords.latitude}, lon: ${pos.coords.longitude}`)
// Currently, observables from Ionic Native plugins
// need to run inside of zone to trigger change detection
ngZone.run(() => {
this.position = pos;
})
});
// to stop watching
watch.unsubscribe();
});
}
}
@ -71,6 +101,9 @@ Spent way too long diagnosing an issue only to realize a plugin wasn't firing or
## Plugin Missing?
Let us know or submit a PR! Take a look at [the Developer Guide](https://github.com/driftyco/ionic-native/blob/master/DEVELOPER.md) for more on how to contribute. :heart:
## Ionic 1/Angular 1 support
Ionic Native 3.x supports Ionic 2.x and above. For Ionic/Angular 1 support, please use version 2 of Ionic Native. See the [2.x README](https://github.com/driftyco/ionic-native/blob/8cd648db5cddd7bdbe2bd78839b19c620cc8c04c/README.md) for usage information.
# Credits
@ -78,6 +111,8 @@ Ibby Hadeed - [@ihadeed](http://github.com/ihadeed)
Tim Lancina - [@timlancina](http://twitter.com/timlancina)
Mike Hartington - [@mhartington](https://twitter.com/mhartington)
Max Lynch - [@maxlynch](http://twitter.com/maxlynch)
Rob Wormald - [@robwormald](https://twitter.com/robwormald)