Skip to content

Commit 7266824

Browse files
edi9999edi9999
committed
removed unused deps and updated the documentation
1 parent fe54545 commit 7266824

File tree

4 files changed

+30
-321
lines changed

4 files changed

+30
-321
lines changed

‎docs/source/configuration.rst‎

Lines changed: 4 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -12,101 +12,15 @@ It documents the options parameter when you do:
1212

1313
.. code-block:: javascript
1414
15-
new DocxGen(data,options);
15+
var doc=new DocxGen(content);
16+
doc.setOptions(options)
1617
1718
Image Replacing
1819
---------------
1920

20-
The name of this option is `qrCode` (function) (This was a boolean in 0.6.3 and before).
21-
22-
To stay a templating engine, I wanted that DocxTemplater doesn't add an image from scratch, but rather uses an existing image that can be detected, and DocxTemplater will just change the contents of that image, without changing it's style (border, shades, ...). The size of the replaced images will stay the same, ...
23-
24-
So I decided to use the qrCode format, which is a format that lets you identify images by their content.
25-
26-
The option for this is `qrCode` (false for off, a function for on, default off)
27-
28-
The function takes two parameter: The first one is the string that was decoded by the qrcode module, the second the callback.
29-
30-
For example your configuration could be:
31-
32-
.. code-block:: javascript
33-
34-
new DocxGen(data,{qrCode:function(result,callback){
35-
urloptions=(result.parse(path))
36-
options =
37-
hostname:urloptions.hostname
38-
path:urloptions.path
39-
method: 'GET'
40-
rejectUnauthorized:false
41-
errorCallback= (e) ->
42-
throw new Error("Error on HTTPS Call")
43-
reqCallback= (res)->
44-
res.setEncoding('binary')
45-
data = ""
46-
res.on('data', (chunk)->
47-
data += chunk
48-
)
49-
res.on('end', ()->
50-
callback(null,data))
51-
req = http.request(options, reqCallback).on('error',errorCallback)
52-
}})
53-
5421
.. note::
5522

56-
If you don't use that functionality, you should not enable it (you don't have to do anything), because the qrcode module is quite slow.
57-
58-
.. warning::
59-
60-
The qrCode functionality only works for PNG !
61-
They is no support for other file formats yet.
62-
The main problem being that their is no decoder for other file formats in Node.js.
63-
The library https://github.com/zhangyuanwei/node-images does support decoding for more file formats (gif, png, jpeg), but depends on 3 other none node dependencies.
64-
65-
.. warning::
66-
67-
They is a security warning if you use true as the value for qrCode, because this will use the older qrcode loading function.
68-
This function can load any file on the filesystem, with a possible leak in api-keys or whatever you store on docxtemplater's server.
69-
70-
To generate qrcodes with nodejs, you can use for example this script brought by @ssured in issue #69 https://github.com/edi9999/docxtemplater/issues/69
71-
72-
`npm install qr-image canvas`
73-
74-
To install the dependencies of canvas, look here (platform specific)
75-
https://github.com/Automattic/node-canvas/wiki
76-
77-
78-
.. code-block:: javascript
79-
80-
var Canvas, Image, canvas, column, ctx, fs, matrix, qr, qrString, size, textSize, value, x, y, _i, _j, _len, _len1;
81-
qr = require('qr-image');
82-
fs = require('fs');
83-
Canvas = require('canvas');
84-
Image = Canvas.Image;
85-
qrString = 'gen:{image}';
86-
size = 10;
87-
matrix = qr.matrix(qrString);
88-
canvas = new Canvas((2 + 5 + matrix.length) * size, (2 + 5 + matrix.length) * size);
89-
ctx = canvas.getContext('2d');
90-
ctx.fillStyle = '#000';
91-
ctx.fillRect(0, 0, canvas.width, canvas.height);
92-
ctx.fillStyle = '#fff';
93-
ctx.fillRect(1, 1, canvas.width - 2, canvas.height - 2);
94-
ctx.fillStyle = '#000';
95-
for (y = _i = 0, _len = matrix.length; _i < _len; y = ++_i) {
96-
column = matrix[y];
97-
for (x = _j = 0, _len1 = column.length; _j < _len1; x = ++_j) {
98-
value = column[x];
99-
if (value === 1) {
100-
ctx.fillRect((x + 1 + 2.5) * size, (y + 1) * size, size, size);
101-
}
102-
}
103-
}
104-
ctx.font = 4 * size + 'px Helvetica';
105-
ctx.fillStyle = '#000';
106-
textSize = ctx.measureText(qrString);
107-
ctx.fillText(qrString, (canvas.width - textSize.width) / 2, canvas.height - size - textSize.actualBoundingBoxDescent);
108-
canvas.pngStream().pipe(fs.createWriteStream('qr.png'));
109-
23+
The imageReplacing feature has been removed from the main docxtemplater package. This feature will be implemented in the future in an external module.
11024

