Design Considerations for the Word Rendering
The Word Rendering Extension of Telerik Reporting produces Open XML Word documents. The generated documents are compatible with Microsoft Word 2007 or later. Earlier versions of Microsoft Word are not supported. This rendering extension requires Third-Party Dependencies. The file name extension generated by this renderer is DOCX. After the report is exported, you can edit the contents of the generated document or print it as usual.
The Word rendering extension is based on the Image rendering extension, with some differences. For information common to both formats, see Image Rendering Design Considerations. This topic describes features that are specific to the Word rendering extension.
Rendering
The report exported to Word appears as a nested table that represents both the report layout and content. Nested data region items, such as SubReport, Table, Crosstab, or List items are rendered as nested tables that reflect the layout and structure of that data region in the report. Due to the way Word renders these nested items, their borders may be misaligned or appear drawn with double lines if the nested item has its own border style. Other items are rendered as separate cells within the same table. The item’s value is rendered as content in the table cell. PictureBox, Chart, Barcode, and Shape items are rendered as static images in the cell. URL actions of TextBox items are rendered as hyperlinks, as soon as they represent absolute URLs. The relative ones are not respected and are not rendered in Word.
Word tables support a maximum of 63 columns. Reports with very complex layout or many misaligned items might sometimes produce documents exceeding that limit. To avoid this, align your items carefully in the designer, using the "snap to lines" and "snap to grid" modes whenever possible. To organize many items together in columns and rows consider using the Table, Crosstab or List report item instead.
Since report items are rendered as individual table cells they cannot overlap. If you have overlapping items in the report definition, the resulting document is undefined, i.e. this would break the report layout. If there are no overlapping items the original layout is preserved. In general, avoid having overlapping items at design time if you are planning to export the report to Word.
Pagination
Microsoft Word does not support the concept of hard pages. Instead, when the exported document is opened in Word, Word repaginates it again based on the page size. The rendering extension tries to preserve closely the original pages of the report, inserting additional page breaks when necessary. However, in some rare cases, the repagination performed by Word might interfere with this behavior, resulting in a document with page breaks on unexpected places or blank pages. To correct this, you can try changing the Word’s pagination by adjusting the page margins.
Page Sizing
When the report is rendered, the page size, orientation, and margins are configured in the document according to the corresponding properties in the report definition. For ReportBook the page settings of each individual report in the book are respected. This can produce a document with varying page sizes and orientation per report.
Word supports a maximum page size of 22 inches wide and 22 inches high. If your page is wider than 22 inches, some data may not be displayed in the Print Layout view.
Page Headers and Footers
Report’s PageHeaderSection and PageFooterSection are rendered as header and footer regions in the document. For ReportBook the page sections of each individual report in the book are respected. This can produce a document with varying page headers and footers per report.
Word does not support configuring explicitly the height of headers and footers. Instead they are sized automatically according to their content.
Page Columns
Newsletter-style multi-column reports are rendered as multiple columns in Word.
Since Word repaginates the entire document when opening it, the same behavior is applied to multi-column documents as well. The rendering extension tries to preserve the original organization of the report in columns by inserting column breaks when necessary. However, in some rare occasions, the repagination performed by Word might interfere with this behavior resulting in column breaks in unexpected places or empty columns. To correct this, you can try changing the Word’s pagination by adjusting the column spacing or page margins.
Styling
The following is a brief description of how styles are rendered in Word.
-
Colors- Colors are rendered as exact RGB values. Transparent colors with alpha channels are not supported. -
Borders- Borders of report items are rendered as table cell borders. Borders of adjacent report items are collapsed automatically, following the Word’s own border-collapse rules.Word application applies a margin value to the table cell by default. This will produce a space between the nested table borders and the parent table borders. To remove the space, the margin needs to be removed manually after opening the document in MS Word.
Background- Background colors are rendered as background shading of table cells. Background images are not supported.-
Fonts- Fonts and their settings are rendered exactly as they are specified in the report definition. To display correctly a document that uses a specific font, that font must be installed on the client machine. The rendering extension does not provide a fallback mechanism in case of missing fonts.Text boxes that do not contain a value (contain a null value, empty string, etc.) will be rendered with a font size of 1pt.
Text- Text justification and alignment are preserved when exporting to Word. Note that if a justified text goes from one page to another, the last line of the first page will be left-aligned. Text orientation is supported only for the angles of 0, 90, and 270 degrees. Rotated text on other angles is not supported and is approximated to the closest match.-
HTML- HTML text is rendered using Word’s own HTML rendering engine. This might produce a result that is slightly different from the output generated in Web browsers.
Report items
The following rules apply to rendered report items:
- The PictureBox report item's Sizing property should be set to AutoSize for best image quality or the PictureBox.Size should match the actual image size. In case you get a blurred image at run-time, change the Sizing mode or resize the PictureBox item to match the size of the produced image.
- The Cross-Section item renders its graphical primitives as images. It is recommended to set the Position property to
Frontto allow rendering it on top of the other items. Otherwise, the Word application may apply an undesired offset to it. - The Checkbox item is rendered in two parts. The Checked status is shown as an image, and the Text value is displayed as text beside it.
Interactivity
The supported interactivity actions are Navigate to URL and Navigate to Bookmark.
URL actions on report items are rendered as hyperlinks in the Word document. When you click the hyperlink, the default Web browser opens and navigates to the specified URL.
Actions on report sections are not supported.
Limitations
Text Watermarks do not support strikethrough and underline text decorations.