-
Notifications
You must be signed in to change notification settings - Fork 6
Documatic Home Page
Documatic is a Ruby gem that can be included in Ruby, Rails Ruport applications.
Documatic’s design follows the model/view/controller paradigm.
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.
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.
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, Ruport tables or any other kind of Ruby object that can be instantiated in your code.
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.
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.
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...end and do...end blocks.
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 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.