11125
Custom Parser
11226
--------------
@@ -147,7 +61,7 @@ To use the angular-parser, do the following:
14761
get: tag == '.' ? function(s){ return s;} : expressions.compile(tag)
14862
};
14963
}
150-
new DocxGen(data,{parser:angularParser})
64+
new DocxGen(data).setOptions({parser:angularParser})
15165
15266
.. note::
15367

‎docs/source/full_doc.rst‎

Lines changed: 9 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -15,127 +15,34 @@ Creating a new Docxgen Object
1515
1616
This function returns a new DocxGen Object
1717
18-
new DocxGen(content[,Tags,options])
18+
new DocxGen(content,options)
1919
20-
content:
21-
Type: string
22-
The docx template you want to load as plain text
23-
24-
Tags:
25-
Type: Object {tag_name:tag_replacement} [{}]
26-
Object containing for each tag_name, the replacement for this tag. For example, if you want to replace firstName by David, your Object will be: {"firstName":"David"}
27-
28-
options: object
29-
30-
parser:
31-
Type: function
32-
A custom parser to use. See angular.js like parsing
33-
34-
intelligentTagging:
35-
Type: boolean [false]
36-
If intelligent Tagging is not set to true, when using recursive tags ({#tag} and {/tag}), the system will copy paste what is between the start tag and the endtag, this could basically corrupt the files if recursive tags are used inside tables.
37-
If intelligent Tagging is set to true, and when using recursive tags inside tables, the whole column will be copy pasted.
38-
39-
qrCode:
40-
Type: boolean [false]
41-
If qrCode is set to true, DocxGen will look at all the images to find a Qr-Code. If the Qr-code matches to a URL, this URL will be loaded by ajax (Be aware that the server you want to access needs to allow your request, or it won't work. http://stackoverflow.com/questions/9310112/why-am-i-seeing-an-origin-is-not-allowed-by-access-control-allow-origin-error )
42-
**Important**: the qrCode functionality only works for PNG, I don't think I will enable this for other fileformats in the near future.
43-
44-
localImageCreator
45-
Type: function(arg,callback) [function that returns an arrow]
46-
The function has to be customized only if you want to use the qrCode options (**qrCode=true**). When the qrcode text starts with **gen:**, the image is not going to be loaded by url but DocxGen calls localImageCreator with **arg**=full Text decoded. The callback needs to be called with the image Data:**callback(result)**, in plain/txt format (if you want to create it from a Data-URI, you can use JSZipBase64.decode(data) to decode a Data-URI to plain/txt)
47-
48-
The default localImageCreator returns a red arrow, no matter what the arguments are:
49-
50-
@localImageCreator= (arg,callback) ->
51-
result=JSZipBase64.decode("iVBORw0KGgoAAAANSUhEUgAAABcAAAAXCAIAAABvSEP3AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACXSURBVDhPtY7BDYAwDAMZhCf7b8YMxeCoatOQJhWc/KGxT2zlCyaWcz8Y+X7Bs1TFVJSwIHIYyFkQufWIRVX9cNJyW1QpEo4rixaEe7JuQagAUctb7ZFYFh5MVJPBe84CVBnB42//YsZRgKjFDBVg3cI9WbRwXLktQJX8cNIiFhM1ZuTWk7PIYSBhkVcLzwIiCjCxhCjlAkBqYnqFoQQ2AAAAAElFTkSuQmCC")
52-
53-
[Default Image](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABcAAAAXCAIAAABvSEP3AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACXSURBVDhPtY7BDYAwDAMZhCf7b8YMxeCoatOQJhWc/KGxT2zlCyaWcz8Y+X7Bs1TFVJSwIHIYyFkQufWIRVX9cNJyW1QpEo4rixaEe7JuQagAUctb7ZFYFh5MVJPBe84CVBnB42//YsZRgKjFDBVg3cI9WbRwXLktQJX8cNIiFhM1ZuTWk7PIYSBhkVcLzwIiCjCxhCjlAkBqYnqFoQQ2AAAAAElFTkSuQmCC)
54-
55-
qrFinishedCallBack:
56-
Type: function () [function that console.log(ready)]
57-
This function is called if you specify qrCode argument to true in this constructor, and will be called when all qrCodes have been replaced (because the qrCode replacing functions are **async**)
20+
if content is defined, it will call `.load(content,options)`
5821
5922
6023
Docxgen methods
6124
---------------
6225
6326
.. code-block:: javascript
6427
65-
load(content)
28+
load(content,options)
6629
67-
content:
68-
Type: string
69-
The docx template you want to load as plain text
30+
This will call new JSzip().load(content,options) under the hood. See http://stuk.github.io/jszip/documentation/api_jszip/load.html
31+
You can also pass a JSzip object as the first argument.
7032
71-
loadFromFile(path)
72-
path
73-
Type: string
74-
Loads a docx from a file path
75-
setTags(Tags)
33+
setData(Tags)
7634
7735
Tags:
7836
Type: Object {tag_name:tag_replacement}
7937
Object containing for each tag_name, the replacement for this tag. For example, if you want to replace firstName by David, your Object will be: {"firstName":"David"}
8038
81-
82-
applyTags([Tags])
83-
Tags:
84-
Type: Object {tag_name:tag_replacement}
85-
same as setTags
86-
Default:this.Tags
39+
render()
8740
8841
This function replaces all template variables by their values
8942
90-
output([options])
91-
92-
options: object[{}]
93-
94-
name:
95-
Type:string["output.docx"]
96-
The name of the file that will be outputed (doesnt work in the browser because of dataUri download)
97-
98-
callback:
99-
Type:function
100-
Function that is called without arguments when the output is done. Is used only in Node (because in the browser, the operation is synchronous)
101-
102-
download:
103-
Type:boolean[true]
104-
If download is true, file will be downloaded automatically with data URI.
105-
returns the output file.
106-
107-
type:
108-
Type:string["base64"]
109-
The type of zip to return. The possible values are : (same as in http://stuk.github.io/jszip/ @generate)
110-
base64 (default) : the result will be a string, the binary in a base64 form.
111-
string : the result will be a string in "binary" form, 1 byte per char.
112-
uint8array : the result will be a Uint8Array containing the zip. This requires a compatible browser.
113-
arraybuffer : the result will be a ArrayBuffer containing the zip. This requires a compatible browser.
114-
blob : the result will be a Blob containing the zip. This requires a compatible browser.
115-
nodebuffer : the result will be a nodejs Buffer containing the zip. This requires nodejs.
116-
117-
118-
This function creates the docx file and downloads it on the user's computer. The name of the file is download.docx for Chrome, and some akward file names for Firefox: VEeTHCfS.docx.part.docx, and can't be changed because it is handled by the browser.
119-
For more informations about how to solve this problem, see the **Filename Problems** section on [http://stuk.github.io/jszip/](http://stuk.github.io/jszip/)
120-
121-
Note: All browsers don't support the download of big files with Data URI, so you **should** use the `download` method for files bigger than 100kB data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABcAAAAXCAIAAABvSEP3AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACXSURBVDhPtY7BDYAwDAMZhCf7b8YMxeCoatOQJhWc/KGxT2zlCyaWcz8Y+X7Bs1TFVJSwIHIYyFkQufWIRVX9cNJyW1QpEo4rixaEe7JuQagAUctb7ZFYFh5MVJPBe84CVBnB42//YsZRgKjFDBVg3cI9WbRwXLktQJX8cNIiFhM1ZuTWk7PIYSBhkVcLzwIiCjCxhCjlAkBqYnqFoQQ2AAAAAElFTkSuQmCC
122-
123-
download(swfpath,imgpath[,fileName])
124-
125-
swfpath
126-
Type:string
127-
Path to the swfobject.js in downloadify
128-
129-
imgpath
130-
Type:string
131-
Path to the image of the download button
132-
133-
[fileName]
134-
Type:string
135-
Default:"default.docx"
136-
Name of the file you would like the user to download.
43+
getZip()
13744
138-
This requires to include Downloadify.js, that needs flash version 10. Have a look at the *output* function if you don't want to depend on it. This function has the advantage that it works regardless of the file size
45+
This will return you the zip that represents the docx. You can then call `.generate` on this to generate a buffer, string , ... (see http://stuk.github.io/jszip/documentation/api_jszip/generate.html)
13946
14047
getFullText:([path])
14148

‎docs/source/generate.rst‎

Lines changed: 17 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -11,129 +11,20 @@ Here's a sample code to generate a document:
1111

1212
.. code-block:: javascript
1313
14-
DocxGen=require('docxtemplater'); //Only for Node Usage
15-
new DocxGen().loadFromFile("tagExample.docx",{async:true}).success(function(doc){
16-
doc.setTags({
17-
"first_name":"Hipp",
18-
"last_name":"Edgar",
19-
"phone":"0652455478",
20-
"description":"New Website"
21-
}) //set the templateVariables
22-
doc.applyTags() //apply them (replace all occurences of {first_name} by Hipp, ...)
23-
doc.output() //Output the document using Data-URI
24-
});
25-
26-
27-
The different steps are the following:
28-
29-
Loading a document:
30-
-------------------
31-
32-
A docx can be loaded by it's base64 representation, like this:
33-
34-
.. code-block:: javascript
35-
36-
doc=new DocxGen(base64Data,options);
37-
38-
However, loading the base64Data is not that easy, so I created a wrapper function to load a docx from a file via Ajax.
39-
40-
41-
.. note::
42-
43-
The options parameter are explained in :ref:`configuration`
44-
45-
46-
.. code-block:: javascript
47-
48-
doc=new DocxGen().loadFromFile(documentPath,options);
49-
50-
The documentPath is the path to the document you want to load.
51-
The options are the same as in the constructor function, and I've added the async parameter.
52-
53-
- If async is true, the document is loaded asynchronously and returns a promise (eg you can write .success(callback) to get when the document is loaded)
54-
- If async is false, the document is loaded synchronously and returns the document.
55-
56-
57-
Setting the tags:
58-
-----------------
59-
60-
The tags are the variables that are going to be replaced by their values.
61-
To set them, just use:
62-
63-
.. code-block:: javascript
64-
65-
doc.setTags(tags);
66-
67-
68-
Applying the tags:
69-
------------------
70-
71-
Applying the tags means opening all files that contain text (eg: footer, header, main document), and replace the variables by their values.
72-
73-
74-
.. code-block:: javascript
75-
76-
doc.applyTags(tags)
77-
78-
.. note::
79-
80-
If you specify an argument for the applyTags method, the function setTags(tags) will be called before applying the tags.
81-
82-
Outputing the document:
83-
-----------------------
84-
85-
They are several ways to output the document. The most basic usage is to download the document.
86-
87-
.. code-block:: javascript
88-
89-
doc.output(options)
90-
91-
Depending on your environment, if you don't set any options, this will:
92-
93-
- In the browser: Download the document using DataURI
94-
- In Node: Save the document with the given fileName (output.docx by default)
95-
96-
97-
Here's the different options parameters:
98-
99-
.. code-block:: javascript
100-
101-
name:
102-
Type:string["output.docx"]
103-
The name of the file that will be outputed (doesnt work in the browser because of dataUri download)
104-
105-
callback:
106-
Type:function
107-
Function that is called without arguments when the output is done. Is used only in Node (because in the browser, the operation is synchronous)
108-
109-
download:
110-
Type:boolean[true]
111-
If download is true, file will be downloaded automatically with data URI.
112-
returns the output file.
113-
114-
type:
115-
Type:string["base64"]
116-
The type of zip to return. The possible values are : (same as in http://stuk.github.io/jszip/ @generate)
117-
base64 (default) : the result will be a string, the binary in a base64 form.
118-
string : the result will be a string in "binary" form, 1 byte per char.
119-
uint8array : the result will be a Uint8Array containing the zip. This requires a compatible browser.
120-
arraybuffer : the result will be a ArrayBuffer containing the zip. This requires a compatible browser.
121-
blob : the result will be a Blob containing the zip. This requires a compatible browser.
122-
nodebuffer : the result will be a nodejs Buffer containing the zip. This requires nodejs.
123-
124-
125-
This function creates the docx file and downloads it on the user's computer. The name of the file is download.docx for Chrome, and some akward file names for Firefox: VEeTHCfS.docx.part.docx, and can't be changed because it is handled by the browser.
126-
For more informations about how to solve this problem, see the **Filename Problems** section on [http://stuk.github.io/jszip/](http://stuk.github.io/jszip/)
127-
128-
.. note::
129-
130-
Note: All browsers don't support the download of big files with Data URI, so you **should** use the `download` method for files bigger than 100kB data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABcAAAAXCAIAAABvSEP3AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACXSURBVDhPtY7BDYAwDAMZhCf7b8YMxeCoatOQJhWc/KGxT2zlCyaWcz8Y+X7Bs1TFVJSwIHIYyFkQufWIRVX9cNJyW1QpEo4rixaEe7JuQagAUctb7ZFYFh5MVJPBe84CVBnB42//YsZRgKjFDBVg3cI9WbRwXLktQJX8cNIiFhM1ZuTWk7PIYSBhkVcLzwIiCjCxhCjlAkBqYnqFoQQ2AAAAAElFTkSuQmCC
131-
132-
In Node, to send the document to the client, you can write the following code snippet:
133-
134-
.. code-block:: javascript
135-
136-
out=doc.output({download:false,type:"string"})
137-
res.send(new Buffer(out,"binary"));
138-
139-
14+
//Only for Node Usage
15+
DocxGen=require('docxtemplater');
16+
content=fs.readFileSync(__dirname+"/input.docx","binary")
17+
18+
doc=new DocxGen(content);
19+
doc.setData({
20+
"first_name":"Hipp",
21+
"last_name":"Edgar",
22+
"phone":"0652455478",
23+
"description":"New Website"
24+
}) //set the templateVariables
25+
doc.render() //apply them (replace all occurences of {first_name} by Hipp, ...)
26+
zip=doc.getZip() //Get the zip representation of the docx
27+
28+
//Only for Node Usage
29+
output=zip.generate({type:"base64"})
30+
fs.writeFileSync(__dirname+"/output.docx",output,"binary")

0 commit comments

Comments
 (0)