Template Layout Best Practices
Here are some tips for making your output identical to your report template.
Windward tries to make template output pixel-for-pixel identical with the created template. However, it will never be perfect.
The best way to approach your template is with the idea that while you are building it, it is an ever-changing document based on the amount of data that is being pulled from your data source; as opposed to something like a painting, which has a permanent size and permanent placement. With a painting, you can put something in an exact spot on the canvas and everything stays the same size or in the same place no matter what changes may be made elsewhere.
Whereas with a Windward Tagged template, you are creating a flowing stream of paragraphs, images, tables, one after the other, which vary in size and length (depending on the data you tell it to retrieve).
- When Windward is generating your output, it starts at the top and follows the instructions of each Tag it encounters until it reaches the end of your template.
- Each item (paragraph, images, tables, etc.) has properties about how it follows the preceding item and how the next item should follow it, so the actual size of the output can change each time you run a report.
- Some of these items' properties are affected by settings you implement in Office, while some are set up in the Tag Editor of a specific Tag. Settings can be in conflict with each other, or can produce results you were not anticipating.
Some (not all) of the reasons for differences are:
- Office itself will format slightly differently based on the graphics and printer drivers on a system.
- Office lays out documents slightly differently from what their spec says it should do--these differences are not documented and Microsoft itself generally does not know exactly how Word/Excel is calculating the placement of text.
- Most measurements come from the text metrics provided by the True Type fonts on a system. Different systems provide different numbers for the same font. The same font file provides different numbers on different operating systems. If these differ, the output will differ.
- PDF output is not rendered as documented. In a PDF file if you tell it to render a square 1" x 1" we have seen it do everything from 0.9" x 0.9" to 1.05" x 1.05". It appears to depend on the graphics card and printer driver.
- The layout (soft line break, soft page breaks, etc.) is performed using the font metrics of the fonts installed on the system generating the report. If a font specified in the template does not exist on the server where output is generated, then Windward has to substitute a font that is installed. This substituted font will generally have different font metric values, and that will affect the appearance of the layout. (Starting in version 13 you can define what existing font should be used for a missing font.)
- PDF output has no concept of a border, just a polyline. A polyline is a continuous line of constant width and color that is composed of several line segments. PDF output will join all segments smoothly. And if the line ends where it starts, it will join the ends of the line. But if a border changes width, color, style as it is being drawn, one polyline ends and another starts. Even though they end/start at the same location, they are not joined. In addition, internal borders between cells are not joined to the outer border.
In almost all cases you can easily work with the constraints if you follow these guidelines:
- When you need a page break, put in a hard page break. Do not depend on the page layout to put in a soft page break. Do the same for line breaks, column breaks, etc.
- Absolutely-positioned objects can cause problems as they don't move when the data is merged in. That can be a problem as the merged-in data needs to adjust other objects to take their placement into account. Avoid absolutely-positioned objects whenever possible. Positioning relative to a paragraph, column, (margin for X position) are all fine. Positioning relative to the page or margin on the Y axis is strongly discouraged. When using any Engine to generate a DOCX report, absolutely-positioned Word tables will not break across pages.
- Use appropriate paragraph settings for "keep with/together" and table "row header." If you create three rows or three paragraphs with Tags in the template, the output can be 150 rows or 150 paragraphs! Just remember that those three rows/paragraphs with your Tags may all fit on one page, but the final output may not fit on one page.
- Set column widths in tables using set values (inches, centimeters, points) or percentages. If you use autofit it will not match because Microsoft is not sure how Word does that. Excel column widths will always be a little off because of how Excel calculates them.
- Use TrueType and OpenType fonts. If you use other types of fonts, there are limits with what can be done with them and they are closely tied to their code page.
- For PDF table borders Windward draws a polyline for the outer border, a polyline for each internal row border and a polyline for each internal column border. Whenever possible, keep each individual polyline to the same width, color, and style.
- RTF is no longer a supported template format--please use DOCX, XLSX, or PPTX instead. The RTF format is very poorly defined and Word does not follow it in many cases. DOCX is well defined and Word mostly follows it. So an RTF template is more likely to be problematic.
- Minimize the use of nested tables. If you want a border around a page, do not create a table for the entire page containing the page contents - use the page border. Nested tables are very useful and well supported, so this is a matter of appropriate use, not trying to avoid them. But when you have two approaches and one does not use an additional nested table, use that approach.
- Leave a little room on each page. If you cram everything you can onto a page and it barely holds it all before the page break, sooner or later you will generate output on a system where the fonts are a little larger and your one page output is now two pages.
These tips should help prevent and correct minor formatting issues and discrepancies between the document on your screen and the Output.