A lot of people have asked us, if it is possible to use OpenOffice.org (OOo) to create templates that are compatible with LiveDocx. It actually is possible to do that. But because of OOo's approach to mail merge it is not as straightforward as in MS Word. OOo's mail merge philosophy needs a little getting used to. This post will help you understand this philosophy and get you started on creating templates with OOo.

Database-based mail merge

Mail merge in OpenOffice.org (OOo)—and this includes creating templates—cannot be done without first setting up a database. That database determines which mail merge fields can be contained in a template.

Luckily, we can use OOo Calc to setup the database, which makes the process almost effortless. The following image shows how to setup up a sample database using OOo Calc:  

Determining the mail merge fields for a template is as easy as setting their names as column headers. For the above sample this means, there will be the fields recipientsender available later on. Additional fields would go into the cells C1, D1 and so on. The best format to save this file is the default format, i.e. OpenDocument Spreadsheet (.ods).

Putting the database to work

Now that the "database" is in place, we can move to the actual template creation. For this step we need OOo Writer, of course, but please note that OOo Base also has to be installed, even though we won't use it directly.

To create our template we can use all of the "normal" text processing stuff. For inserting mail merge fields, however, we need to access the menu Insert → Fields → Other… or simply press Ctrl+F2 instead. In the dialog that opens we choose the Database tab. Then, we click on Browse…, navigate to the spreadsheet file we have created earlier, select it and click Open. OOo now creates a database based on the spreadsheet in the background.

Now, we select the type Mail merge fields on the left. Our database then shows up in the list as depicted below:

The database name is the same as the filename we have given the spreadsheet. The database tables correspond to the sheets in the spreadsheet file. Then again, the columns, read: fields, correspond to the cell contents we have inserted earlier.

We can now insert mail merge fields into our document. Of course, the fields are inserted at the current input position. So, we will be opening and closing the Fields dialog a lot.

Template specifics

There are a few things to bear in mind, when using OpenOffice.org (OOo) to  create templates:

1. Templates must be saved as RTF 
2. Field naming is rather special in OOo

The first one is simple. If we do not save our templates in RTF format, they will not work. It is that simple.

The second one is a bit more tricky. By choosing View → Field Names from the menu or by simply clicking Ctrl+F9 we can make the field names visible. This is quite convenient, since these will be the names we will have to use later on in our applications.

As we can see in the above image, the naming scheme is quite simple:

• database.table.column

or from our spreadsheet perspective:

• filename.sheet.column
  

There is just one big caveat. The dots in the field names are no full stop characters but ÿ characters which only look like dots in OOo. This means, we have to use the GetFieldNames() method, before we can use the fields. So, when using field names like LiveDocxÿletterÿrecipient in our code, we are able to put our templates, created in OOo, to work.

Since we have released LiveDocx MailMerge API 1.1 many people have suggested interesting new features. We ourselves had some ideas, what to implement in future versions of the web service. This blog post is meant to summarize some of those feature requests and ideas to help you figure out what's coming up in the next LiveDocx version.

Save documents as HTML

TX Text Control 15, the technology LiveDocx is based on, supports embedding images in HTML. Thus, it is possible to introduce HTML as output format into LiveDocx. Whether as quick preview, as platform independent exchange format or for use in web apps, there's a wide variety of possible applications. As usual, you just feed your template and data into the API and it returns a single file, that contains everything, to you. Please note, that only recent browsers display embedded images correctly. If unsure, refer to respective browser's documentation.

Create multiple documents in one run

The new version will accept multiple lines of merge data. The resulting documents will be appended to one another, so that they become a single (possibly long) document. This is quite useful for scenarios such as label printing, creating vouchers or certificates, for instance. But we are pretty sure you, our users, will come up with some ideas how to put this to even better use.

Reduced file sizes

Documents containing images can become quite big. Version 1.2 of the LiveDocx MailMerge API addresses this problem, resulting in significantly reduced file sizes. By the time of this writing, the internal handling and management of image files, especially the compression settings, are thoroughly revised.

The benefits of this are obvious:
smaller documents → faster downloads → overall improved user experience

List of all available fonts

Since templates should ideally contain only fonts, which are installed on the server, and the free LiveDocx server only comes equipped with the Windows standard fonts, it's often desirable to have a list of the available fonts. If a template contains fonts, which are not installed on the server, the fonts a replaced by similar ones. In some rare cases, i.e. when using too exotic fonts, this automatic process does not work, and the generated documents lack some parts. LiveDocx MailMerge API 1.2 will provide a list of the available fonts, to enable its users to check with the server, before creating faulty documents.

Now that we have a couple of new and shiny templates, what do we do it them? Let's assume we want to create a telephone bill. We want to email it to the customer directly after creation, but—for legal reasons—the customer also receives a hard copy, printed on company letter paper. This means, the document generated for emailing and the one generated for printing differ in that the latter must not have a header, since that's already pre-printed on the company letter paper. Using IncludeText fields this is easy to accomplish.

Let's get ourselves equipped!

Besides a couple of templates, all we need is a little bit of application logic. In case you haven't created any templates of your own yet, you can use these:

template.docx (8.25 kb)

sub_template.docx (16.32 kb)

There are three different ways to toggle the inclusion/exclusion of sub-templates, when using IncludeText fields with LiveDocx. Let's take a look at 'em!

Using SetIgnoreSubTemplates()

The default for LiveDocx is to include sub-templates. I.e. when there's an IncludeText field in your template pointing to an existent sub-template, the sub-template is inserted at the corresponding position into the template holding the reference during the merge process.

