Description

The atkDocumentWriter is the general DocumentWriter framework class. It Should be extended to support specific file formats. At this moment 2 file formats are supported:

.odt - Open Office
.docx. - MSWord 2007

Params

The constructor of the atkDocumentWriter is not directly called. &atkDocumentWriter::getInstance($format) must be used to get a singleton instance for any format used.

Examples

Template

The basic idea is that tags in a template-document are replaced by specified values.

A simple template will look like this:

Dear [name],
Thank you for testing this template.
Greetings,
[sender]

This is just a regular Open Office .odt or Word2007 .docx document.

In your code, $tplvars is an array which contains 'tags' and 'values'.

$tplvars["name"] = "Jeroen";
$tplvars["sender"] = "Santa";

In the generated document, the tags are replaced:

Dear Jeroen,
Thank you for testing this template.
Greetings,
Santa

Available codes

If you want to know which codes are available in a document, you can use the [taglist] tag in a template document. When using the documentwriter on this template, the resulting document will contain a list of all available tags (including loops which can be used in tables).

Display document (Open Office example)

Use the atkDocumentWriter in an action for example. When a button is pressed, a document will be generated:

$template_filename = "oo_template.odt";           
$template_file = &$handler->getFilenameForTemplate($template_filename);

The location of the template can be configured in config.inc.php: $config_doctemplatedir = "doctemplates/";

atkimport("atk.document.atkdocumentwriter");
$dw = &atkDocumentWriter::getInstance("opendocument");
$dw->display($template_file, "output.odt", $tplvars);

A 'Save as..' dialog will popup in your browser to save the document (or it will be displayed inline, when configured in the browser).

Store document (MS Word 2007 example)

Use the atkDocumentWriter in an action for example. When a button is pressed, a document will be generated:

$template_filename = "word_template.docx";           
$template_file = &$handler->getFilenameForTemplate($template_filename);

The location of the template can be configured in config.inc.php: $config_doctemplatedir = "doctemplates/";

atkimport("atk.document.atkdocumentwriter");
$dw = &atkDocumentWriter::getInstance("docx");
$dw->store($template_file, atkconfig('atktempdir')."generated_docs/output.docx", $tplvars, true); // pass 'true' to create non-existing directories automatically

Your document will be stored in the specified directory

Tips and Limitations

Docx formatting problems

As mentioned above, the [tags] in your document will be replaced by the value in your tplvars. The application will search for the exact text between [ and ].

MSWord 2007 tends to add a lot of markup codes between the [ and ], sometimes. You do not see this markup in your document, but if you check out the xml code it will look like this:

Name:</w:t></w:r><w:proofErr w:type="gramStart"/><w:r><w:rPr><w:rFonts w:ascii="Arial" etc.. <w:t>[name</w:t></w:r><w:proofErr w:type="gramEnd"/></w:rPr><w:t>]
                                                                                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

As you can see, the ] is separeted from the rest of the tag and will therefore not be replaced by the 'name' specified in your tplvars. The XML should look like this:

Name:</w:t></w:r><w:r><w:rPr><w:rFonts w:ascii="Arial" w:hAnsi="Arial" w:cs="Arial"/>  etc.. <w:t>[name]

Preventing and fixing splitted tags problem in .docx

Luckily the markup is not added all the time. After saving and closing your document, you can check your template:

by using the atkDocumentWriter with this template in your application and check if all tags were correctly replaced
or check the document.xml file in your .docx file

This xml file can be found in the .docx file. Basically, your .docx file is a zip-archive, which you can rename to .zip and open it. 7-Zip allows you to open a .docx file as an archive directly (right click on file, 'open archive' and browse to this file). You can see the contents of your document in:

word/document.xml

These rules will minimize the adding of markup:

1 Font only

Use only 1 font in a document. This will the 'base font' of the document. For every font switch, markup code is added around the text with the other font.

Avoid tables

Try to avoid tables, and use a text box instead if possible (if you want two columns next to each other, for example).

If you do want to use tables, you'll probably have to add one or more spaces after the last closing tag ]. A newline can do the job too.

Retyping the tag

You can try retyping the tag, or a part of the tag (the last couple of characters).

Adding spaces

Sometimes, adding or removing a space after the tag will do the trick too.

Retyping all tags

However, changing one tag, can break one or more other tags. Retype (or add/remove spaces to) the broken tags to fix them.