LiveDocx in PHP

An oft underestimated feature of LiveDocx is support for the Microsoft Word INCLUDETEXT field type, which allows templates to be chained together into one larger template. The entire contents of the sub-templates are brought into the main template in the order in which the fields are inserted, during the merge process. The final document contains the contents of the template and all sub-templates.

To learn more about INCLUDETEXT and how to insert INCLUDETEXT fields into your template, please take a look the following articles:

• WD2000: How to Create a Long Document in Word, Section IncludeText Field

• Using IncludeText Fields – Part 1: Creating Templates

• Using IncludeText Fields – Part 2: Putting It All To Work

Zend\Service\LiveDocx\MailMerge provides two methods to control how or whether sub-templates are included in the main template.

In the default state, all templates, which are referenced in INCLUDETEXT fields are included during the merge process.

If you do not want this to be the case, the method setIgnoreSubTemplates() can be set to true. This disables the inclusion of all sub-templates during the merge process. Using the free public LiveDocx service, you cannot selectively define which templates should be included. It is an all-or-nothing approach.

The premium and licensed versions of the LiveDocx service, on the other hand, allow for more fine grained control. These versions provide the method setSubTemplateIgnoreList(), which takes an array of filenames that should not be included. This way, you can, for example, included sub-templates 2 and 5, but not 1, 3 and 4.

The methods setIgnoreSubTemplates() and setSubTemplateIgnoreList() will be part of Zend Framework 2 when it ships. The latest code updates should be merged into master on the Zend canonical repository within the next few weeks. For the time being, the code is still in my GitHub repository, in the branch livedocx-2.0.

You can clone the latest code at:
https://github.com/jonathanmaron/zf2/tree/livedocx-2.0

Take a look at the following directory for some demonstration applications that illustrate the methods setIgnoreSubTemplates() and setSubTemplateIgnoreList()

/demos/Zend/Service/LiveDocx/MailMerge/templates-ignore/

Feel free to contact me, using the comments section below, if you need any help, or notice any inconsistencies in the code.

June 10, 2011: The code updates mentioned in this post have now been merged into master on the Zend canonical repository.

I am delighted to announce that the Zend Framework 2 implementation of the LiveDocx service is getting nearer completion. At the moment, the code is still in my GitHub repository, in the branch livedocx-2.0. It should be merged into master on the Zend canonical repository within the next few weeks.

You can clone the latest code at:
https://github.com/jonathanmaron/zf2/tree/livedocx-2.0

What’s new in this version?

• Exception handling has been migrated to ZF2 practices i.e. Exception/RuntimeException and Exception/InvalidArgumentException.

• Exceptions from the backend service now contain only the message from the backend service. The backend engineers requested this be the case, as it aides support cases.

• The inline documentation has been updated.

• The methods logIn() and logOut() are now protected in scope.

• The methods setIsLoggedIn() and getIsLoggedIn() were added.

• The quality and coverage of unit tests have been vastly improved (63 tests, 203 assertions).

You are welcome to clone the repository and try out the new code for yourself. Feel free to contact me, using the comments section below, if you need any help, or notice any inconsistencies in the code.

June 10, 2011: The code updates mentioned in this post have now been merged into master on the Zend canonical repository.

One of the most popular questions that I get asked by developers, using the free public LiveDocx service, i.e. the default in the Zend Framework components, is:

Why am I forbidden from using the LiveDocx service? What have I done wrong?
I keep getting an Exception, with the message HTTP Error 403 Forbidden.

To be fair, this error message is not great and I will lobby the backend engineers to make it more explicit. But what does it mean?

It means that you are trying to perform one of the following:

• More than 1 concurrent request.

• More than 100 requests in any 60 second period.

The free public service has to restrict usage to ensure that all users get a fair share of the service.

These limitations do not apply to the premium or licensed LiveDocx products.