|
1 | | -# Android PDF Creator |
2 | | -Titanium Module for generating PDF files based on HTML or a WebView content |
| 1 | +# PDF Creator |
| 2 | +Titanium Native Module (Android) and libraries for generating PDF files based on HTML |
3 | 3 |
|
4 | 4 | ## Before you start |
5 | | -* This module has been only tested with Titanium SDK 3.4.x and up |
6 | | -* All the PDF work is done by iText libraries: http://itextpdf.com |
7 | | - * iTextG, which is a port for Android |
8 | | - * XMLWorker, which is intended for parse HTML files into PDF |
9 | | - * Please refer to the XMLWorker Documentation to make sure your HTML file uses all the supported tags and CSS properties: http://demo.itextsupport.com/xmlworker/itextdoc/index.html |
10 | | - * iTextG is licensed under the GNU Affero General Public License version 3 and depending on the nature of your app you might need a license. Please visit [license](http://itextpdf.com/pricing/android_license) for details. |
| 5 | +* The Android module has been tested with Titanium SDK 5.x and up. |
| 6 | +* All the PDF creation is done by iText: http://itextpdf.com |
| 7 | + * `iTextG`, which is a port for Android |
| 8 | + * `XMLWorker` which is intended for parse HTML files into PDF |
| 9 | + * **Important:** `XMLWorker` does not support the whole subset of CSS styles, for the suppoerted list refer to [their docs](http://demo.itextsupport.com/xmlworker/itextdoc/index.html) |
| 10 | + * iTextG is licensed under `GNU Affero General Public License version 3` and depending on the nature of your app you might need a license. Please visit [license](http://itextpdf.com/pricing/android_license) for details. |
11 | 11 |
|
12 | | -## Obtaining the module |
13 | | -* Download the zip file from the [dist](https://github.com/pablog178/android_pdf_creator/tree/master/dist) folder |
| 12 | +## Obtaining the module and libs |
| 13 | +* Go to the [Releases Tab](https://github.com/propelics/android_pdf_creator/releases). |
| 14 | +* `pdfGeneration.js` is optional to use, it contains the basics for generating a PDF file. |
| 15 | + * `pdfGeneration.js` depends on [mustache.js](https://github.com/janl/mustache.js) for parsing templates. |
| 16 | +* For iOS, [NappPDFCreator](https://github.com/viezel/NappPDFCreator) is recommended |
14 | 17 |
|
15 | | -## Basic Usage |
| 18 | +##PDFCreator Module |
| 19 | + |
| 20 | +### Basic Usage |
16 | 21 | 1. Make sure you have the module dependency added on `tiapp.xml` |
17 | | - |
18 | | - `<module platform="android">com.pablog178.pdfcreator.android</module>` |
19 | | - |
20 | | -2. Require the module where needed |
21 | | -3. The usage of the module is based on the events: `success` and `error` |
22 | | -4. The actual PDF creation can be achieved by the methods `generatePDFWithHTML()` or `generatePDFwithWebView()` |
23 | | -5. Once created, the success event will fire. |
24 | | - |
25 | | -## Example |
26 | | - var pdfCreator = require('com.pablog178.pdfcreator.android'); |
27 | | - |
28 | | - pdfCreator.addEventListener("complete", function (_evt) { |
29 | | - //Handle the PDF created |
30 | | - var pdfFile = Ti.Filesystem.getFile(Ti.Filesystem.applicationDataDirectory, _evt.filename); |
31 | | - //... |
32 | | - }); |
33 | 22 |
|
34 | | - pdfCreator.addEventListener("error", function(_evt){ |
35 | | - //An error has ocurred |
36 | | - }); |
37 | | - |
38 | | - // Generate a PDF based on HTML |
39 | | - pdfCreator.generatePDFWithHTML({ |
40 | | - html : '<html><body><h1>Hello World!</h1></body></html>', |
41 | | - filename : 'hello.pdf' |
42 | | - }); |
43 | | - |
44 | | - //Generate a PDF based on a webview |
45 | | - var webview = Ti.UI.createWebView({ |
46 | | - scalesPageToFit : true |
47 | | - }); |
48 | | - |
49 | | - webview.addEventListener('load', function (e) { |
50 | | - pdfCreator.generatePDFwithWebView({ |
51 | | - filename : 'hello.pdf', |
52 | | - webview : webview, |
53 | | - quality : 100 |
54 | | - }); |
55 | | - }); |
56 | | - |
57 | | - webview.url = 'www.apple.com'; |
| 23 | + ```xml |
| 24 | + <module platform="android">com.propelics.pdfcreator</module> |
| 25 | + <module platform="iphone">dk.napp.pdf.creator</module> |
| 26 | + ``` |
| 27 | + |
| 28 | +1. Require the module(s) where needed |
| 29 | + |
| 30 | + ```javascript |
| 31 | + var PdfCreator = require('com.propelics.pdfcreator'); |
| 32 | + ``` |
| 33 | + |
| 34 | +1. The usage of the module is based on events: `complete` and `error`. |
| 35 | + * `complete` - Triggered once the PDF has been generated and no errors occured. |
| 36 | + * `error` - Triggered if some error happens, stops the generation of the PDF. |
| 37 | +1. The actual PDF creation can be achieved by the methods `generatePDFWithHTML()` or `generatePDFwithWebView()` |
| 38 | + * `generatePDFWithHTML()` - Parses some HTML string and creates a PDF file from it. Use `XMLWorker` for it. PDF files have the best quality but not all HTML/CSS properties are supported yet. |
| 39 | + * `generatePDFwithWebView()` - Takes a screenshot from a given `Ti.UI.WebView` and divides the resulting image into several pages. PDF files have medium quality and use a lot of space on disk, but supports all the HTML/CSS properties available. |
| 40 | + |
| 41 | +### Example |
| 42 | +```javascript |
| 43 | +var PdfCreator = require('com.propelics.pdfcreator'); |
| 44 | + |
| 45 | +PdfCreator.addEventListener("complete", function (_evt) { |
| 46 | + //Handle the PDF created |
| 47 | + var pdfFile = Ti.Filesystem.getFile(Ti.Filesystem.applicationDataDirectory, _evt.filename); |
| 48 | + //... |
| 49 | +}); |
| 50 | + |
| 51 | +PdfCreator.addEventListener("error", function(_evt){ |
| 52 | + //An error has ocurred |
| 53 | +}); |
| 54 | + |
| 55 | +// Generate a PDF based on HTML |
| 56 | +PdfCreator.generatePDFWithHTML({ |
| 57 | + html : '<html><body><h1>Hello World!</h1></body></html>', |
| 58 | + filename : 'hello.pdf' |
| 59 | +}); |
| 60 | + |
| 61 | +//Generate a PDF based on a webview |
| 62 | +var webview = Ti.UI.createWebView({ |
| 63 | + scalesPageToFit : true |
| 64 | +}); |
| 65 | + |
| 66 | +webview.addEventListener('load', function (e) { |
| 67 | + PdfCreator.generatePDFwithWebView({ |
| 68 | + filename : 'hello.pdf', |
| 69 | + webview : webview, |
| 70 | + quality : 100 |
| 71 | + }); |
| 72 | +}); |
| 73 | + |
| 74 | +webview.url = 'www.apple.com'; |
| 75 | +``` |
| 76 | + |
| 77 | +## PDFGeneration lib |
| 78 | + |
| 79 | +### Basic Usage |
| 80 | +* This lib is intended to handle the common use cases for the PDF module creation. Therefore it depends on the `PDFCreator` module. |
| 81 | +* Add `pdfGeneration.js` and `mustache.js` under `app/lib` (for Alloy projects). |
| 82 | +* 2 functions are included to generate the PDF files |
| 83 | + * `generateWithWebView()` - Generates a PDF file based on an HTML File using a webview to load it's data. **It does NOT use `PDFCreator.generatePDFwithWebView()`** |
| 84 | + * `generatePDFWithTemplate()` - Generates a PDF file based on an HTML Template, will load using `mustache.js` |
| 85 | +* Both functions take a set of options to generate the PDF. |
| 86 | + * `htmlFile` - File object to load that includes the HTML file to parse |
| 87 | + * `data` - Dictionary with data to be parsed inside the HTML before generating the PDF |
| 88 | + * `sucessCallback` - Function called when the PDF gets generated |
| 89 | + * `failCallback` - Function called if an error occurs |
| 90 | + |
| 91 | +### Example |
| 92 | +```javascript |
| 93 | +var PdfGeneration = require('pdfGeneration'); |
| 94 | + |
| 95 | +// Workaround to load images |
| 96 | +var imageFile = Ti.Filesystem.getFile(Ti.Filesystem.resourcesDirectory, 'image.jpg'); |
| 97 | +var imgTemp = Ti.Filesystem.createTempFile(); |
| 98 | +imgTemp.write(imageFile.read()); |
| 99 | + |
| 100 | +PdfGeneration.generateWithWebView({ |
| 101 | + // Name of the PDF file to create |
| 102 | + pdfFileName : 'webview', |
| 103 | + // File containing the html to load |
| 104 | + htmlFile : Ti.Filesystem.getFile(Ti.Filesystem.resourcesDirectory, 'webview.html'), |
| 105 | + // A view to contain the Webview (should be inside an opened Window) |
| 106 | + wrapper : $.index, |
| 107 | + // Data to parse |
| 108 | + data : { |
| 109 | + customerName : 'John Doe', |
| 110 | + image : imgTemp.resolve().replace('file:', '') |
| 111 | + }, |
| 112 | + successCallback : function (_data) { |
| 113 | + // The PDF was created |
| 114 | + }, |
| 115 | + failCallback : function (_data) { |
| 116 | + // An error occured |
| 117 | + } |
| 118 | +}); |
| 119 | + |
| 120 | +PdfGeneration.generatePDFWithTemplate({ |
| 121 | + // Name of the PDF file to create |
| 122 | + pdfFileName : 'template', |
| 123 | + // File containing the html to load |
| 124 | + htmlFile : Ti.Filesystem.getFile(Ti.Filesystem.resourcesDirectory, 'template.html'), |
| 125 | + // Data to parse |
| 126 | + data : { |
| 127 | + customerName : 'John Doe', |
| 128 | + image : imgTemp.resolve().replace('file:', '') |
| 129 | + }, |
| 130 | + successCallback : function (_data) { |
| 131 | + // The PDF was created |
| 132 | + }, |
| 133 | + failCallback : function (_data) { |
| 134 | + // An error occured |
| 135 | + } |
| 136 | +}); |
| 137 | +``` |
| 138 | + |
| 139 | +### Notes for loaing PDF files |
| 140 | +* In order to load images, the absolute path for the images is needed under the `src` attribute. |
| 141 | +* CSS styles should be loaded within the HTML file. |
| 142 | +* Only the system fonts are supported. If the `font-face` includes an specific name, it will take more time to load that using `serif` or `sans-serif` |
0 commit comments