Export to Native Word

Exporting reports into Microsoft Word documents is a popular method of formatting and presenting data, and this topic discusses the related techniques.



About Exporting Reports to Native Word

Exporting data into a Word document allows for additional formatting to be applied, and for narrative text to be included with visualizations. Logi Info includes specific elements for exporting data into documents that can be edited using Microsoft's widely-used Word program.

 Aways use the Action.Export Native Word element in your Logi applications. Earlier versions of Logi Info used the deprecated Action.Export Word Or Excel element and it's been retained in Logi Studio only for backward compatibility.
 

Manual or Programmatic Export

You can configure your application to export data to Word in two ways:

  • Manually - The user clicks a link or button in a report to initiate the export and the result is made available for viewing in a browser or can be saved locally. The export elements are added into the report definition.
     
  • Programmatically - The export occurs when a Process Tasks executes, triggered by an user-initiated event or scheduled event, and the result is written out as a Word file on the web server. The export elements are added into the process definition.

You may use both techniques in the same application.

 

Exporting a Report Manually

Here's an example of how to create a report with a link that exports manually:
 

     

  1. In your Report definition, add an Action.Export Native Word element to a Label, Image, Button or Chart element, as shown above.
  2. Add the required Target.Native Word element.
  3. If the report to export is the current report, you don't need to do anything else. Just save your definition and browse your report; it's that simple.
  4. All Target.Native Word element attributes are optional. The default settings will export the current report in its entirety.
  5. If the report to export is not the current report, specify that report by setting the Target.Native Word element's Report Definition File attribute.
  6. The exported file will be given a random file name and a .doc file extension (Word 2003 and earlier) unless you specify a specific file name and the .docx extension (Word 2007+) in the Export Filename attribute.

What Happens: The report is exported to a temporary file which is created in your project folder's rdDownload folder on the web server. The temp file is then returned to the client and opened in your browser. You may be prompted to View or Save the file. Temporary files on the server are cleaned up automatically over time.

 

Exporting a Report Programmatically

The following example, for Logi Info only, shows how to create a process task that exports data programmatically:
 

     
  1. In your process definition, add a Task element.
  2. Add a Procedure.Delete File element beneath the Task. The export will not overwrite an existing file so this element is used to delete any older version before the export occurs; no error will occur if there's no existing file to delete.
  3. Add a Procedure.Export Native Word element beneath the task, as shown above.
  4. In both elements' Filename attribute, specify the output path and filename on the web server for the exported document. The filename should include the .doc or .docx file extension. In the example above, this value uses a token to export the report to a folder called myExports within your project folder: @Function.AppPhysicalPath~\myExports\myfile.docx



     
  5. Add the required Target.Native Word element, as shown above.
  6. In the element's Report Definition File attribute, specify the report definition to be exported. Note that, in a Process definition, the "CurrentReport" option that appears in the suggested values for this attribute cannot be used. You must specify the actual name of the report.

What Happens: When your task runs, the specified report will be exported to a temporary file in your project folder's rdDownload folder on the web server; the temp file is then copied to your output file.

 

Adding Exported Headers and Footers

Exported reports are paginated and you may want to have a report header and/or footer appear on each exported page. This can be done, without affecting the normal appearance of the HTML report output in a browser, using the Printable Paging element.
 


As shown above, the Printable Paging element has been added beneath the report's top-level Report element. It has its own Page Header and Page Footer child elements which are containers for Label elements. In the example above, the captions of the footer label could use the @Date.Today~ and @Function.PageNumber~ tokens to get their values.

When the report is run, the header and footer under the Printable Paging element will not be visible. When the report is exported, the header and footer will be visible on each exported page.

 

Forcing Page Breaks in Exports

When a report is paginated during an export, it may be useful to be able to force a page break, for example, to ensure that sections of the report start on new pages. This can be done using the Printer Page Break element.
 