To experience this yourself using the above templates, make sure to put the sub-template file into your server-side user directory as 'sub_template.docx' before you start merging. If you don't want to spend time on generating merge data, simply set it to null, i.e. SetFieldValues(null), and create the document. The resulting document contains a headline and an image coming from the sub-template.

If you need to exclude the sub-template, say for printing on company letter paper, there is just one more line of code for you to type. A call to SetIgnoreSubTemplates() using true as argument does the trick, i.e. SetIgnoreSubTemplates(true).

That was simple, wasn't it?

Using an empty sub-template

Obviously, another way to prevent anything from being inserted into the main template, is to replace the sub-template with an empty document. Please note, that the empty sub-template must not be a completely empty file but a valid doc, docx, rtf or txd file without contents. Big difference!

Deleting the sub-template

Also, if you do not upload the sub-template to the LiveDocx server or delete it before merging, the resulting document won't contain the contents of the sub-template—obviously. This is to prevent the merge process from crashing, in case you forget to put the sub-template in place, but can be used to toggle off the sub-template, too.

Playtime

For the impatient, here's a .NET project to try the things described above right away:

IncludeTextSample.zip (41.34 kb)

The above archive contains a VS.NET project. All you need to do is, double-click the .csproj file to fire up Visual Studio. Then, simply run the project, enter your LiveDocx credentials in the text fields and hit one of the buttons entitled 'Don't include' or 'Include'. After a few seconds the resulting document should open automatically. Feel free to play around with the source code to explore the possibilties LiveDocx offers to you.

A new feature in LiveDocx MailMerge API 1.1 is merging IncludeText fields. With IncludeText fields you can insert sub-templates into your main template during the merge process. This comes in handy, e.g. when you want to replace whole parts of your resulting document with something else under certain conditions. Another common application is to leave the document header blank, when printing onto pre-printed letter paper, but to include the document header, when sending the document by email. In this short article I'll show, how to build templates that enable you to use this new LiveDocx feature.

Prerequisites

To get started, you need at least two templates. The first one is your main template, which contains the IncludeText field(s), and the second one is the sub-template. Sub-templates may contain everything normal templates may contain, i.e. formatted text, fields (including IncludeText fields) and merge blocks. Building circular references with IncludeText fields won't work, of course. So, be sure to check your references, before merging.

The sub-template(s) have to be located in your template directory on the LiveDocx server. UploadTemplate() is your friend.

Creating Templates

All that's left to do now is to insert an IncludeText field into the main template. You can do this using MS Word or the TX Template Designer (LiveDocx Edition), which will be available here for download shortly. Instead of setting the field value to an absolute path like MS Word suggests, just insert the filename of the desired sub-template without leading path but including the file extension.

Please note, that MS Word will display an error message (something about the document name being invalid—depending on your system language). That's ok. MS Word expects an absolute path as argument to the IncludeText field, but LiveDocx will know, how to handle the document correctly.

That's it. There's nothing more to it. Now, you are good to go.

The next article on IncludeText fields will explain, how to merge or ignore sub-templates under certain conditions.

Now that there are two versions of the mail merge service released for quite a while, it is about time to explain the thoughts behind the version numbers.

A new minor version number, i.e. the number behind the dot like 1.1 following 1.0, indicates small improvements have been made. This is the case, when e.g. new features are added to the service, which hardly affect the interface and it remains completely backward compatible. The new features get added to the API documentation, the rest of the documentation remains unchanged and valid, of course.

Major additions to and/or changes in the interface on the other hand result in a change of the major version number, i.e. the number in front of the dot. For instance changing some or all of the method signatures, rendering the exiting client libraries like phpLiveDocx incompatible, would result in something like LiveDocx MailMerge 2.0. Also, the documentation would reflect this change by introducing a new section named after the new major version number.

For better orientation regarding minor versions, every entry in the API documentation has a field called "Introduced: <ver. no.>". The field informs the reader about when a particular method has been introduced into the service.

After a thorough server update and slight reconfiguration this morning we are proud to announce that version 1.1 of the LiveDocx MailMerge API is now available. This version is based on the recently released TX Text Control 15.0.

New Merge Field Types

LiveDocx MailMerge API 1.1 implements some new merge field types. Thus, this version now features following field types:

• MERGEFIELD
• DATE
• PAGE
• IF
• INCLUDETEXT

Additionally, to pay our respects to the beta status of our site and service, we have added

• NUMPAGES

to the list above, which is automatically merged at the end of the merging process with the total number of pages of the resulting document.

Reduced PDF file size

Many people will be pleased to learn that the size of generated PDF documents is dramatically smaller compared to those generated with version 1.0. In LiveDocx, PDF files are produced using the TX Text Control server component. Due to a PDF export filter in an early beta stage, the overly big PDF files came about.

SSL is mandatory

SSL is not optional but mandatory in LiveDocx MailMerge API 1.1. Regardless of the intended use of the service, SSL encryption always ensures maximum security and the integrity of the transmitted data.

New Service URL

The URL to use the new version is https://api.livedocx.com/1.1/mailmerge.asmx?WSDL, which can also be found in the footer of the LiveDocx website. Of course, the LiveDocx MailMerge API 1.0 will still be available. Also, SSL in version 1.0 remains optional.

Lastly, we want to apologize for any inconvenience the server update may have caused.

Have fun with the new version!

Due to some necessary maintenance work, the LiveDocx service and website will probably not be accessible on Tuesday, May 26, 2009 between 9:00 and 10:00 GMT. In advance, we appologize for any inconvenience.