Template design rules

JCopist was designed to allow maximum flexibility when using FreeMarker in OpenOffice.org documents. However, there are a few rules you have to follow when designing your templates:

Double quotes

FreeMarker uses double quotes for character strings and XPath expressions.

For certain languages, OpenOffice.org will autocorrect double quotes to something else. For instance, in French, "quoted" becomes:

Quotes correction

These quotes won't work with FreeMarker. Therefore, you have to disable quote autocorrection, either by pressing Ctrl+Z everytime you type one, or permanently from the "Tools/Autocorrect" menu in OpenOffice.org

Conditional tags on a single line

Consider the following example :

Defective single-line if

The FreeMarker syntax is correct, however this template will fail!

Problem

As you may already know, OpenOffice.org stores the content of your document in an XML file. The line above will be stored in a <text:p> tag ; however, the red part at the end of the line will be stored in an embedded <text:span>tag: 

<text:p text:style-name="P1">
[#if (false)]Foo
<text:span text:style-name="T1">
[/#if]Bar
</text:span>
</text:p>

When FreeMarker interprets this fragment, the [#if]...[/#if] block is removed, and we are left with the following XML: 

<text:p text:style-name="P1">
Bar
</text:span>
</text:p>

As you can see, the closing </text:span> tag has no matching opening tag, hence the XML is not valid.

Solution

Use a different formatting for your FreeMarker tags :

Correct single-line if

This way, FreeMarker tags and normal text will always be in separate <text:span> tags.

Furthermore, it will make your templates more readable.

Conditional tags spanning multiple paragraphs

Here is another example that won't work :

Defective multi_line if

Problem

As before, the problem is explained by looking at the content.xml file:

<text:p text:style-name="P1">
	This paragraph is always displayed.
</text:p>
<text:p text:style-name="P2">
	[#if (false)]
</text:p>
<text:p text:style-name="P1">
	This paragraph is displayed conditionnally.
</text:p>
<text:p text:style-name="P3">
	<text:span text:style-name="T1">
		[/#if]
	</text:span>
	<text:span text:style-name="T2">
		trailing text...
	</text:span>
</text:p>

Notice that the [#if] FreeMarker tag has its own paragraph. JCopist will automatically detect this kind of situation and remove the surrounding <text:p> tag, in order to avoid blank lines in the resulting document.

Therefore, when FreeMarker interprets the fragment, we get the following XML:

<text:p text:style-name="P1">
	This paragraph is always displayed.
</text:p>
	</text:span>
	<text:span text:style-name="T2">
		trailing text...
	</text:span>
</text:p>

Once again, there are unmatched closing tags.

Solution

The problem above comes from the trailing text. Always put the closing [/#if]tag on a distinct line:

Correct multi_line if

Make sure there are no trailing whitespaces or tabs on the line. Also, select the whole line and apply a format, to be sure there is just a single <text:p> tag around the FreeMarker tag, and no <text:span>.