You can add one or more Printer PageBreak elements beneath the Body element to break the exported pages where desired. In the example above, these elements ensure that the "dtProducts" table and the "dtOrders" table start on new pages. When the report is viewed in the browser, however, like the Printable Paging element, the Printer Page Break element has no effect.
 

Forcing a Data Table Row Break

When working with data tables with multi-line rows, you may want to ensure that rows break cleanly across pages of their Word exports. In other words, they want to prevent different lines of the same data table row from appearing on different Word document pages. This can be accomplished through CSS, using code like:

.noPageBreakCell { page-break-inside: avoid; }

Assigning the above class to a Data Table Column element will create the desired effect.

Hiding Elements When Exporting

When exporting to Word, you commonly want to hide some of the elements in the report page, like the Export button or link. This can be done very easily using Show Modes, see Show Modes.
 

In the example shown above, the definition on the left includes a Label (styled as a button) that can be clicked to export the report to Word. However, when it's exported, shown on the right, the Export button appears in the Word document. We don't want that text to appear in the document.
 

To "hide" the button in the exported document, simply place the elements beneath a Division element, as shown above. This element supports Show Modes, which the Label does not. Then set the Division element's Show Modes attribute value to the built-in rdBrowser value, as shown above. Elements with this ShowMode value will only be visible in the browser.
 

When the report is run and exported, as shown above, the document no longer includes the "Export to Word" button.

 

Exporting More Info Rows

If your report contains a data table and you're using the More Info Row element to show/hide additional detail data within the table, you may want the detail rows (when visible) to be exported along with the main table data.
 

To enable this, as shown above, set your Target.Native Word element's Keep Show Elements attribute to True. Keep Show Elements works with Action.Show Elements (used to show/hide the More Info Row) so that items that have been shown or hidden by the user remain that way when the report is re-displayed or

 

Cascading Style Sheet Support

