Hi all,

 A few months have passed since we almost released LiveDocx 1.3. But while it has been quiet here, we were busy working on new features in the meantime. Now it is time to prepare our next release, and this is a sneak preview of what to expect of it.

Image fields

Many of you have asked about this, and we think we have found an easy and clean way of doing it. The next LiveDocx release will enable you to merge images into fields. No need for a new or special field type required. This new feature works with plain, old merge fields.

Nested blocks

A fairly advanced feature not everybody has a need for. But those of you who do miss it badly. Hence, you will be pleased to hear that the next LiveDocx release will enable you to merge nested blocks.

Formatted input

Last but not least, the next LiveDocx release will enable you to merge formatted text (HTML) into your templates. This opens up new possibilities in application design. You could, e.g., provide your users with a simple rich text editor or let them merge hyperlinks, which will work in the resulting PDF documents, of course.

Dear LiveDocx users,

We would like to inform you that as of May 26, 2010, LiveDocx 1.0 and 1.1 will no longer be available.

If you are still running any scripts or applications based on one of those versions of LiveDocx, please update them to use LiveDocx 1.2 before that date.

LiveDocx 1.2 will continue to run as before.

Thank you for using LiveDocx!

Great news, everyone!

While preparing LiveDocx 1.3, which we were developing solely as a maintenance release, the compatibility tests revealed that is was possible to run it as an update to LiveDocx 1.2 without any side effects for existing applications. Therefore, we chose to update LiveDocx 1.2 instead of having all of our users have to update their applications to a new version.

Enjoy LiveDocx!

LiveDocx 1.2 has been around for quite a while now. We think it's time for a new version. In fact, this thought is not new. Months ago, we thought about implementing and releasing LiveDocx 1.3 that should bring some small improvements. We have even given some hints in several forum posts and in some support emails indicating that the 1.3 release was imminent.

As you can all see, we have decided differently. This post is intended to give you some long overdue insight regarding our planning.

First things first

There has been a nasty bug in our server backend, which kept us quite busy for some weeks. The bug's existence became more and more apparent with the growing number of users accessing our services. We had to straighten out our priorities; making the current service more robust trumped releasing new features. Thus, we've put development on ice and went bug hunting.

Finally, we've been able not only to track it down, which alone was hard enough, but also to fix it. We have still some final testing to do to make absolutely sure the bug is gone, but it won't be too long before we apply the fix to our servers. We will inform you separately of the upcoming maintenance, of course.

Roadmap

As indicated in the introduction, this post means to give you an idea of what we are up to. Currently, we are working on two releases.

LiveDocx 1.3

The long promised version. This version is based on the above mentioned fix. Its sole purpose is to replace all previous versions of LiveDocx, 1.0, 1.1 and 1.2, all of which include the bug that has made our lives so hard for the past couple of weeks. LiveDocx 1.3 is completely backward compatible, so apart from swapping the old service URL with the new one, you shouldn't have to do anything to make it work with your existing code.

Obviously, the above means that shortly after releasing LiveDocx 1.3, we will discontinue the older releases. To make sure every user gets a chance to make the transition to the new version, we will send an email to every user and also wait an appropriate amount of time before we shut down the other versions.

LiveDocx 2.0

The long awaited features. Many users give us feedback regarding our service. Some of it is good, some of it not so much. We appreciate this. Feedback shows us what we have done right and also where there is room for improvement.

Regarding improvement, two features that users have constantly been asking for are nested merge blocks and formatted merge data. LiveDocx 2.0 will support these features. As the version number indicates, the interface will change—probably a lot. The new API is not finalized yet, we still have to figure some things out regarding cross-platform compatibility. For one, it's not always easy to use the built-in serialization of .NET data types, while at the same time remain, e.g., PHP friendly. Also, we are trying various authentication methods to reduce the number of API calls.

I am pretty sure we'll come up with a solution that will keep everybody happy. Of course we'll keep you posted.

Enjoy LiveDocx.

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!