Usage
Documatic is a set of Ruby libraries distributed as a Rubygem. These libraries can be included in Ruby or Ruby on Rails applications.
Documatic's design follows the model/view/controller paradigm.
Model
Your data model can come from any source: database records from ActiveRecord or pure Ruby DBI, data obtained from web services, system commands, or whatever.
Documatic places no constraints on the format of your data, or the number or types of data you can pass through to your template for processing. There is no special model API for Documatic.
View
The view is an OpenDocument file. We call this the "template": even though it is not literally an OpenOffice.org template, it functions as a template for Documatic documents. You can embed Ruby code in the document by editing it in OpenOffice.org and assigning one of the four special character styles to your code: "Ruby Block", "Ruby Code", "Ruby Value" or "Ruby Literal". More details are below.
Controller
Your Ruby script is the controller. It is responsible for collecting the model data, instantiating a Documatic template, and processing the template.
Your script needs to load 'rubygems' and 'documatic' (if not already loaded).
require 'rubygems'
require 'documatic'Then your script fetches and perhaps manipulates the model data for the report. Your script instantiates Documatic::Template and provides the path to the template.
t = Documatic::Template.new(filename)Your script invokes process on the template object, passing a hash of keys/values. This hash becomes part of the namespace for the merge. Documatic uses some Ruby trickery to inject the keys into the template's namespace, so they become faux local variables (to be precise, they are singleton methods of the instance class representing the template's component objects).
For example the following code would create faux local variables 'name' and 'phone' to be used when processing the template.
t.process :name => "Fred Bloggs", :phone => "9876 5432"The variables you pass in can be arrays, hashes, ActiveRecord objects, or any other kind of Ruby object that can be instantiated in your code.
Preparing Templates
A Documatic template is simply an OpenDocument file with some special character styles that get converted by Documatic into embedded Ruby.
Note: these are character styles, not paragraph styles. Display the OpenOffice.org Stylist by going to the menu Format > Styles and Formatting or by pressing F11. Then click the second button at the top to go to Character Styles.
Ruby Value
The "Ruby Value" character style marks text that is to be interpreted and inserted in the output document. It is probably the basic and most useful style tag to use with Documatic: it simply displays a value.
The corresponding embedded Ruby markers are <%= and %>. The value within is escaped, to protect against errors caused by the insertion of any special XML characters.
Use "Ruby Value" for any visible data.
Ruby Code
The "Ruby Code" character style marks text that is to be interpreted as code, where the resulting value is not to be presented in the document itself.
The corresponding embedded Ruby markers are <% and %>.
"Ruby Code" is useful for control and looping statements, such as if...else and do...end blocks.
Ruby Block
"Ruby Block" is like "Ruby Value", except that it inserts content at the block level. It's one of the esoteric yet powerful features of Documatic. Some explanation of how OpenDocument works is required to understand what Ruby Block is designed to do.
The XML within an OpenDocument file has a lengthy preamble with styles etc., then it has an element that contains the visible body text of the document. This element doesn't contain literal text: it contains block level elements such as paragraphs, tables, lists etc. These block level elements contain the text spans that comprise the visible letters and words in your document.
"Ruby Value" is the right choice if you want to embed code within the text of a paragraph. However, if you want to remove the entire paragraph and replace it with a block-level element - such as another paragraph, a table, etc. - then "Ruby Block" is the right choice. The Documatic compiler uses the following heuristic: if a paragraph contains nothing but a "Ruby Block" command, the entire paragraph is removed and replaced by the embedded Ruby in the "Ruby Block".
"Ruby Block" is useful for inserting partials (i.e. other templates, like subreports) because they are also OpenDocument files and so contain material at the block level.
Ruby Literal
"Ruby Literal" is also like "Ruby Value", except that it does not escape the inserted data. That makes "Ruby Literal" very useful for inserting XML data directly into the text stream. For example Documatic comes with a helper called span() that inserts text into your template with the specified style; span() should be marked up with "Ruby Literal".
The following table summarises the main features and intended uses of the four markup styles:
| Block | Displayed | Escaped |
Notes |
|
| Ruby Code |  |
|
For control structures. Absorbs surrounding paragraph; list item or table row. | |
| Ruby Value | |
|
Displays values in text. | |
| Ruby Block | |
|
Displays block-level XML (e.g. partials). Absorbs surrounding paragraph. | |
| Ruby Literal | |
Displays text values and unescaped XML (e.g. text helpers) |
Partials
One of the powerful features of Documatic is the ability to include partial templates into a master template. This allows you to modularise your templates: extract common functionality into partials.
Partials are prepared in the same manner as any other Documatic template. Documatic provides a helper partial() that takes two arguments: the partial's file name and a set of local assigns (similar to the bindings passed to the process() method discussed above). Partials are inserted into other templates using the "Ruby Block" tag.
Demonstrations
If the above information seems a bit confusing initially, some examples might illustrate the ease of working with Documatic.
Stand-alone Ruby Application
The zip file below contains a simple example of a Documatic report, including how to use "Ruby Block" to insert a partial in a report.
Demonstration (21KB zip)Download and unpack the above zip file to a temporary directory, then try running the Ruby script. The data comes from a simple hash in the script itself. A subdirectory called "output" will be created in the current directory, where the merged report will be created.
Ruby on Rails Application
This site features a trivial Documatic report that list this site's content pages.
This report illustrates how easy it is to use Documatic with Rails and ActiveRecord data, as well as how you can gather information using a form and include it in the report. Included is a link to download the source code for this report.