When a Word export is being generated, the export engine processes any style sheet information along with the report data. The style sheet assigned to the report is used; you do not need to do anything additional to specify the style sheet. If desired, you can use two different style sheets in your report definition, one for the report and one for the Word export:

  1. Select the root element of your report definition and set its Default Show Modes attribute value to an arbitrary string, such as "Normal".
  2. Add two Style Sheet elements to your report definition.
  3. Assign one Style Sheet element's Show Modes attribute a value that matches the string used in Step 1, "Normal". This style sheet will be used for the regular HTML report.
  4. Assign the other Style Sheet element's Show Modes attribute a value that matches the Target.Native Word element's Report Show Modes attribute value (both should be an arbitrary string that does not match the string from Step 1, such as "Export".

Now when the report runs in a browser, the first style sheet will be applied; when it's exported to Word, the second style sheet will be applied. What if you want to combine the effects from this section and the previous section, i.e. hide some elements and use different spreadsheets? Just remember that the Show Modes attribute can accept several values, separated by a comma. To combine the examples from these two sections, ensure that the root element's Default Show Modes attribute includes both Show Modes values: "Normal,NoExport" (do not enter the double quotes).

  The following considerations should be noted when working with style sheets for Word exports. Failure to follow these guidelines will result in style sheet information being ignored by the Word exporter, or, in some cases, failure of the export process.

  1. When defining CSS classes in their style sheet(s), you must include a space or line feed between the name of a class and the opening curly-brace. These are valid classes:

    .myClass1{ color: Blue; }
    .myClass2
    {
        color: Blue;
    }

but this is in invalid class:

    .myBadClass{ color: Blue; }

  1. You may combine classes using the CLASS attribute of elements in a report definition file:
    CLASS="class1 class2"
  1. You must use the Width and Width Scale attributes when setting table and cell widths. The CSS "width" property is not supported.
  2. If duplicate class definitions exist, only the first definition is used.
  3. If duplicate properties appear inside a class, only the last occurrence is used. 
  4. The following CSS Selectors are supported by the Word export engine:
     

    Selector

    Example

    Type
    TABLE
    Class
    .<classname>   (begins with a period)
    ID
    #second_table
    Type-prefixed Class
    TABLE.<classname>
     
  1. The following CSS Level 1 Properties are supported by the Word exporter. Please note that the order of the values for properties with multiple values is significant. Multiple values must be listed in the order defined in this table or the Word exporter will ignore the property altogether:
     

    Property

    Value/Examples

    background<background-color>
    background-colorWeb colors (examples: #00FF00 or Green)
    border <border-width> <border-style> <border-color>
    <border-style> <border-color>
    <border-color>
    border-bottom <border-width> <border-style> <border-color>
    <border-style> <border-color>
    <border-color>
    border-colorWeb colors (examples: #00FF00 or Green)
    border-styleExample: solid
    border-top <border-width> <border-style> <border-color>
    <border-style> <border-color>
    <border-color>
    border-widthPixels (example: 25px)
    color Web colors (examples: #00FF00 or Green)
    filterExamples: flipv, fliph
    font <font-style> <font-weight> <font-size> <font-family>;
    font-familyBase-14 & TrueType fonts (example: Arial)
    font-sizePoints (example: 12pt)
    font-styleExample: italic
    font-weightExample: bold
    padding<padding-top> <padding-right> <padding-bottom> <padding-left>
    heightPixels (example: 25px)
    padding-topPixels (example: 25px)
    padding-right Pixels (example: 25px)
    padding-bottom Pixels (example: 25px)
    padding-left Pixels (example: 25px)
    text-align (see Note below)Examples: left, right, center, justify
    text-decorationExamples: underline, overline
    vertical-alignExamples: top, middle, bottom
    writing-mode Examples: lr-tb, tb-rl


Style Tips:

  • With a limited list of CSS properties, if Native Word exporting is going to be used in an application, it's a good idea to design the CSS classes used for elements to be exported with these limitations in mind. That way a single style sheet could be used for all exports and the HTML display of a report. Many of these property limitations stem from the fact that there isn't a good way to translate certain CSS properties into a formatting setting in a native Word document; the formatting options available in a native Word document are much more limited than those available with CSS.
     
  • When it comes to specifying font-size, Word can't handle pixel values. All pixel values specified in CSS classes for font-size will be converted to point values. Therefore, it's highly recommended that points be used to specify the font-size.
     
  • Word builds tables sequentially, cell-by-cell, left-to-right, top-to-bottom. Word will attempt to apply all the properties of the previous cell to the cell currently being created unless the properties are explicitly defined differently for the current cell using a different CSS class which overwrites all the properties of the previous cell. For instance, if the first cell has a "border-bottom: 1px solid black;" class applied and you want the next cell to appear without a bottom border, you would have to apply a class with the following property: "border-bottom: 1px solid white;".
     
  • Use text-align to set the alignment of tables. This is not generally allowed by the rules of CSS, however, an exception is made because the align attribute is not supported.
 

Debugging Exports

When the debugger has been set to Debugger Links and the report is run, and then exported, a debug link will be included at the bottom of the exported report:
 

This mechanism allows you to review the export process in more detail and can help to diagnose any problems that may arise.

 

Export Considerations

The following apply when exporting to Word:

  • Chart color transparency is not available in exports to Word. Non-animated charts displayed in Logi HTML reports are rendered as .png images and support transparency, however, when exported to Word, these charts are rendered as .jpg images, which do not support transparency.
  • Embedded HTML files in a Logi report may not be exported correctly; success is dependent on the nature of the external HTML file, its adherence to proper XHTML syntax, and other factors.
  • Background colors are only applied within tables
  •  Bulleted lists are not supported (using the Bullet element)
  • Rectangle element is not supported
  • Layout Positioning is not supported
  • HideDuplicates element is not supported
     
keywords: MoreInfoRow