caracal 1.0.1 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +5 -5
- data/.gitignore +1 -0
- data/CHANGELOG.md +95 -5
- data/README.md +171 -35
- data/caracal.gemspec +4 -4
- data/lib/caracal/core/custom_properties.rb +49 -0
- data/lib/caracal/core/iframes.rb +42 -0
- data/lib/caracal/core/ignorables.rb +47 -0
- data/lib/caracal/core/models/custom_property_model.rb +60 -0
- data/lib/caracal/core/models/iframe_model.rb +148 -0
- data/lib/caracal/core/models/namespace_model.rb +65 -0
- data/lib/caracal/core/models/page_break_model.rb +50 -4
- data/lib/caracal/core/models/page_number_model.rb +50 -24
- data/lib/caracal/core/models/page_size_model.rb +34 -25
- data/lib/caracal/core/models/paragraph_model.rb +11 -4
- data/lib/caracal/core/models/style_model.rb +44 -15
- data/lib/caracal/core/models/table_cell_model.rb +61 -50
- data/lib/caracal/core/models/table_model.rb +1 -1
- data/lib/caracal/core/models/text_model.rb +42 -20
- data/lib/caracal/core/namespaces.rb +89 -0
- data/lib/caracal/core/page_numbers.rb +22 -16
- data/lib/caracal/core/page_settings.rb +18 -16
- data/lib/caracal/document.rb +75 -58
- data/lib/caracal/renderers/content_types_renderer.rb +18 -17
- data/lib/caracal/renderers/core_renderer.rb +1 -1
- data/lib/caracal/renderers/custom_renderer.rb +64 -0
- data/lib/caracal/renderers/document_renderer.rb +205 -118
- data/lib/caracal/renderers/fonts_renderer.rb +2 -2
- data/lib/caracal/renderers/footer_renderer.rb +41 -20
- data/lib/caracal/renderers/numbering_renderer.rb +27 -26
- data/lib/caracal/renderers/package_relationships_renderer.rb +14 -13
- data/lib/caracal/renderers/settings_renderer.rb +5 -5
- data/lib/caracal/renderers/styles_renderer.rb +88 -73
- data/lib/caracal/renderers/xml_renderer.rb +20 -20
- data/lib/caracal/version.rb +1 -1
- data/lib/caracal.rb +11 -2
- data/spec/lib/caracal/core/iframes_spec.rb +29 -0
- data/spec/lib/caracal/core/ignorables_spec.rb +79 -0
- data/spec/lib/caracal/core/models/iframe_model_spec.rb +83 -0
- data/spec/lib/caracal/core/models/image_model_spec.rb +60 -62
- data/spec/lib/caracal/core/models/link_model_spec.rb +12 -11
- data/spec/lib/caracal/core/models/namespace_model_spec.rb +107 -0
- data/spec/lib/caracal/core/models/page_number_model_spec.rb +66 -31
- data/spec/lib/caracal/core/models/page_size_model_spec.rb +42 -32
- data/spec/lib/caracal/core/models/style_model_spec.rb +32 -1
- data/spec/lib/caracal/core/models/table_cell_model_spec.rb +10 -1
- data/spec/lib/caracal/core/models/text_model_spec.rb +18 -10
- data/spec/lib/caracal/core/namespaces_spec.rb +116 -0
- data/spec/lib/caracal/core/page_numbers_spec.rb +32 -23
- data/spec/lib/caracal/core/page_settings_spec.rb +33 -25
- data/spec/lib/caracal/core/relationships_spec.rb +47 -47
- data/spec/support/_fixtures/snippet.docx +0 -0
- metadata +28 -8
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 5e775f349922d6591347d38de57b4211581c75d1b1b1fe08f67d887d68833a6b
|
|
4
|
+
data.tar.gz: 635e787f52491c8f06ff3dcb32cd0d573a4abc7b44aa693dc8421a74108942e0
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 20b0fd3d486e99180c7a871610ba7d619d75cefc2116cb54e3920ed8bf2c036a6d93789df6570dde608cc68ece8693e272da093ad5ac26dad8962804c35f2171
|
|
7
|
+
data.tar.gz: d69653b8075ec87ab191cf07d4bc1090fb0822b3ae05a1f24d9edfd8ac3476efa2291c46a21c8194dca4d99505fee569cf1ddaf85a4f03dce7ae1de3857cc486
|
data/.gitignore
CHANGED
data/CHANGELOG.md
CHANGED
|
@@ -1,7 +1,98 @@
|
|
|
1
|
+
#### v1.2.0
|
|
2
|
+
|
|
3
|
+
* Enhancements
|
|
4
|
+
* Added colspan and rowspan functionality to table styling feature. (@ViktorKopychko)
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
#### v1.1.2
|
|
8
|
+
|
|
9
|
+
* Enhancements
|
|
10
|
+
* Added font size options for page numbers. (@cfacello)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
#### v1.1.1
|
|
14
|
+
|
|
15
|
+
* Enhancements
|
|
16
|
+
* Added character styles. (@xerespm)
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
#### v1.1.0
|
|
20
|
+
|
|
21
|
+
* Enhancements
|
|
22
|
+
* Corrected how renderers output namespaced nodes to ensure jruby compliance. (HUGE thank you to @henrychung for researching and implementing this).
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
#### v1.0.13
|
|
26
|
+
|
|
27
|
+
* Bug Fixes
|
|
28
|
+
* Corrected bug where lists were no longer multi-line. (@jdugan h/t @StochasticSpring).
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
#### v1.0.12
|
|
32
|
+
|
|
33
|
+
* Bug Fixes
|
|
34
|
+
* Removed unintended use of Active Support method in footer renderer. (@jdugan).
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
#### v1.0.11
|
|
38
|
+
|
|
39
|
+
* Bug Fixes
|
|
40
|
+
* Cleaned up experimental feature for iframes. (@jdugan).
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
#### v1.0.10
|
|
44
|
+
|
|
45
|
+
* Enhancements
|
|
46
|
+
* Added experimental feature for iframes. (@jdugan).
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
#### v1.0.8
|
|
50
|
+
|
|
51
|
+
* Enhancements
|
|
52
|
+
* Added indentation controls to paragraph commands (@avolochnev).
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
#### v1.0.7
|
|
56
|
+
|
|
57
|
+
* Enhancements
|
|
58
|
+
* Added an :orientation option to :page_size so print jobs work as expected (@jdugan h/t @swedishpotato).
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
#### v1.0.6
|
|
62
|
+
|
|
63
|
+
* Bug Fixes
|
|
64
|
+
* Changed Paragraph and Table Cell Models slightly to allow syntax flexibility with respect to options (@jdugan).
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
#### v1.0.5
|
|
68
|
+
|
|
69
|
+
* Enhancements
|
|
70
|
+
* Added vertical alignment (@ykonovets).
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
#### v1.0.4
|
|
74
|
+
|
|
75
|
+
* Enhancements
|
|
76
|
+
* Changed tilt dependency to be less restrictive (@jdugan).
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
#### v1.0.3
|
|
80
|
+
|
|
81
|
+
* Enhancements
|
|
82
|
+
* Added custom properties (@davidtolsma).
|
|
83
|
+
* Added page breaks to paragraph model sub-functions (@jdugan).
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
#### v1.0.2
|
|
87
|
+
|
|
88
|
+
* Enhancements
|
|
89
|
+
* Corrected image markup to support Word 2007 (@Alnoroid).
|
|
90
|
+
|
|
91
|
+
|
|
1
92
|
#### v0.3.0
|
|
2
93
|
|
|
3
94
|
* Deprecations
|
|
4
|
-
* The :style attribute is no longer allowed on text and link commands. Use :font, :size, etc. instead.
|
|
95
|
+
* The :style attribute is no longer allowed on text and link commands. Use :font, :size, etc. instead (@jdugan).
|
|
5
96
|
|
|
6
97
|
|
|
7
98
|
#### v0.2.1
|
|
@@ -16,15 +107,14 @@
|
|
|
16
107
|
* Enhancements
|
|
17
108
|
* Implemented true line breaks within paragraphs (@Linuus).
|
|
18
109
|
* Converted paragraph command to accept/allow blank content (@Linuus).
|
|
19
|
-
* Allowed :top and :bottom attributes to be set on default paragraph style (@
|
|
110
|
+
* Allowed :top and :bottom attributes to be set on default paragraph style (@jdugan).
|
|
20
111
|
|
|
21
112
|
|
|
22
113
|
* Deprecations
|
|
23
|
-
* Line breaks are no longer allowed at the document level. Use blank paragraphs instead.
|
|
24
|
-
|
|
114
|
+
* Line breaks are no longer allowed at the document level. Use blank paragraphs instead (@jdugan).
|
|
25
115
|
|
|
26
116
|
|
|
27
117
|
#### v0.1.x
|
|
28
118
|
|
|
29
119
|
* Enhancements
|
|
30
|
-
* Initial commits. (@
|
|
120
|
+
* Initial commits. (@jdugan)
|
data/README.md
CHANGED
|
@@ -1,6 +1,5 @@
|
|
|
1
1
|
# Caracal
|
|
2
2
|
|
|
3
|
-
[](https://travis-ci.org/trade-informatics/caracal)
|
|
4
3
|
[](https://rubygems.org/gems/caracal)
|
|
5
4
|
|
|
6
5
|
|
|
@@ -12,6 +11,9 @@ Caracal is not a magical HTML to Word translator. Instead, it is a markup langua
|
|
|
12
11
|
|
|
13
12
|
Or, said differently, if you use [Prawn](https://github.com/prawnpdf/prawn) for PDF generation, you'll probably like Caracal. Only you'll probably like it better. :)
|
|
14
13
|
|
|
14
|
+
Please see the [caracal-example](https://github.com/trade-informatics/caracal-example) repository for
|
|
15
|
+
a working demonstration of the library's capabilities.
|
|
16
|
+
|
|
15
17
|
|
|
16
18
|
## Teaser
|
|
17
19
|
|
|
@@ -42,7 +44,7 @@ Caracal::Document.save 'example.docx' do |docx|
|
|
|
42
44
|
li 'Item 2'
|
|
43
45
|
end
|
|
44
46
|
docx.p
|
|
45
|
-
docx.img
|
|
47
|
+
docx.img 'https://www.example.com/logo.png', width: 500, height: 300
|
|
46
48
|
end
|
|
47
49
|
```
|
|
48
50
|
|
|
@@ -81,12 +83,14 @@ You may not know that .docx files are simply a zipped collection of XML document
|
|
|
81
83
|
|
|
82
84
|
For each Caracal request, the following document structure will be created and zipped into the final output file:
|
|
83
85
|
|
|
86
|
+
```
|
|
84
87
|
example.docx
|
|
85
88
|
|- _rels
|
|
86
89
|
|- .rels
|
|
87
90
|
|- docProps
|
|
88
91
|
|- app.xml
|
|
89
92
|
|- core.xml
|
|
93
|
+
|- custom.xml
|
|
90
94
|
|- word
|
|
91
95
|
|- _rels
|
|
92
96
|
|- document.xml.rels
|
|
@@ -101,6 +105,7 @@ For each Caracal request, the following document structure will be created and z
|
|
|
101
105
|
|- settings.xml
|
|
102
106
|
|- styles.xml
|
|
103
107
|
|- [Content_Types].xml
|
|
108
|
+
```
|
|
104
109
|
|
|
105
110
|
|
|
106
111
|
## File Descriptions
|
|
@@ -116,6 +121,9 @@ Specifies the name of the application that generated the document. *This file is
|
|
|
116
121
|
**docProps/core.xml**
|
|
117
122
|
Specifies the title of the document. *This file is generated automatically by the library based on other user directives.*
|
|
118
123
|
|
|
124
|
+
**docProps/custom.xml**
|
|
125
|
+
Specifies the custom document properties. *This file is generated automatically by the library based on other user directives.*
|
|
126
|
+
|
|
119
127
|
**word/_rels/document.xml.rels**
|
|
120
128
|
Defines an internal identifier and type with all external content items (images, links, etc). *This file is generated automatically by the library based on other user directives.*
|
|
121
129
|
|
|
@@ -164,14 +172,14 @@ A twip is 1/20 of a point. Word documents are printed at 72dpi. 1in == 72pt ==
|
|
|
164
172
|
In Word documents, pixels are equivalent to points.
|
|
165
173
|
|
|
166
174
|
**EMUs (English Metric Unit)**
|
|
167
|
-
EMUs are a virtual unit designed to facilitate the smooth conversion between inches,
|
|
175
|
+
EMUs are a virtual unit designed to facilitate the smooth conversion between inches, millimeters, and pixels for images and vector graphics. 1in == 914400 EMUs == 72dpi x 100 x 254.
|
|
168
176
|
|
|
169
177
|
At present, Caracal expects values to be specified in whichever unit OOXML requires. This is admittedly difficult for new Caracal users. Eventually, we'll probably implement a utility object under the hood to convert user-specified units into the format expected by OOXML.
|
|
170
178
|
|
|
171
179
|
|
|
172
180
|
## Syntax Flexibility
|
|
173
181
|
|
|
174
|
-
Generally speaking, Caracal commands will accept instructions via any combination of a parameters hash and/or a block. For example, all of the
|
|
182
|
+
Generally speaking, Caracal commands will accept instructions via any combination of a parameters hash and/or a block. For example, all of the following commands are equivalent.
|
|
175
183
|
|
|
176
184
|
```ruby
|
|
177
185
|
docx.style id: 'special', name: 'Special', size: 24, bold: true
|
|
@@ -247,13 +255,16 @@ docx.name # => 'example_document.docx'
|
|
|
247
255
|
### Page Size
|
|
248
256
|
|
|
249
257
|
Page dimensions can be set using the `page_size` method. The method accepts two parameters for controlling the width and height of the document.
|
|
258
|
+
It also accepts a third parameter for setting the page orientation. If you want landscape orientation, you need to change both the page
|
|
259
|
+
dimensions and the orientation explicitly.
|
|
250
260
|
|
|
251
261
|
*Page size defaults to United States standard A4, portrait dimensions (8.5in x 11in).*
|
|
252
262
|
|
|
253
263
|
```ruby
|
|
254
264
|
docx.page_size do
|
|
255
|
-
width
|
|
256
|
-
height
|
|
265
|
+
width 15840 # sets the page width. units in twips.
|
|
266
|
+
height 12240 # sets the page height. units in twips.
|
|
267
|
+
orientation :landscape # sets the printer orientation. accepts :portrait and :landscape.
|
|
257
268
|
end
|
|
258
269
|
```
|
|
259
270
|
|
|
@@ -289,16 +300,22 @@ docx.page # starts a new page.
|
|
|
289
300
|
|
|
290
301
|
### Page Numbers
|
|
291
302
|
|
|
292
|
-
Page numbers can be added to the footer via the `page_numbers` method. The method accepts
|
|
303
|
+
Page numbers can be added to the footer via the `page_numbers` method. The method accepts optional parameters for controlling the alignment, label and size of the text.
|
|
293
304
|
|
|
294
305
|
*Page numbers are turned off by default.*
|
|
295
306
|
|
|
296
307
|
```ruby
|
|
297
308
|
docx.page_numbers true do
|
|
298
|
-
align
|
|
309
|
+
align :right # sets the alignment. accepts :left, :center, and :right.
|
|
310
|
+
label 'Page' # sets the text that will go to the left of the page number. Defaults to nil.
|
|
311
|
+
size: 24 # sets the label and number size simultaneously. units in half points.
|
|
312
|
+
label_size: 24 # sets the label size only. units in half points.
|
|
313
|
+
number_size: 20 # sets the number size only. units in half points.
|
|
299
314
|
end
|
|
300
315
|
```
|
|
301
316
|
|
|
317
|
+
The `size` option and the `label_size` and `number_size` options are mutually exclusive.
|
|
318
|
+
|
|
302
319
|
|
|
303
320
|
### Fonts
|
|
304
321
|
|
|
@@ -319,19 +336,23 @@ Paragraph style classes can be defined using the `style` method. The method acc
|
|
|
319
336
|
|
|
320
337
|
```ruby
|
|
321
338
|
docx.style do
|
|
322
|
-
id
|
|
323
|
-
name
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
339
|
+
id 'Heading1' # sets the internal identifier for the style.
|
|
340
|
+
name 'heading 1' # sets the friendly name of the style.
|
|
341
|
+
type 'paragraph' # sets the style type. accepts `paragraph` or `character`
|
|
342
|
+
font 'Palantino' # sets the font family.
|
|
343
|
+
color '333333' # sets the text color. accepts hex RGB.
|
|
344
|
+
size 28 # sets the font size. units in half points.
|
|
345
|
+
bold false # sets the font weight.
|
|
346
|
+
italic false # sets the font style.
|
|
347
|
+
underline false # sets whether or not to underline the text.
|
|
348
|
+
caps false # sets whether or not text should be rendered in all capital letters.
|
|
349
|
+
align :left # sets the alignment. accepts :left, :center, :right, and :both.
|
|
350
|
+
line 360 # sets the line height. units in twips.
|
|
351
|
+
top 100 # sets the spacing above the paragraph. units in twips.
|
|
352
|
+
bottom 0 # sets the spacing below the paragraph. units in twips.
|
|
353
|
+
indent_left 360 # sets the left indent. units in twips.
|
|
354
|
+
indent_right 360 # sets the rights indent. units in twips.
|
|
355
|
+
indent_first 720 # sets the first line indent. units in twips.
|
|
335
356
|
end
|
|
336
357
|
```
|
|
337
358
|
|
|
@@ -347,10 +368,34 @@ Caracal establishes a standard set of default styles for every document. Default
|
|
|
347
368
|
* Heading5
|
|
348
369
|
* Heading6
|
|
349
370
|
|
|
371
|
+
Styles are declared as `paragraph` by default. If you need to adjust inline text styles repeatedly, you might
|
|
372
|
+
benefit from defining a `character` style. Paragraph styles affects all text runs within a paragraph; character styles
|
|
373
|
+
are used to style individual runs within a larger text block.
|
|
374
|
+
|
|
375
|
+
One-off inline text styling can also be accomplished by passing the `text` command override arguments (see below).
|
|
376
|
+
|
|
377
|
+
|
|
378
|
+
### Custom Properties
|
|
379
|
+
|
|
380
|
+
Custom document properties can be defined using the `custom_property` method. The method accepts a few required parameters to control the definition of the custom property.
|
|
381
|
+
|
|
382
|
+
```ruby
|
|
383
|
+
docx.custom_property do
|
|
384
|
+
name 'property name 1' # sets the name of the custom property.
|
|
385
|
+
value 'test' # sets the value of the custom property.
|
|
386
|
+
type :text # sets the property type. accepts :text, :number, :date, :boolean.
|
|
387
|
+
end
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
The `name`, `value`, and `height` attributes are required. If any of the attributes are missing, the custom property will not be created.
|
|
391
|
+
|
|
392
|
+
A document may have zero or many custom properties. Each custom property's `name` should be unique with its `type`.
|
|
393
|
+
|
|
394
|
+
|
|
350
395
|
|
|
351
396
|
### Paragraphs
|
|
352
397
|
|
|
353
|
-
Paragraph text can be added using the `p` method. The method accepts several optional parameters for controlling the style and behavior of the
|
|
398
|
+
Paragraph text can be added using the `p` method. The method accepts several optional parameters for controlling the style and behavior of the paragraph.
|
|
354
399
|
|
|
355
400
|
In its simple form, a paragraph accepts a text string and formatting options.
|
|
356
401
|
|
|
@@ -360,14 +405,15 @@ docx.p 'Sample text.'
|
|
|
360
405
|
docx.p 'Sample text.', style: 'custom_style'
|
|
361
406
|
|
|
362
407
|
docx.p 'Sample text.' do
|
|
363
|
-
style
|
|
364
|
-
align
|
|
365
|
-
color
|
|
366
|
-
size
|
|
367
|
-
bold
|
|
368
|
-
italic
|
|
369
|
-
underline
|
|
370
|
-
bgcolor
|
|
408
|
+
style 'custom_style' # sets the paragraph style. generally used at the exclusion of other attributes.
|
|
409
|
+
align :left # sets the alignment. accepts :left, :center, :right, and :both.
|
|
410
|
+
color '333333' # sets the font color.
|
|
411
|
+
size 32 # sets the font size. units in 1/2 points.
|
|
412
|
+
bold true # sets whether or not to render the text with a bold weight.
|
|
413
|
+
italic false # sets whether or not render the text in italic style.
|
|
414
|
+
underline false # sets whether or not to underline the text.
|
|
415
|
+
bgcolor 'cccccc' # sets the background color.
|
|
416
|
+
vertical_align 'superscript' # sets the vertical alignment.
|
|
371
417
|
end
|
|
372
418
|
```
|
|
373
419
|
|
|
@@ -380,7 +426,8 @@ docx.p do
|
|
|
380
426
|
text ' to something awesome', font: 'Courier New', color: '555555', size: 32, bold: true, italic: true, underline: true, bgcolor: 'cccccc'
|
|
381
427
|
text '.'
|
|
382
428
|
br
|
|
383
|
-
text 'This text follows a line break.'
|
|
429
|
+
text 'This text follows a line break and uses a character style instead of overrides.', style: 'MyCharStyle'
|
|
430
|
+
page
|
|
384
431
|
end
|
|
385
432
|
```
|
|
386
433
|
|
|
@@ -533,7 +580,7 @@ Images can be added by using the `img` method. The method accepts several optio
|
|
|
533
580
|
*Caracal will automatically embed the image in the Word document.*
|
|
534
581
|
|
|
535
582
|
```ruby
|
|
536
|
-
docx.img
|
|
583
|
+
docx.img 'https://www.example.com/logo.png' do
|
|
537
584
|
data raw_data # sets the file data directly instead of opening the url
|
|
538
585
|
width 396 # sets the image width. units specified in pixels.
|
|
539
586
|
height 216 # sets the image height. units specified in pixels.
|
|
@@ -562,7 +609,7 @@ docx.table [['Header 1','Header 2'],['Cell 1', 'Cell 2']] do
|
|
|
562
609
|
border_color '666666' # sets the border color. defaults to 'auto'.
|
|
563
610
|
border_line :single # sets the border style. defaults to :single. see OOXML docs for details.
|
|
564
611
|
border_size 4 # sets the border width. defaults to 0. units in twips.
|
|
565
|
-
border_spacing 4 # sets the spacing around the border.
|
|
612
|
+
border_spacing 4 # sets the spacing around the border. defaults to 0. units in twips.
|
|
566
613
|
end
|
|
567
614
|
```
|
|
568
615
|
|
|
@@ -592,13 +639,24 @@ docx.table [['Header 1','Header 2'],['Cell 1', 'Cell 2']], border_size: 4 do
|
|
|
592
639
|
end
|
|
593
640
|
```
|
|
594
641
|
|
|
642
|
+
It is possible to merge cells vertically and horizontally using the `rowspan` and `colspan` options in `cell_style` method e.g.
|
|
643
|
+
|
|
644
|
+
```ruby
|
|
645
|
+
docx.table [['11', '1213', '14'], ['21', '22', '23', '24']] do
|
|
646
|
+
cell_style rows[0][0], rowspan: 2
|
|
647
|
+
cell_style rows[0][1], colspan: 2
|
|
648
|
+
cell_style rows[0][2], rowspan: 2
|
|
649
|
+
end
|
|
650
|
+
```
|
|
651
|
+
|
|
652
|
+
*Note: content of cells 21 and 24 will disappear*
|
|
595
653
|
|
|
596
654
|
### Table Cells
|
|
597
655
|
|
|
598
656
|
If your table contains more complex data (multiple paragraphs, images, lists, etc.), you will probably want to instantiate your `TableCellModel` instances directly. With the exception of page breaks, table cells can contain anything the document can contain, including another table.
|
|
599
657
|
|
|
600
658
|
```ruby
|
|
601
|
-
c1 = Caracal::Core::Models
|
|
659
|
+
c1 = Caracal::Core::Models::TableCellModel.new do
|
|
602
660
|
background 'cccccc' # sets the background color. defaults to 'ffffff'.
|
|
603
661
|
margins do
|
|
604
662
|
top # sets the top margin. defaults to 0. units in twips.
|
|
@@ -609,7 +667,7 @@ c1 = Caracal::Core::Models:TableCellModel.new do
|
|
|
609
667
|
|
|
610
668
|
p 'This is a sentence above an image.'
|
|
611
669
|
p
|
|
612
|
-
img
|
|
670
|
+
img 'https://www.example.com/logo.png', width: 200, height: 100
|
|
613
671
|
end
|
|
614
672
|
```
|
|
615
673
|
|
|
@@ -641,6 +699,36 @@ end
|
|
|
641
699
|
```
|
|
642
700
|
|
|
643
701
|
|
|
702
|
+
## Experimental Features
|
|
703
|
+
|
|
704
|
+
### IFrames
|
|
705
|
+
|
|
706
|
+
You can include an external Word document into your working Caracal document by specifying a URL or by supplying the data directly.
|
|
707
|
+
|
|
708
|
+
*It should be noted that the metaphor here is imperfect. Caracal fully includes the external file at the time of insertion. Further changes to the external file will not be reflected in your Caracal output.*
|
|
709
|
+
|
|
710
|
+
```ruby
|
|
711
|
+
# this example loads the file from the internet
|
|
712
|
+
docx.iframe url: 'http://www.some-website.org/snippet.docx'
|
|
713
|
+
|
|
714
|
+
# this example loads the data directly
|
|
715
|
+
docx.iframe data: File.read('my/path/to/snippet.docx')
|
|
716
|
+
```
|
|
717
|
+
|
|
718
|
+
Caracal is pretty smart about including the external document, at least as it relates to images. As long as the external
|
|
719
|
+
document only uses the feature set Caracal supports natively, you should be okay.
|
|
720
|
+
|
|
721
|
+
But if the external document uses more advanced Word features, the `iframe` directive may or may not work. Again, a
|
|
722
|
+
Word document is really just a dozen or so XML files zipped up with the extension `.docx`. Most of the commands you issue in a Word document only add OOXML to one of these internal files. But some commands--like inserting an image--modify several of
|
|
723
|
+
the internal files. So, when you include an external file, what Caracal is doing under the hood is grabbing the contents
|
|
724
|
+
of the main internal XML file and copying that OOXML into the Caracal document's main internal file. Caracal is smart enough
|
|
725
|
+
to look for any images in the external file and make the corresponding entries in its own internal files, but if other
|
|
726
|
+
advanced features of Word require similar adjustments, Caracal won't know to do that. Probably those advanced features
|
|
727
|
+
will not operate as expected in the parent Caracal document.
|
|
728
|
+
|
|
729
|
+
Again, this feature is considered experimental. Use at your own risk/discretion.
|
|
730
|
+
|
|
731
|
+
|
|
644
732
|
## Template Rendering
|
|
645
733
|
|
|
646
734
|
Caracal includes [Tilt](https://github.com/rtomayko/tilt) integration to facilitate its inclusion in other frameworks.
|
|
@@ -648,6 +736,54 @@ Caracal includes [Tilt](https://github.com/rtomayko/tilt) integration to facilit
|
|
|
648
736
|
Rails integration can be added via the [Caracal-Rails](https://github.com/trade-informatics/caracal-rails) gem.
|
|
649
737
|
|
|
650
738
|
|
|
739
|
+
## Using Variables
|
|
740
|
+
|
|
741
|
+
Lexical scope is a pretty big challenge for Caracal and it often confuses new users. This [closed issue](https://github.com/trade-informatics/caracal/issues/71) covers the discussion both from the user and library persepctive.
|
|
742
|
+
|
|
743
|
+
|
|
744
|
+
## Filing an Issue
|
|
745
|
+
|
|
746
|
+
Caracal was written for and tested against Word 2010, 2013, and Office365. It should also open in LibreOffice
|
|
747
|
+
with high fidelity.
|
|
748
|
+
|
|
749
|
+
|
|
750
|
+
### Older Versions
|
|
751
|
+
If you are using a version of Word that predates 2010, Caracal may or may not work for you. (Probably it won't.)
|
|
752
|
+
We don't ever plan to support versions before 2010, but if you choose to embark on that endeavor, we'd be
|
|
753
|
+
happy to answer questions and provide what guidance we can. We just won't write any code in that direction.
|
|
754
|
+
|
|
755
|
+
|
|
756
|
+
### Newer Versions
|
|
757
|
+
|
|
758
|
+
For those using reasonably current versions of Word, please consider the following:
|
|
759
|
+
|
|
760
|
+
- Before you file an issue, please run the example Caracal project [caracal-example](https://github.com/trade-informatics/caracal-example) in your development environment and
|
|
761
|
+
check the output. This project implements nearly every feature Caracal supports and renders the expected output
|
|
762
|
+
correctly. It can be thought of as a canonical implementation of the library.
|
|
763
|
+
|
|
764
|
+
- If you don't see your issue in the example project's implementation of the same feature, chances are you
|
|
765
|
+
made a mistake in your document's syntax or have an environment-specific, non-caracal problem.
|
|
766
|
+
|
|
767
|
+
- If you do see the same behavior in the example project, you've probably uncovered a variance in the way
|
|
768
|
+
your particular permutation of Windows/Word interprets the OOXML.
|
|
769
|
+
|
|
770
|
+
|
|
771
|
+
### How to Work on a Problem
|
|
772
|
+
|
|
773
|
+
Caracal is essentially an exercise in reverse engineering OOXML output. When developing features, we
|
|
774
|
+
typically start by building the simplest Word document we can that includes the desired behavior.
|
|
775
|
+
Then, we change the document extension to .zip, extract the archive, and inspect the resulting OOXML.
|
|
776
|
+
Finally, we teach the corresponding renderer to output that OOXML.
|
|
777
|
+
|
|
778
|
+
It's a tedious process, but it's not nearly as tedious as learning the entire OOXML specification.
|
|
779
|
+
|
|
780
|
+
The downside is Word changes its expectations about OOXML format with each version, so it can be a bit
|
|
781
|
+
of a balancing act to get the OOXML structured for acceptance by all supported versions.
|
|
782
|
+
|
|
783
|
+
Ultimately, we'll probably need to implement version-specific renderers (i.e., a set of renderers
|
|
784
|
+
for 2010/2013, a set for 2016, etc.).
|
|
785
|
+
|
|
786
|
+
|
|
651
787
|
## Contributing
|
|
652
788
|
|
|
653
789
|
1. Fork it ( https://github.com/trade-informatics/caracal/fork )
|
data/caracal.gemspec
CHANGED
|
@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
|
|
|
8
8
|
spec.version = Caracal::VERSION
|
|
9
9
|
spec.authors = ['Trade Infomatics', 'John Dugan']
|
|
10
10
|
spec.email = ['jpdugan@gmail.com']
|
|
11
|
-
spec.summary = %q{ Fast, professional
|
|
12
|
-
spec.description = %q{ Caracal is a pure Ruby
|
|
11
|
+
spec.summary = %q{ Fast, professional Microsoft Word (docx) writer for Ruby. }
|
|
12
|
+
spec.description = %q{ Caracal is a pure Ruby Microsoft Word generation library that produces professional quality MSWord documents (docx) using a simple, HTML-style DSL. }
|
|
13
13
|
spec.homepage = 'https://github.com/trade-informatics/caracal'
|
|
14
14
|
spec.license = 'MIT'
|
|
15
15
|
|
|
@@ -20,8 +20,8 @@ Gem::Specification.new do |spec|
|
|
|
20
20
|
|
|
21
21
|
spec.add_dependency 'nokogiri', '~> 1.6'
|
|
22
22
|
spec.add_dependency 'rubyzip', '~> 1.1'
|
|
23
|
-
spec.add_dependency 'tilt', '
|
|
24
|
-
|
|
23
|
+
spec.add_dependency 'tilt', '>= 1.4'
|
|
24
|
+
|
|
25
25
|
spec.add_development_dependency 'bundler', '~> 1.3'
|
|
26
26
|
spec.add_development_dependency 'rake', '~> 10.0'
|
|
27
27
|
spec.add_development_dependency 'rspec', '~> 3.0'
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
require 'caracal/core/models/custom_property_model'
|
|
2
|
+
require 'caracal/errors'
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
module Caracal
|
|
6
|
+
module Core
|
|
7
|
+
|
|
8
|
+
# This module encapsulates all the functionality related to setting the
|
|
9
|
+
# document's custom properties.
|
|
10
|
+
#
|
|
11
|
+
module CustomProperties
|
|
12
|
+
def self.included(base)
|
|
13
|
+
base.class_eval do
|
|
14
|
+
|
|
15
|
+
#-------------------------------------------------------------
|
|
16
|
+
# Public Methods
|
|
17
|
+
#-------------------------------------------------------------
|
|
18
|
+
|
|
19
|
+
# This method controls the custom properties.
|
|
20
|
+
#
|
|
21
|
+
def custom_property(options={}, &block)
|
|
22
|
+
model = Caracal::Core::Models::CustomPropertyModel.new(options, &block)
|
|
23
|
+
if model.valid?
|
|
24
|
+
register_property(model)
|
|
25
|
+
end
|
|
26
|
+
model
|
|
27
|
+
end
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
#============== GETTERS =============================
|
|
31
|
+
|
|
32
|
+
def custom_props
|
|
33
|
+
@custom_props ||= []
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
#============== REGISTRATION ========================
|
|
38
|
+
|
|
39
|
+
def register_property(model)
|
|
40
|
+
custom_props << model
|
|
41
|
+
model
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
end
|
|
45
|
+
end
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
end
|
|
49
|
+
end
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
require 'caracal/core/models/iframe_model'
|
|
2
|
+
require 'caracal/errors'
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
module Caracal
|
|
6
|
+
module Core
|
|
7
|
+
|
|
8
|
+
# This module encapsulates all the functionality related to inserting
|
|
9
|
+
# word document snippets into the document.
|
|
10
|
+
#
|
|
11
|
+
module IFrames
|
|
12
|
+
def self.included(base)
|
|
13
|
+
base.class_eval do
|
|
14
|
+
|
|
15
|
+
#-------------------------------------------------------------
|
|
16
|
+
# Public Methods
|
|
17
|
+
#-------------------------------------------------------------
|
|
18
|
+
|
|
19
|
+
def iframe(options={}, &block)
|
|
20
|
+
model = Caracal::Core::Models::IFrameModel.new(options, &block)
|
|
21
|
+
if model.valid?
|
|
22
|
+
model.preprocess!
|
|
23
|
+
model.namespaces.each do |(prefix, href)|
|
|
24
|
+
namespace({ prefix: prefix, href: href })
|
|
25
|
+
end
|
|
26
|
+
model.ignorables.each do |prefix|
|
|
27
|
+
ignorable(prefix)
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
contents << model
|
|
31
|
+
else
|
|
32
|
+
raise Caracal::Errors::InvalidModelError, 'IFrameModel requires either the :url or :data argument.'
|
|
33
|
+
end
|
|
34
|
+
model
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
end
|
|
38
|
+
end
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
end
|
|
42
|
+
end
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
module Caracal
|
|
2
|
+
module Core
|
|
3
|
+
|
|
4
|
+
# This module encapsulates all the functionality related to registering and
|
|
5
|
+
# retrieving ignorable namespaces.
|
|
6
|
+
#
|
|
7
|
+
module Ignorables
|
|
8
|
+
def self.included(base)
|
|
9
|
+
base.class_eval do
|
|
10
|
+
|
|
11
|
+
#-------------------------------------------------------------
|
|
12
|
+
# Public Methods
|
|
13
|
+
#-------------------------------------------------------------
|
|
14
|
+
|
|
15
|
+
#============== ATTRIBUTES ==========================
|
|
16
|
+
|
|
17
|
+
def ignorable(prefix)
|
|
18
|
+
register_ignorable(prefix)
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
#============== GETTERS =============================
|
|
23
|
+
|
|
24
|
+
def ignorables
|
|
25
|
+
@ignorables ||= []
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
#============== REGISTRATION ========================
|
|
30
|
+
|
|
31
|
+
def register_ignorable(prefix)
|
|
32
|
+
unless ignorables.include?(prefix)
|
|
33
|
+
ignorables << prefix
|
|
34
|
+
prefix
|
|
35
|
+
end
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
def unregister_ignorable(prefix)
|
|
39
|
+
ignorables.delete(prefix)
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
end
|
|
43
|
+
end
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
end
|
|
47
|
+
end
|