README.md in sablon-0.1.1 vs README.md in sablon-0.2.0
- old
+ new
@@ -1,22 +1,23 @@
# Sablon
-[](http://badge.fury.io/rb/sablon) [](https://travis-ci.org/senny/sablon)
+[](http://badge.fury.io/rb/sablon)
+[](https://travis-ci.org/senny/sablon)
Is a document template processor for Word `docx` files. It leverages Word's
built-in formatting and layouting capabilities to make template creation easy
and efficient.
-*Note: Sablon is still in early development. Please report if you encounter any issues along the way.*
#### Table of Contents
* [Installation](#installation)
* [Usage](#usage)
* [Writing Templates](#writing-templates)
* [Content Insertion](#content-insertion)
* [WordProcessingML](#wordprocessingml)
* [HTML](#html)
+ * [Images (Beta)](#images-beta)
* [Conditionals](#conditionals)
* [Loops](#loops)
* [Nesting](#nesting)
* [Comments](#comments)
* [Configuration (Beta)](#configuration-beta)
@@ -223,27 +224,56 @@
The full Open Office XML specification used to develop the HTML converter
can be found [here](https://www.ecma-international.org/publications/standards/Ecma-376.htm) (3rd Edition).
-The example above shows an HTML insertion operation that will replace the entire paragraph. In the same fashion as WordML, inline HTML insertion is possible where only the merge field is replaced as long as only "inline" elements are used. "Inline" in this context does not necessarily mean the same thing as it does in CSS, in this case it means that once the HTML is converted to WordML only valid children of a paragraph (w:p) tag exist. Unlike WordML insertion plain text can be used without being wrapped in tags when working with HTML, see the example below:
+The example above shows an HTML insertion operation that will replace the entire paragraph. In the same fashion as WordML, inline HTML insertion is possible where only the merge field is replaced as long as only "inline" elements are used. "Inline" in this context does not necessarily mean the same thing as it does in CSS, in this case it means that once the HTML is converted to WordML only valid children of a paragraph (w:p) tag exist. As with WordML all plain text needs to be wrapped in a HTML tag. A simple `<span>..</span>` tag enclosing all other elements will suffice. See the example below:
```ruby
inline_html = <<-HTML.strip
- This text can contain <em>additional formatting</em> according to the
+ <span>This text can contain <em>additional formatting</em> according to the
<strong>HTML</strong> specification. As well as links to external
<a href="https://github.com/senny/sablon">websites</a>, don't forget
- the "http/https" bit.
+ the "http/https" bit.</span>
HTML
context = {
article: Sablon.content(:html, inline_html) }
# alternative method using special key format
# 'html:article' => html_body
}
template.render_to_file File.expand_path("~/Desktop/output.docx"), context
```
+
+##### Images (beta)
+
+Images can be added to the document using a placeholder image wrapped in a
+pair of merge fields set up as `«@figure:start»` and `«@figure:end»`. Where
+in this case "figure" is the key of the context hash storing the image.
+
+Images are wrapped in an instance of a `Sablon::Content` class in the same
+fashion as HTML or WordML strings. An image may be initialized from multiple
+sources such as file paths, URLs, or any object that exposes a `#read`
+method that returns image data. When using a "readable object" if the object
+doesn't have a `#filename` method then a `filename: '...'` option
+needs to be added to the `Sablon.content` method call.
+```ruby
+context = {
+ figure: Sablon.content(:image, 'fixtures/images/c3po.jpg'),
+ figure2: Sablon.content(:image, string_io_obj, filename: 'test.png')
+ # alternative method using special key format for simple paths and URLs
+ # 'image:figure' => 'fixtures/images/c3po.jpg'
+}
+```
+
+Example:
+
+
+Additional examples of usage can be found in
+[images_template.docx](test/fixtures/images_template.docx) and
+in [sablon_test.rb](test/sablon_test.rb).
+
#### Conditionals
Sablon can render parts of the template conditionally based on the value of a
context variable. Conditional fields are inserted around the content.
@@ -262,9 +292,10 @@
```
«body:if(present?)»
... arbitrary document markup ...
«body:endIf»
```
+
#### Loops
Loops repeat parts of the document.