Update doc
This commit is contained in:
Sebastián Katzer
parent
03b70956ba
commit
aa22e1c060
167
README.md
167
README.md
@ -12,79 +12,88 @@ See [Drawing and Printing Guide for iOS](http://developer.apple.com/library/ios/
|
|||||||
- **Android** *(Print through 3rd party printing apps)*
|
- **Android** *(Print through 3rd party printing apps)*
|
||||||
|
|
||||||
|
|
||||||
## Adding the Plugin to your project
|
## Installation
|
||||||
Through the [Command-line Interface](http://cordova.apache.org/docs/en/3.0.0/guide_cli_index.md.html#The%20Command-line%20Interface):
|
The plugin can either be installed from git repository or from local file system through the [Command-line Interface][CLI].<br>
|
||||||
|
Or cloud based through [PhoneGap Build][PGB].
|
||||||
|
|
||||||
|
### Local development environment
|
||||||
|
From master:
|
||||||
```bash
|
```bash
|
||||||
# from master:
|
# ~~ from master ~~
|
||||||
cordova plugin add https://github.com/katzer/cordova-plugin-printer.git
|
cordova plugin add https://github.com/katzer/cordova-plugin-printer.git && cordova prepare
|
||||||
cordova build
|
```
|
||||||
|
from a local folder:
|
||||||
# stable version:
|
```bash
|
||||||
cordova de.appplant.cordova.plugin.printer
|
# ~~ local folder ~~
|
||||||
cordova build
|
cordova plugin add de.appplant.cordova.plugin.printer --searchpath path/to/plugin && cordova prepare
|
||||||
|
```
|
||||||
|
or to use the last stable version:
|
||||||
|
```bash
|
||||||
|
# ~~ stable version ~~
|
||||||
|
cordova plugin add de.appplant.cordova.plugin.printer && cordova prepare
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### PhoneGap Build
|
||||||
## Removing the Plugin from your project
|
Add the following xml to your config.xml to always use the latest version of this plugin:
|
||||||
Through the [Command-line Interface](http://cordova.apache.org/docs/en/3.0.0/guide_cli_index.md.html#The%20Command-line%20Interface):
|
```xml
|
||||||
|
<gap:plugin name="de.appplant.cordova.plugin.printer" />
|
||||||
```
|
```
|
||||||
|
or to use an specific version:
|
||||||
|
```xml
|
||||||
|
<gap:plugin name="de.appplant.cordova.plugin.printer" version="0.5.2" />
|
||||||
|
```
|
||||||
|
More informations can be found [here][PGB_plugin].
|
||||||
|
|
||||||
|
### Removing the Plugin
|
||||||
|
Through the [Command-line Interface][CLI]:
|
||||||
|
```bash
|
||||||
cordova plugin rm de.appplant.cordova.plugin.printer
|
cordova plugin rm de.appplant.cordova.plugin.printer
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## PhoneGap Build
|
## ChangeLog
|
||||||
Add the following xml to your config.xml to always use the latest version of this plugin:
|
|
||||||
```
|
|
||||||
<gap:plugin name="de.appplant.cordova.plugin.printer" />
|
|
||||||
```
|
|
||||||
or to use this exact version:
|
|
||||||
```
|
|
||||||
<gap:plugin name="de.appplant.cordova.plugin.printer" version="0.5.1" />
|
|
||||||
```
|
|
||||||
More informations can be found [here](https://build.phonegap.com/plugins/360).
|
|
||||||
|
|
||||||
|
|
||||||
## Release Notes
|
|
||||||
#### Version 0.6.0 (not yet released)
|
#### Version 0.6.0 (not yet released)
|
||||||
|
- [bugfix]: Printing wasn't possible because `isServiceAvailable` returns False IOS
|
||||||
- [feature]: Added Windows8 support<br>
|
- [feature]: Added Windows8 support<br>
|
||||||
*Thanks to* ***pirvudoru***
|
*Thanks to* ***pirvudoru***
|
||||||
|
|
||||||
#### Version 0.5.2 (22.03.2014)
|
#### Further informations
|
||||||
- [bugfix:] `isServiceAvailable` on Android did not return a list of available printing apps.
|
- See [CHANGELOG.md][changelog] to get the full changelog for the plugin.
|
||||||
|
|
||||||
#### Version 0.5.1 (15.12.2013)
|
|
||||||
- Removed Android KitKat support *(See kitkat branch)*
|
|
||||||
|
|
||||||
#### Version 0.5.0 (yanked)
|
|
||||||
- Release under the Apache 2.0 license.
|
|
||||||
- [***change:***] Removed the `callback` property from the `print` interface.
|
|
||||||
- [enhancement:] Added Android KitKat support<br>
|
|
||||||
*Based on the Print Android plugin made by* ***Eion Robb***
|
|
||||||
|
|
||||||
#### Version 0.4.0 (24.08.2013)
|
|
||||||
- [feature]: Added Android support<br>
|
|
||||||
*Based on the Print Android plugin made by* ***Eion Robb***
|
|
||||||
- [feature]: `print()` accepts a 4th arguments for platform specific properties.
|
|
||||||
- [change]: the callback of `print()` will be called with a result code about the user action.
|
|
||||||
|
|
||||||
#### Version 0.2.1 (13.08.2013)
|
|
||||||
- [feature]: Support for callback scopes.
|
|
||||||
|
|
||||||
#### Version 0.2.0 (11.08.2013)
|
|
||||||
- [feature]: Added iOS support<br>
|
|
||||||
*Based on the Print iOS plugin made by* ***Randy McMillan***
|
|
||||||
|
|
||||||
## Using the plugin
|
## Using the plugin
|
||||||
The plugin creates the object ```window.plugin.printer``` with two methods:
|
The plugin creates the object `window.plugin.printer` with the following methods:
|
||||||
|
|
||||||
### isServiceAvailable()
|
1. [plugin.printer.isServiceAvailable][available]
|
||||||
Printing is only available on devices capable of multi-tasking (iPhone 3GS, iPhone 4 etc.) running iOS 4.2 or later. You can use this function to hide print functionality from users who will be unable to use it.<br>
|
2. [plugin.printer.print][print]
|
||||||
Function takes a callback function, passed to which is a boolean property. Optionally you can assign the scope in which the callback will be executed as a second parameter (default to *window*).
|
|
||||||
|
### Plugin initialization
|
||||||
|
The plugin and its methods are not available before the *deviceready* event has been fired.
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
/*
|
document.addEventListener('deviceready', function () {
|
||||||
* Find out if printing is available. Use this for showing/hiding print buttons.
|
// window.plugin.printer is now available
|
||||||
|
}, false);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Find out if printing is available on the device
|
||||||
|
The device his printing capabilities can be reviewed through the `printer.isServiceAvailable` interface.
|
||||||
|
You can use this function to hide print functionality from users who will be unable to use it.<br>
|
||||||
|
The method takes a callback function, passed to which is a boolean property. Optionally you can assign the scope in which the callback will be executed as a second parameter (default to *window*).
|
||||||
|
|
||||||
|
__Note:__ Printing is only available on devices capable of multi-tasking (iPhone 3GS, iPhone 4 etc.) running iOS 4.2 or later or through a pre-installed printer app (Android).<br>
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
/**
|
||||||
|
* Checks if the printer service is avaible (iOS)
|
||||||
|
* or if a printing app is installed on the device (Android).
|
||||||
|
*
|
||||||
|
* @param {Function} callback
|
||||||
|
* A callback function
|
||||||
|
* @param {Object?} scope
|
||||||
|
* The scope of the callback (default: window)
|
||||||
|
*
|
||||||
|
* @return {Boolean}
|
||||||
*/
|
*/
|
||||||
window.plugin.printer.isServiceAvailable(
|
window.plugin.printer.isServiceAvailable(
|
||||||
function (isAvailable) {
|
function (isAvailable) {
|
||||||
@ -93,19 +102,41 @@ window.plugin.printer.isServiceAvailable(
|
|||||||
);
|
);
|
||||||
```
|
```
|
||||||
|
|
||||||
### print()
|
### Send content to a printer
|
||||||
Function takes an html string.
|
Content can be send to a printer through the `printer.print` interface.<br>
|
||||||
|
The method takes a string or a HTML DOM node.
|
||||||
|
|
||||||
**Note:** All required CSS rules needs to be included as well.
|
#### Further informations
|
||||||
|
- See the [isServiceAvailable][available] method to find out if printing is available on the device.
|
||||||
|
- All required CSS rules needs to be included in order to print HTML encoded content.
|
||||||
|
- On Android the functionality between different print apps may vary.
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
// Get HTML string
|
/**
|
||||||
var page = document.body.innerHTML;
|
* Sends the content to a printer app or service.
|
||||||
|
*
|
||||||
|
* @param {String} content
|
||||||
|
* HTML string or DOM node
|
||||||
|
* if latter, innerHTML is used to get the content
|
||||||
|
* @param {Object?} options
|
||||||
|
* Platform specific options
|
||||||
|
*/
|
||||||
|
window.plugin.printer.print(content, options);
|
||||||
|
```
|
||||||
|
|
||||||
// Pass the HTML
|
|
||||||
|
## Example
|
||||||
|
The following exmaple demonstrates how to print out the whole HTML page.
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Get the content
|
||||||
|
var page = document.body;
|
||||||
|
|
||||||
|
// Pass to the printer
|
||||||
window.plugin.printer.print(page);
|
window.plugin.printer.print(page);
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## Platform specifics
|
## Platform specifics
|
||||||
|
|
||||||
### Get all available printing apps on Android
|
### Get all available printing apps on Android
|
||||||
@ -162,4 +193,18 @@ Printing is only supported on AirPrint-enabled printers or with the use of third
|
|||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
This software is released under the [Apache 2.0 License](http://opensource.org/licenses/Apache-2.0).
|
This software is released under the [Apache 2.0 License][apache2_license].
|
||||||
|
|
||||||
|
© 2013-2014 appPlant UG, Inc. All rights reserved
|
||||||
|
|
||||||
|
|
||||||
|
[cordova]: https://cordova.apache.org
|
||||||
|
[CLI]: http://cordova.apache.org/docs/en/edge/guide_cli_index.md.html#The%20Command-line%20Interface
|
||||||
|
[PGB]: http://docs.build.phonegap.com/en_US/3.3.0/index.html
|
||||||
|
[PGB_plugin]: https://build.phonegap.com/plugins/676
|
||||||
|
[changelog]: CHANGELOG.md
|
||||||
|
[available]: #find-out-if-printing-is-available-on-the-device
|
||||||
|
[print]: #send-content-to-a-printer
|
||||||
|
[apache2_license]: http://opensource.org/licenses/Apache-2.0
|
||||||
|
[katzer]: katzer@appplant.de
|
||||||
|
[appplant]: www.appplant.de
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user