Work/cordova-plugin-printer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Sebastián Katzer 2014-09-08 09:31:14 +02:00
parent c54a18a5a2
commit cdd721d24b
1 changed files with 201 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

250
README.md
View File

@ -1,85 +1,220 @@
Cordova Printer-Plugin
======================
A bunch of printing plugins for Cordova 3.x.x <p align="right">
<b><a href="#">master</a><b/>
<span>&nbsp;</span>
<a href="https://github.com/katzer/cordova-plugin-printer/tree/google-cloud-print">v0.6</a>
<span>&nbsp;</span>
<a href="https://github.com/katzer/cordova-plugin-printer/tree/network-printer">v0.5</a>
</p>
Cordova Print Plugin
====================
[Cordova][cordova] plugin to print HTML documents using [AirPrint][AirPrint] for iOS and [Android Printing Framework][APF] for Android KitKat and above.
__Choose the right branch for you!__
The plugin provides multiple branches to support different printer types and android versions while _AirPrint_ is supported with each one. This is the _master_ branch.
- [master Branch][master_branch] for iOS and Android >= 4.4 (>= v0.7.x)
- [google-cloud-print Branch][google-cloud-print_branch] for Android <= 4.3 (~> v0.6.x)
- __Deprecated__ [network-printer Branch][network-printer_branch] for Android <= 4.3 (<= v0.5.x)
### About Apple AirPrint
AirPrint is an Apple™ technology that helps you create full-quality printed output without the need to download or install drivers. AirPrint is built in to many printer models from most popular printer manufacturers. Just select an AirPrint printer on your local network to print from your favorite iOS or OS X app.<br>
AirPrint printers are available for these devices when using the latest version of iOS available for them:
- iPad (all models)
- iPhone (3GS or later)
- iPod touch (3rd generation or later)
<img src="http://static1.businessinsider.com/image/4cf67b8149e2aeb00b020000/only-12-printers-work-with-apples-airprint-heres-the-list.jpg" />
### Android Printing Framework
Printing in __Android 4.4__ and later is provided by the Printing framework. By default, most Android devices have print service plugins installed to enable printing using the Google Cloud Print and Google Drive services. Print service plugins from other printer manufactures are available through the App Store though the Google Cloud Print service plugin can also be used to print from an Android device to just about any printer type and model.<br>
In addition to supporting physical printers, it is also possible to save printed output to your Google Drive account or locally as a PDF file on the Android device.
<img src="http://androidtopnews.com/wp-content/uploads/2013/10/46888__android-4.4-kitkat-official-4.jpg" />
### Supported Printers
Printing is supported on AirPrint- and Google Cloud Print-enabled printers or from Android devices to compatible network printers over Wi-Fi. 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/
- Google Cloud-ready printers: http://www.google.com/cloudprint/learn/printers.html
- Connect network printers with Google Cloud Print: https://support.google.com/cloudprint/answer/1686197?rd=1
- Printing with the Android Printing Framework: http://www.techotopia.com/index.php/Printing_with_the_Android_Printing_Framework
### Plugin's Purpose
This Cordova plugin serves as a platform independent JavaScript bridge to call the underlying native SDKs.
by Sebastián Katzer ([github.com/katzer](https://github.com/katzer))
## Supported Platforms ## Supported Platforms
- **iOS** *(Print from iOS devices to AirPrint compatible printers)*<br> - **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. See [Drawing and Printing Guide for iOS][ios_guide] for detailed informations and screenshots.
- **Android** *(SDK 19)* - **Android KitKat** *(Print from Android devices to compatible printers over Wi-Fi or cloud-hosted services such as Google Cloud Print)*
## Adding the Plugin to your project
Through the [Command-line Interface](http://cordova.apache.org/docs/en/3.0.0/guide_cli_index.md.html#The%20Command-line%20Interface):
## Installation
The plugin can either be installed from git repository, from local file system through the [Command-line Interface][CLI] or cloud based through [PhoneGap Build][PGB].
### Local development environment
From master:
```bash ```bash
# ~~ from master ~~
cordova plugin add https://github.com/katzer/cordova-plugin-printer.git cordova plugin add https://github.com/katzer/cordova-plugin-printer.git
``` ```
from a local folder:
## Removing the Plugin from your project ```bash
Through the [Command-line Interface](http://cordova.apache.org/docs/en/3.0.0/guide_cli_index.md.html#The%20Command-line%20Interface): # ~~ local folder ~~
cordova plugin add de.appplant.cordova.plugin.printer --searchpath path/to/plugin
``` ```
or to use the last stable version:
```bash
# ~~ stable version ~~
cordova plugin add de.appplant.cordova.plugin.printer
```
### 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.7.0" />
```
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
``` ```
## Release Notes
#### Version 0.5.0 (11.12.2013)
- 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) ## ChangeLog
- [feature]: Added Android support<br> #### Version 0.7.0 (not yet released)
*Based on the Print Android plugin made by* ***Eion Robb*** - AirPrint support
- [feature]: `print()` accepts a 4th arguments for platform specific properties. - Android Printing Framework support
- [change]: the callback of `print()` will be called with a result code about the user action. - [__change__:] Renamed `isServiceAvailable` to `isAvailable`.
- [enhancement:] New print options like `name`, `landscape` or `duplex`.
#### Version 0.2.1 (13.08.2013) #### Further informations
- [feature]: Support for callback scopes. - See [CHANGELOG.md][changelog] to get the full changelog for the plugin.
#### 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 `cordova.plugins.printer` with the following methods:
### isServiceAvailable() 1. [printer.isAvailable][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. [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. // cordova.plugins.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.isAvailable` 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 Android KitKat and above.<br>
```javascript
/**
* Checks if the printer service is avaible (iOS)
* or if connected to the Internet (Android).
*
* @param {Function} callback
* A callback function
* @param {Object?} scope
* The scope of the callback (default: window)
*
* @return {Boolean}
*/ */
window.plugin.printer.isServiceAvailable( cordova.plugins.printer.isAvailable(
function (isAvailable) { function (isAvailable) {
alert(isAvailable ? 'Service is available' : 'Service NOT available'); alert(isAvailable ? 'Service is available' : 'Service NOT available');
} }
); );
``` ```
### 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. Optional parameters allows to specify the name of the document and a callback. The callback will be called if the user cancels or completes the print job.
**Note:** All required CSS rules needs to be included as well. #### Available Options
| Name | Description | Type | Support |
| ---- | ----------- |:----:| -------:|
| name | The name of the print job and of the document | String | all |
| printerId| An identifier of the printer to use for the print job. | String | iOS |
| duplex | Specifies the duplex mode to use for the print job.<br>Either double-sided (duplex:true) or single-sided (duplex:false).<br>Double-sided by default. | Boolean | iOS |
| landscape| The orientation of the printed content, portrait or landscape.<br>_Portrait_ by default. | Boolean | all |
| graystyle | If your application only prints black text, setting this property to _true_ can result in better performance in many cases.<br>_False_ by default. | Boolean | all |
#### Further informations
- See the [isAvailable][available] method to find out if printing is available on the device.
- All CSS rules needs to be embedded or accessible via absolute URLs in order to print out HTML encoded content.
- See the [examples][examples] to get an overview on how to use the plugin.
```javascript ```javascript
// Get HTML string /**
var page = document.body.innerHTML; * Sends the content to the Google Cloud Print service.
*
* @param {String} content
* HTML string or DOM node
* if latter, innerHTML is used to get the content
* @param {Object} options
* Options for the print job
* @param {Function?} callback
* A callback function
* @param {Object?} scope
* The scope of the callback (default: window)
*/
cordova.plugins.printer.print(content, options, callback, scope);
```
// Pass the HTML
window.plugin.printer.print(page); ## Examples
__NOTE:__ All CSS rules needs to be embedded or accessible via absolute URLs in order to print out HTML encoded content.
#### 1. Print the whole HTML page
```javascript
// Either a DOM node or a string
var page = document.body;
cordova.plugins.printer.print(page, 'Document.html', function () {
alert('printing finished or canceled')
});
```
#### 2. Print custom specific content
```javascript
// Either a DOM node or a string
var page = '<h1>Hello Document</h1>';
cordova.plugins.printer.print(page, 'Document.html', function () {
alert('printing finished or canceled')
});
```
#### 3. Adjust the page
```javascript
cordova.plugins.printer.print('123', { name:'Document.html', landscape:true }, function () {
alert('printing finished or canceled')
});
``` ```
## Quirks ## Quirks
### Testing in the iOS Simulator ### 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). 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 ### Adding Page Breaks to Printouts
Use the 'page-break-before' property to specify a page break, e.g. Use the 'page-break-before' property to specify a page break, e.g.
@ -96,14 +231,9 @@ Second page.
See W3Schools for more more information: http://www.w3schools.com/cssref/pr_print_pagebb.asp 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. __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 ## Contributing
1. Fork it 1. Fork it
@ -114,4 +244,26 @@ 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
[GCP]: http://www.google.com/cloudprint/learn/index.html
[APF]: http://www.techotopia.com/index.php/Printing_with_the_Android_Printing_Framework
[AirPrint]: http://support.apple.com/kb/ht4356
[master_branch]: #
[google-cloud-print_branch]: https://github.com/katzer/cordova-plugin-printer/tree/google-cloud-print
[network-printer_branch]: https://github.com/katzer/cordova-plugin-printer/tree/network-printer
[ios_guide]: http://developer.apple.com/library/ios/documentation/2ddrawing/conceptual/drawingprintingios/Printing/Printing.html
[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/index.html
[PGB_plugin]: https://build.phonegap.com/plugins/
[changelog]: CHANGELOG.md
[available]: #find-out-if-printing-is-available-on-the-device
[print]: #send-content-to-a-printer
[examples]: #examples
[apache2_license]: http://opensource.org/licenses/Apache-2.0
[katzer]: katzer@appplant.de
[appplant]: www.appplant.de