PDF Document viewer cordova plugin for iOS, Android and Windows 8.1 + 10
npm install cordova-plugin-document-viewerCordova Document Viewer Plugin
============================
A common requirement when developing a cordova based app is to embed a
performant and secure inline viewer for pdf files which doesn't allow the user
to extract a copy of the pdf file out of the apps sandbox.
Simple delegation to commonly available viewer apps like Acrobat Reader or
MuPDF is no proper solution, as the app looses control over the pdf file in this case.
The external viewer app may or may not provide features to send the document
via email or save it to the devices disk, which is not acceptable.
This plugin offers a slim API to view PDF files which are either stored in the
apps assets folder (/www/*) or in any other file system directory
available via the cordova file plugin
(e.g. cordova.file.applicationDirectory, cordova.file.dataDirectory).
Online files reachable via http(s) are not supported. Download them to a temp
folder before starting the viewer. You may use the ``onClose` callback
`
to cleanup the temp dir when the viewer is closed.
Viewer features like "Save as" or "Send via EMail" are configurable at runtime.
Labels for buttons (i18n) are configurable at runtime.
$3
The purpose of the plugin is to create a platform independent javascript
interface for [Cordova][cordova] based mobile applications to view different
document types by using native viewer components.
Overview
1. Supported Platforms
2. Installation
3. Using the plugin
4. Known issues
Supported Platforms ##
* Cordova/Phonegap >=4.4.0
* iOS 7+
* Android 4.1+
* Windows 8.1
* Windows 10
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].
The plugin is published at the [npm plugin registry][CDV_plugin].
An [ionic native wrapper][ionic] for the plugin is available.
$3
From master:
bash
`~~ from master branch ~~
cordova plugin add https://github.com/sitewaerts/cordova-plugin-document-viewer.git
`
from a local folder:
bash
`~~ local folder ~~
cordova plugin add cordova-plugin-document-viewer --searchpath path/to/plugin
`
or to use the last stable version:
bash
`~~ stable version ~~
cordova plugin add cordova-plugin-document-viewer
`
or to use a specific version:
bash
`~~ stable version ~~
cordova plugin add cordova-plugin-document-viewer@[VERSION]
`
You may replace cordova with phonegap regarding to your needs.
$3
Add the following xml to your config.xml to always use the latest version of this plugin:
xml
`
`
or a specific version:
xml
`
`
For available versions and additional information visit the [npm plugin registry][CDV_plugin].
Using the plugin ##
See https://github.com/sitewaerts/cordova-plugin-document-viewer-sample-app for a working example.
The plugin creates the object cordova.plugins.SitewaertsDocumentViewer`.
`
$3
The plugin and its methods are not available before the deviceready event has been fired.
javascript
`
document.addEventListener('deviceready', function () {
// cordova.plugins.SitewaertsDocumentViewer is now available
}, false);
`
$3
#### url ####
String pointing to a device local file (e.g. 'file:///...')
#### mimeType ####
String representing the mime type of the file. Currently only 'application/pdf' is supported.
#### options ####
Some optional features like search or bookmarks are not (yet) implemented on every platform!
js
`
var options = {
title: STRING,
documentView : {
closeLabel : STRING
},
navigationView : {
closeLabel : STRING
},
email : {
enabled : BOOLEAN
},
print : {
enabled : BOOLEAN
},
openWith : {
enabled : BOOLEAN
},
bookmarks : {
enabled : BOOLEAN
},
search : {
enabled : BOOLEAN
},
autoClose: {
onPause : BOOLEAN
}
}
`
$3
js
`
cordova.plugins.SitewaertsDocumentViewer.canViewDocument(
url, contentType, options, onPossible, onMissingApp, onImpossible, onError);
`
#### onPossible ####
js
`
function onPossible(){
window.console.log('document can be shown');
//e.g. track document usage
}
`
#### onMissingApp ####
js
`
function onMissingApp(appId, installer)
{
if(confirm("Do you want to install the free PDF Viewer App "
+ appId + " for Android?"))
{
installer();
}
}
`
#### onImpossible ####
js
`
function onImpossible(){
window.console.log('document cannot be shown');
//e.g. track document usage
}
`
#### onError ####
js
`
function onError(error){
window.console.log(error);
alert("Sorry! Cannot show document.");
}
`
$3
js
`
cordova.plugins.SitewaertsDocumentViewer.viewDocument(
url, mimeType, options, onShow, onClose, onMissingApp, onError, linkHandlers);
`
#### onShow ####
js
`
function onShow(){
window.console.log('document shown');
//e.g. track document usage
}
`
#### onClose ####
js
`
function onClose(){
window.console.log('document closed');
//e.g. remove temp files
}
`
#### onMissingApp ####
js
`
function onMissingApp(appId, installer)
{
if(confirm("Do you want to install the free PDF Viewer App "
+ appId + " for Android?"))
{
installer();
}
}
`
#### onError ####
js
`
function onError(error){
window.console.log(error);
alert("Sorry! Cannot view document.");
}
`
#### linkHandlers ####
Currently only supported on iOS!
Array of link handlers. Optional.
Links in the pdf (when clicked by the user) are delegated to the first linkHandler with a matching pattern.
If no matching pattern is found, the link is handled with the default link handler of the native viewer component (if any).
js
`
var linkHandlers = [
{
pattern: STRING, // string representation of a plain regexp (no flags)
close: BOOLEAN, // shall the document be closed, after the link handler was executed?
handler: function (link) {} // link handler to be executed when the user clicks on a link matching the pattern
},
{
pattern: '^\/',
close: false,
handler: function (link) {
window.console.log('link clicked: ' + link);
}
}
];
`
$3
js
`
cordova.plugins.SitewaertsDocumentViewer.closeDocument(onClose, onError);
`
#### onShow ####
js
`
function onClose(url){
if(url)
window.console.log('closed viewer document ' + url);
else
window.console.log('viewer not open');
}
`
#### onError ####
js
``
function onError(error){
window.console.log(error);
alert("Sorry! Cannot close viewer.");
}