cordova-plugin-printer/README.md

Cordova Printer-Plugin

A bunch of printing plugins for Cordova 3.x.x

by Sebastián Katzer (github.com/katzer)

Supported Platforms

• iOS (Print from iOS devices to AirPrint compatible printers)
  See Drawing and Printing Guide for iOS 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.
Or cloud based through PhoneGap Build.

Local development environment

From master:

# ~~ from master ~~
cordova plugin add https://github.com/katzer/cordova-plugin-printer.git && cordova prepare

from a local folder:

# ~~ local folder ~~
cordova plugin add de.appplant.cordova.plugin.printer --searchpath path/to/plugin && cordova prepare

or to use the last stable version:

# ~~ 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:

<gap:plugin name="de.appplant.cordova.plugin.printer" />

or to use an specific version:

<gap:plugin name="de.appplant.cordova.plugin.printer" version="0.5.2" />

More informations can be found here.

Removing the Plugin

Through the Command-line Interface:

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
  Thanks to pirvudoru

Further informations

• See CHANGELOG.md 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
2. plugin.printer.print

Plugin initialization

The plugin and its methods are not available before the deviceready event has been fired.

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.
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).

/**
 * 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.
The method takes a string or a HTML DOM node.

Further informations

• See the isServiceAvailable 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.

/**
 * 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.

// 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.

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.

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.

<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.

© 2013-2014 appPlant UG, Inc. All rights reserved