212 lines
6.9 KiB
Markdown
212 lines
6.9 KiB
Markdown
Cordova Printer-Plugin
|
|
======================
|
|
|
|
A bunch of printing plugins for Cordova 3.x.x
|
|
|
|
by Sebastián Katzer ([github.com/katzer](https://github.com/katzer))
|
|
|
|
## Supported Platforms
|
|
- **iOS** *(Print from iOS devices to AirPrint compatible printers)*<br>
|
|
See [Drawing and Printing Guide for iOS](http://developer.apple.com/library/ios/documentation/2ddrawing/conceptual/drawingprintingios/Printing/Printing.html) for detailed informations and screenshots.
|
|
|
|
- **Android** *(Print through 3rd party printing apps)*
|
|
|
|
|
|
## Installation
|
|
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
|
|
# ~~ from master ~~
|
|
cordova plugin add https://github.com/katzer/cordova-plugin-printer.git && cordova prepare
|
|
```
|
|
from a local folder:
|
|
```bash
|
|
# ~~ local folder ~~
|
|
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
|
|
Add the following xml to your config.xml to always use the latest version of this plugin:
|
|
```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
|
|
```
|
|
|
|
|
|
## ChangeLog
|
|
#### Version 0.6.0 (not yet released)
|
|
- [bugfix]: Printing wasn't possible because `isServiceAvailable` returns False IOS
|
|
- [bugfix]: Using plugin prevents openDatabase() on Android
|
|
- [feature]: Added Windows8 support<br>
|
|
*Thanks to* ***pirvudoru***
|
|
|
|
#### Further informations
|
|
- See [CHANGELOG.md][changelog] to get the full changelog for the plugin.
|
|
|
|
|
|
## Using the plugin
|
|
The plugin creates the object `window.plugin.printer` with the following methods:
|
|
|
|
1. [plugin.printer.isServiceAvailable][available]
|
|
2. [plugin.printer.print][print]
|
|
|
|
### Plugin initialization
|
|
The plugin and its methods are not available before the *deviceready* event has been fired.
|
|
|
|
```javascript
|
|
document.addEventListener('deviceready', function () {
|
|
// 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(
|
|
function (isAvailable) {
|
|
alert(isAvailable ? 'Service is available' : 'Service NOT available');
|
|
}
|
|
);
|
|
```
|
|
|
|
### Send content to a printer
|
|
Content can be send to a printer through the `printer.print` interface.<br>
|
|
The method takes a string or a HTML DOM node.
|
|
|
|
#### 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
|
|
/**
|
|
* 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);
|
|
```
|
|
|
|
|
|
## 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);
|
|
```
|
|
|
|
|
|
## Platform specifics
|
|
|
|
### Get all available printing apps on Android
|
|
The callback function will be called with a second argument which is an array, indicating which printer apps are available for printing.
|
|
```javascript
|
|
window.plugin.printer.isServiceAvailable(
|
|
function (isAvailable, installedAppIds) {
|
|
alert('The following print apps are installed on your device: ' + installedAppIds.join(', '));
|
|
}
|
|
);
|
|
```
|
|
|
|
### Specify printing app on Android
|
|
An App-ID can be assigned as a platform configuration to indicate which 3rd party printing app shall be used. Otherwise the first found application will be used.
|
|
```javascript
|
|
window.plugin.printer.print(page, { appId: 'epson.print' });
|
|
```
|
|
|
|
## Quirks
|
|
|
|
### Testing in the iOS Simulator
|
|
There's no need to waste lots of paper when testing - if you're using the iOS simulator, select File->Open Printer Simulator to open some dummy printers (print outs will appear as PDF files).
|
|
|
|
### Adding Page Breaks to Printouts
|
|
Use the 'page-break-before' property to specify a page break, e.g.
|
|
|
|
```html
|
|
<p>
|
|
First page.
|
|
</p>
|
|
|
|
<p style="page-break-before: always">
|
|
Second page.
|
|
</p>
|
|
```
|
|
|
|
See W3Schools for more more information: http://www.w3schools.com/cssref/pr_print_pagebb.asp
|
|
|
|
Note: you will need to add an extra top margin to new pages.
|
|
|
|
|
|
### Printing on Real Printers (iOS)
|
|
Printing is only supported on AirPrint-enabled printers or with the use of third-party software on your computer. The following pages contain more information:
|
|
- AirPrint-enabled printers: http://www.apple.com/ipad/features/airprint.html
|
|
- Enabling AirPrint on your computer: http://reviews.cnet.com/8301-19512_7-20023976-233.html, or http://www.ecamm.com/mac/printopia/
|
|
|
|
## Contributing
|
|
|
|
1. Fork it
|
|
2. Create your feature branch (`git checkout -b my-new-feature`)
|
|
3. Commit your changes (`git commit -am 'Add some feature'`)
|
|
4. Push to the branch (`git push origin my-new-feature`)
|
|
5. Create new Pull Request
|
|
|
|
## License
|
|
|
|
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
|