README.md in sablon-0.0.21 vs README.md in sablon-0.0.22
- old
+ new
@@ -6,10 +6,32 @@
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)
+ * [Conditionals](#conditionals)
+ * [Loops](#loops)
+ * [Nesting](#nesting)
+ * [Comments](#comments)
+ * [Configuration (Beta)](#configuration-beta)
+ * [Customizing HTML Tag Conversion](#customizing-html-tag-conversion)
+ * [Customizing CSS Style Conversion](#customizing-css-style-conversion)
+ * [Executable](#executable)
+ * [Examples](#examples)
+ * [Using a Ruby script](#using-a-ruby-script)
+ * [Using the sablon executable](#using-the-sablon-executable)
+* [Contributing](#contributing)
+* [Inspiration](#inspiration)
+
+
## Installation
Add this line to your application's Gemfile:
```ruby
@@ -100,44 +122,59 @@
IMPORTANT: This feature is very much *experimental*. Currently, the insertion
will replace the containing paragraph. This means that other content in the same
paragraph is discarded.
-##### HTML [experimental]
+##### HTML
-Similar to WordProcessingML it's possible to use html as input while processing the
-tempalte. You don't need to modify your templates, a simple insertion operation
+Similar to WordProcessingML it's possible to use html as input while processing the template. You don't need to modify your templates, a simple insertion operation
is sufficient:
```
-«=article.body»
+«=article»
```
To use HTML insertion prepare the context like so:
```ruby
html_body = <<-HTML
<div>This text can contain <em>additional formatting</em>
according to the <strong>HTML</strong> specification.</div>
+<p style="text-align: right; background-color: #FFFF00">Right aligned
+content with a yellow background color</p>
+<div><span style="color: #123456">Inline styles</span> are possible as well</div>
HTML
context = {
- article: { html_body: Sablon.content(:html, html_body) }
+ article: Sablon.content(:html, html_body) }
+ # alternative method using special key format
+ # 'html:article' => html_body
}
template.render_to_file File.expand_path("~/Desktop/output.docx"), context
```
-Currently HTML insertion is very limited and strongly focused on the HTML
-generated by [Trix editor](https://github.com/basecamp/trix).
+Currently, HTML insertion is somewhat limited. It is recommended that the block level tags such as `p` and `div` are not nested within each other, otherwise the final document may not generate as anticipated. List tags (`ul` and `ol`) and inline tags (`span`, `b`, `em`, etc.) can be nested as deeply as needed.
-IMPORTANT: This feature is very much *experimental*. Currently, the insertion
- will replace the containing paragraph. This means that other content in the same
- paragraph is discarded.
+Not all tags are supported. Currently supported tags are defined in [configuration.rb](lib/sablon/configuration/configuration.rb) for paragraphs in method `prepare_paragraph` and for text runs in `prepare_run`.
+Basic conversion of CSS inline styles into matching WordML properties in supported through the `style=" ... "` attribute in the HTML markup. Not all possible styles are supported and only a small subset of CSS styles have a direct WordML equivalent. Styles are passed onto nested elements. The currently supported styles are also defined in [configuration.rb](lib/sablon/configuration/configuration.rb) in method `process_style`. Simple toggle properties that aren't directly supported can be added using the `text-decoration: ` style attribute with the proper WordML tag name as the value. Paragraph and Run property reference can be found at:
+ * http://officeopenxml.com/WPparagraphProperties.php
+ * http://officeopenxml.com/WPtextFormatting.php
+If you wish to write out your HTML code in an indented human readable fashion, or you are pulling content from the ERB templating engine in rails the following regular expression can help eliminate extraneous whitespace in the final document.
+```ruby
+# combine all white space
+html_str = html_str.gsub(/\s+/, ' ')
+# clear any white space between block level tags and other content
+html_str.gsub(%r{\s*<(/?(?:h\d|div|p|br|ul|ol|li).*?)>\s*}, '<\1>')
+```
+
+IMPORTANT: Currently, the insertion will replace the containing paragraph. This means that other content in the same paragraph is discarded.
+
+
#### Conditionals
-Sablon can render parts of the template conditonally based on the value of a
+Sablon can render parts of the template conditionally based on the value of a
context variable. Conditional fields are inserted around the content.
```
«technologies:if»
... arbitrary document markup ...
@@ -185,9 +222,81 @@
```
«comment»
... arbitrary document markup ...
«endComment»
+```
+
+### Configuration (Beta)
+
+The Sablon::Configuration singleton is a new feature that allows the end user to customize HTML parsing to their needs without needing to fork and edit the source code of the gem. This API is still in a beta state and may be subject to change as future needs are identified beyond HTML conversion.
+
+The example below show how to expose the configuration instance:
+```ruby
+Sablon.configure do |config|
+ # manipulate config object
+end
+```
+
+The default set of registered HTML tags and CSS property conversions are defined in [configuration.rb](lib/sablon/configuration/configuration.rb).
+
+#### Customizing HTML Tag Conversion
+
+Any HTML tag can be added using the configuration object even if it needs a custom AST class to handle conversion logic. Simple inline tags that only modify the style of text (i.e. the already supported `<b>` tag) can be added without an AST class as shown below:
+```ruby
+Sablon.configure do |config|
+ config.register_html_tag(:bgcyan, :inline, properties: { highlight: 'cyan' })
+end
+```
+The above tag simply adds a background color to text using the `<w:highlight w:val="cyan" />` property.
+
+
+More complex business logic can be supported by adding a new class under the `Sablon::HTMLConverter` namespace. The new class will likely subclass `Sablon::HTMLConverter::Node` or `Sablon::HTMLConverter::Collection` depending on the needed behavior. The current AST classes serve as additional examples and can be found in [ast.rb](/lib/sablon/html/ast.rb). When registering a new HTML tag that uses a custom AST class the class must be passed in either by name using a lowercased and underscored symbol or the class object itself.
+
+The block below shows how to register a new HTML tag that adds the following AST class: `Sablon::HTMLConverter::InstrText`.
+```ruby
+module Sablon
+ class HTMLConverter
+ class InstrText < Node
+ # implementation details ...
+ end
+ end
+end
+# register tag
+Sablon.configure do |config|
+ config.register_html_tag(:bgcyan, :inline, ast_class: :instr_text)
+end
+```
+
+Existing tags can be overwritten using the `config.register_html_tag` method or removed entirely using `config.remove_html_tag`.
+```ruby
+# remove tag
+Sablon.configure do |config|
+ # remove support for the span tag
+ config.remove_html_tag(:span)
+end
+```
+
+
+#### Customizing CSS Style Conversion
+
+The conversion of CSS stored in an element's `style="..."` attribute can be customized using the configuration object as well. Adding a new style conversion or overriding an existing one is done using the `config.register_style_converter` method. It accepts three arguments the name of the AST node (as a lowercased and underscored symbol) the style applies to, the name of the CSS property (needs to be a string in most cases) and a lambda that accepts a single argument, the property value. The example below shows how to add a new style that sets the `<w:highlight />` property.
+```ruby
+# add style conversion
+Sablon.configure do |config|
+ # register new conversion for the Sablon::HTMLConverter::Run AST class.
+ converter = lambda { |v| return 'highlight', v }
+ config.register_style_converter(:run, 'custom-highlight', converter)
+end
+```
+
+Existing conversions can be overwritten using the `config.register_style_converter` method or removed entirely using `config.remove_style_converter`.
+```ruby
+# remove tag
+Sablon.configure do |config|
+ # remove support for conversion of font-size for the Run AST class
+ config.remove_style_converter(:run, 'font-size')
+end
```
### Executable
The `sablon` executable can be used to process templates on the command-line.