Tips for making the template identical to the output.
Windward tries to make the output report 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 when it is being built, it is an ongoing document based on the amount of data that is being pulled from your data source, as opposed to a 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.
With a Windward tagged template, you are creating a flowing stream of paragraphs, images, tables, one after the other, which vary in size/length (depending on the data you tell it to retrieve).
- When Windward is writing your Output, it starts at the top and follows the instructions of each tag as it encounters it 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 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.
Explanations of Differences
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 measurement comes 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 fontmetrics of the fonts installed on the system generating the report. If a font specified in the template does not exist on the server, then the system has to substitute in a font that is installed. This substituted font will generally have different fontmetric 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. 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 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 settings appropriately for paragraph settings of "keep with/together" and table "row header." If you create 3 rows or 3 paragraphs with tags in the template, the report can end up being 150 rows or 150 paragraphs! Just remember that those 3 rows/paragraphs with your tags may all fit on one page, but the final report 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 a template in RTF is more likely to have something problematic in it.
- 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, you will sooner or later run on a system where the fonts are a little larger and your 1 page is now 2 pages.
These tips should help prevent and correct minor formatting issues and discrepancies between the document on your screen and the Output.