github/awesome-cordova-plugins
github/awesome-cordova-plugins
2
0
Fork 1
mirror of https://github.com/danielsogl/awesome-cordova-plugins.git synced 2025-02-21 00:23:00 +08:00
Code Issues Projects Releases Wiki Activity

Update readme

Browse Source
This commit is contained in:
Ibby Hadeed 2017-12-29 10:40:46 -05:00
parent 0cc1a2b2ff
commit dcf5102c57
No known key found for this signature in database
GPG Key ID: 1CA08EB11DAAA786
1 changed files with 68 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
README.md
View File

@ -11,22 +11,26 @@ Ionic Native wraps plugin callbacks in a Promise or Observable, providing a comm
Run following command to install Ionic Native in your project.
```bash
npm install @ionic-native/core --save
npm install @ionic-native/core@beta --save
```
You also need to install the Ionic Native package for each plugin you want to add. Please see the [Ionic Native documentation](https://ionicframework.com/docs/native/) for complete instructions on how to add and use the plugins.
**NOTE: to use Ionic Native v5, you must use the `@beta` tag when installing any NPM package.**
## Documentation
For the full Ionic Native documentation, please visit [https://ionicframework.com/docs/native/](https://ionicframework.com/docs/native/).
### Basic Usage
To use a plugin, import and add the plugin provider to your `@NgModule`, and then inject it where you wish to use it.
#### Angular/Ionic apps
To use a plugin, import and add the plugin provider to your `@NgModule`, and then inject it where you wish to use it.
Make sure to import the injectable class from the `/ngx` directory as shown in the following examples:
```typescript
// app.module.ts
import { Camera } from '@ionic-native/camera';
import { Camera } from '@ionic-native/camera/ngx';
...
@ -44,11 +48,9 @@ export class AppModule { }
```
```typescript
import { Geolocation } from '@ionic-native/geolocation';
import { Geolocation } from '@ionic-native/geolocation/ngx';
import { Platform } from 'ionic-angular';
import { NgZone } from '@angular/core';
@Component({ ... })
export class MyComponent {
@ -77,16 +79,71 @@ export class MyComponent {
}
```
### Mocking and Browser Development
#### ES2015 Modules
These modules can work in any ES2015+/TypeScript app (including Angular/Ionic apps). To use any plugin, import the class from the appropriate package, and use it's static methods.
```js
import { Camera } from '@ionic-native/camera';
Ionic Native 3.x makes it possible to mock plugins and develop nearly the entirety of your app in the browser or in `ionic serve`.
document.addEventListener('deviceready', () => {
Camera.getPicture()
.then((data) => console.log('Took a picture!', data))
.catch((e) => console.log('Error occurred while taking a picture', e));
});
```
#### AngularJS
Ionic Native generates an AngularJS module in runtime and prepares a service for each plugin. To use the plugins in your AngularJS app:
1. Download the latest bundle from the [Github releases](https://github.com/ionic-team/ionic-native/releases) page.
2. Include it in `index.html` before your app's code.
3. Inject `ionic.native` module in your app.
4. Inject any plugin you would like to use with a `$cordova` prefix.
```js
angular.module('myApp', ['ionic.native'])
.controller('MyPageController', function($cordovaCamera) {
$cordovaCamera.getPicture()
.then(
function(data) {
console.log('Took a picture!', data);
},
function(err) {
console.log('Error occurred while taking a picture', err);
}
);
});
```
#### Vanilla JS
To use Ionic Native in other environments:
1. Download the latest bundle from the [Github releases](https://github.com/ionic-team/ionic-native/releases) page.
2. Include it in `index.html` before your app's code.
3. Access any plugin using the global `IonicNative` variable.
```js
document.addEventListener('deviceready', function() {
IonicNative.Camera.getPicture()
.then(
function(data) {
console.log('Took a picture!', data);
},
function(err) {
console.log('Error occurred while taking a picture', err);
}
);
});
```
### Mocking and Browser Development (Angular apps only)
Ionic Native makes it possible to mock plugins and develop nearly the entirety of your app in the browser or in `ionic serve`.
To do this, you need to provide a mock implementation of the plugins you wish to use. Here's an example of mocking the `Camera` plugin to return a stock image while in development:
First import the `Camera` class in your `src/app/app.module.ts` file:
```typescript
import { Camera } from '@ionic-native/camera';
import { Camera } from '@ionic-native/camera/ngx';
```
Then create a new class that extends the `Camera` class with a mock implementation:
@ -118,7 +175,7 @@ import { IonicApp, IonicModule, IonicErrorHandler } from 'ionic-angular';
import { MyApp } from './app.component';
import { HomePage } from '../pages/home/home';
import { Camera } from '@ionic-native/camera';
import { Camera } from '@ionic-native/camera/ngx';
class CameraMock extends Camera {
getPicture(options) {
@ -143,7 +200,7 @@ class CameraMock extends Camera {
HomePage
],
providers: [
{provide: ErrorHandler, useClass: IonicErrorHandler},
{ provide: ErrorHandler, useClass: IonicErrorHandler },
{ provide: Camera, useClass: CameraMock }
]
})
@ -161,9 +218,6 @@ 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/ionic-team/ionic-native/blob/master/DEVELOPER.md) for more on how to contribute. :heart:
## Ionic v1 (AngularJS, Angular 1.x) support
For Ionic v1 (AngularJS, Angular 1.x) support, please use version 2 of Ionic Native. See the [2.x README](https://github.com/ionic-team/ionic-native/blob/v2.x/README.md) for usage information.
# Credits