How it Works

Documatic is essentially just a way of using embedded Ruby (ERB) in OpenDocument text files. But for that to work, you need to tell Documatic which bits are code so can be treated separately to the main document.

Users of ERB will already be familiar with this idea. When you put ERB in say a HTML template, you mark up the code with either <% %> or <%= %> markers. The first sort of marker encloses Ruby code that controls the flow of your program, but which isn't actually printed in the output. The second sort encloses Ruby code that returns a value that is printed in the output.

That's basically how Documatic works too. You have four special character styles (not paragraph styles!) called "Ruby Code", "Ruby Value", "Ruby Block" and "Ruby Literal". Documatic compiles your template by turning any text marked up with these character styles into ERB code. Then when you use the template for processing, those ERB fragments are interpreted and your output document is constructed.

So making a Documatic template is dead easy. Just create four character styles called "Ruby Code", "Ruby Value", "Ruby Block" and "Ruby Literal". You can use whatever font or colour you like for these character styles: whatever is easiest to read on the screen (the appearance of these four styles is not reflected in the output). Then enter Ruby code into your document and mark it with these styles.

Documatic Styles

"Ruby Code" and "Ruby Value" are the two basic styles for marking up your templates. The other styles -- "Ruby Block" and "Ruby Literal" -- are variations that enable you to utilise some advanced techniques.

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. It's like embedded Ruby's <% and %> markers (and behind the scenes, that's what it actually uses).

"Ruby Code" is useful for control and looping statements, such as if...else and do...end blocks.

The heuristic that the Documatic compiler uses is that if a table row, list item or paragraph contains nothing but a single "Ruby Code" span of text, the surrounding row, list item and/or paragraph is removed and only the code is inserted. That's how you can put looping code in your table, as in the DocumaticTutorial and DocumaticExamples.

Ruby Value

The "Ruby Value" character style marks text that is to be interpreted and inserted in the output document, just like embedded Ruby's <%= and %> markers. It is probably the basic and most useful style tag to use with Documatic: it simply displays a value.

Values inserted with "Ruby Value" are automatically escaped, to protect against errors caused by the insertion of any special XML characters.

Use Ruby Value for any visible data.

Ruby Literal

"Ruby Literal" is like "Ruby Value" -- it inserts visible content into the document -- except that it does not escape the inserted content. 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".

Ruby Block

"Ruby Block" is like "Ruby Literal" -- it inserts unescaped visible content into the document -- except that it inserts the 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 you see in your document.

"Ruby Block" removes the entire containing paragraph and replaces it with block-level material -- such as another paragraph, a table, etc. 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.

Bindings

When you process a Ruport Table, Group or Grouping using Documatic, there are two main sources of data that get passed into Documatic and become part of the template's bindings:

1. data: This contains the actual Table, Group or Grouping that's being rendered.
2. options: This contains any options that were passed to the renderer. This is a powerful feature, because it lets you throw all sorts of data into the mix. There's no limit to the number and types of other data you can include using options: other Tables, Groups or Groupings, or any other data. See DocumaticExamples for some examples of templates that mix in other data using the options.

Magic Stuff

You probably noticed in the examples that Documatic loops over table rows and list items by having code above and below the row or item that's actually being repeated. So how does that work?

Documatic has a number of heuristics to determine how "Ruby Code" should be converted to embedded Ruby.

• If you have a table cell that spans the entire row, and that cell contains nothing except one (and only one) "Ruby Code" block, that whole row is treated as code and removed from the output.
• Similarly with list items and paragraphs: if they contain nothing except one "Ruby Code" block they are removed from the output.

These heuristics allow you to include your code in the template without leaving ugly gaps behind when the template is processed. The embedded Ruby code is interpreted and disappears, and the document knits itself neatly back together again.

Note that because a code-only row can contain only one "Ruby Code" block, if you want to layout your code on multiple lines you will need to use line breaks (SHIFT+ENTER) not carriage returns (ENTER).

Documatic also has heuristics for dealing with the visual appearance of the content after "Ruby Value" and "Ruby Literal" are replaced with actual content. You would have noticed in the DocumaticTutorial and DocumaticExamples that I made these character styles as Courier 10pt with a coloured background. However when you actually process the templates, the inserted content doesn't look like that. The heuristic that Documatic uses is to remove these special character styles and to let the content take the same appearance as the surrounding text.

But what if there is no surrounding text? Or what if you want your inserted content to take a different style (e.g. outstanding account balances greater than $1000 are to be rendered in red)? Unstyled text will be rendered with your template's "Default" style, by default. I guess that's why they call it "Default". :)

Or you can use Documatic's span() helper to insert content with the style of your choice. span() lets you provide content, and a character style name with which it is to be rendered. The idea is that you can set up any character styles you want in your template, and use span() to insert content with those styles. See the API docs for more details.