Customizing Microsoft Word Report Configuration Files

Microsoft Word reports can be configured by four types of Microsoft Word report template (.word) files. Nearly everything related to report layout, colors, fonts and layout can be configured using these XML files.

Page style-specific configuration file

This file is located in your application’s Reports folder. Each application has only one copy of this file, typically “WordReport.word”.

...\<App Name>\Reports\WordReport.word

This template file is shared by all Microsoft Word reports in your application. It specifies page style-specific properties. When you select a different page style in the Application Wizard, a new copy of this file is automatically copied into your application’s Reports folder for the newly selected page style.

Language-specific configuration file

This file is located in your application’s Reports folder, one copy for each language used in your application. For example, the English language file is WordReport en.word.

...\<App Name>\Reports\WordReport.en.word

Language-specific report templates are shared by all Microsoft Word reports in your application. When you select new languages or culture in the Application Wizard, a copy of the language-specific configuration file is copied into your application’s Reports folder for the selected language.

The file’s template is located in:

...\<Iron Speed Designer Installation Folder>\ProjectTemplates\Reports

Iron Speed Designer does not provide this file for all languages; however, you can create one for the language you need by copying the English version (en) and customizing it.

Culture-specific configuration file

This file is located in your application’s Reports folder, one copy for each culture used in your application. For example, the English (United States) file is WordReport.en-us.word.

...\<App Name>\Reports\WordReport.en-us.word

Culture-specific configuration files are shared by all Microsoft Word reports in your application. When you select new languages or cultures in the Application Wizard, a copy of the culture-specific configuration file is copied into your application’s Reports folder for the selected culture.

The file’s template is located in:

...\<Iron Speed Designer Installation Folder>\ProjectTemplates\Reports

Iron Speed Designer does not provide this file for all languages; however, you can create one for the language you need by copying the American English version (en-us) and customizing it.

Button-specific configuration file

This file is located in each page folder, one copy for each Microsoft Word report in your application. The file name is in the format:

<Page>.<Button Control Name>.word

For example, if you have a Microsoft Word report button named CustomersWordButton, a report configuration file called “ShowCustomersTable.CustomersWordButton.word” is automatically created.

...\MyApp\Customers\ShowCustomersTable.CustomersWordButton.word

When you change the Microsoft Word report buttons’ control names, Iron Speed Designer renames the corresponding button-specific configuration files to match the new control names. If you add a Microsoft Word report button or change the Microsoft Word report button’s properties via the Property Sheet, a button-specific configuration file will be created for your Microsoft Word report button. If you remove the Microsoft Word report button or change its properties, the corresponding button-specific configuration file will be removed.

The .word file schema structure and organization

Page style-specific, language-specific and culture-specific report configuration files have the same schema. Button-specific configuration files, however, have a different schema because each Column tag in the file specifies properties for a particular column.

PDFReport1

Main schema organization

PDFReport2

The Font tag and its related parent tags

PDFReport5

The Style tag and its children


The Column tag and its children for a button-specific file (left) and other .word file (right).

Here are the appropriate values you can use in the XML tags:

Parameter
(Tag / Node)

Where Used
(Parent Node)

Values

PageHeight

Report

Specifies the report’s page height.

CulturalDefaultForLandscape	Apply either 8.5in or 210mm as the page height according to the culture.
CulturalDefaultForPortrait	Apply either 11in or 297mm as the page height according to the culture.
Decimal number	Specifies the page height as a decimal number. The units of measure are “pt”, “cm”, and “mm”.

Default value is CulturalDefaultForLandscape.

PageWidth

Report

Specifies the report’s page width.

CulturalDefaultForLandscape	Apply either 11in or 297mm as the page width according to the culture.
CulturalDefaultForPortrait	Apply either 8.5in or 210mm as the page width according to the culture.
Decimal number	Specifies the page width in decimal number. The units of measure are “pt”, “cm”, and “mm”.

Default value is CulturalDefaultForLandscape.

LeftMargin

Report

Specifies the report’s left margin as a decimal number.

The units of measure are “pt”, “cm”, and “mm”.

Default value is 0.5 in.

RightMargin

Report

Specifies the report’s right margin as a decimal number

The units of measure are “pt”, “cm”, and “mm”.

Default value is 0.5 in.

TopMargin

Report

Specifies the report’s top margin as a decimal number.

The units of measure are “pt”, “cm”, and “mm”.

Default value is 0.5 in.

BottomMargin

Report

Specifies the report’s bottom margin as a decimal number.

The units of measure are “pt”, “cm”, and “mm”.

Default value is 0.5 in.

Top

BorderWidth

Specifies the top border’s width as a decimal number.

The units of measure are “pt”, “cm”, and “mm”.

Default value is 0.5 pt.

Top

Padding

Specifies the top padding height as a decimal number.

The units of measure are “pt”, “cm”, and “mm”.

Default value is 1 pt.

Top

BorderColor

Specifies the top border’s color as a 6 digit hex number.

Default value is ffffff.

Top

PageHeader

Decimal number represents the distance between the top edge of the page and the top of the page header.

The units of measure are “pt”, “cm”, and “mm”. “pt” is the default unit of measure if none is specified.

Default value is 1 pt.

Bottom

BorderWidth

Specifies the bottom borders’s width as a decimal number.

The units of measure are “pt”, “cm”, and “mm”.

Default value is 0.5 pt.

Bottom

Padding

Specifies the bottom padding as a decimal number.

The units of measure are “pt”, “cm”, and “mm”.

Default value is 1 pt.

Bottom

BorderColor

Specifies the bottom borders’s color as a 6 digit hex number.

Default value is ffffff.

Bottom

PageFooter

Specifies the distance between the bottom edge of the page and the bottom of the page footer as a decimal number. “pt” is default units.

The units of measure are “pt”, “cm”, and “mm”. “pt” is the default unit of measure if none is specified.

Default value is 1 pt.

Left

BorderWidth

Specifies the left border width as a decimal number.

The units of measure are “pt”, “cm”, and “mm”.

Default value is 0.5 pt.

Left

Padding

Specifies the left padding size as a decimal number.

The units of measure are “pt”, “cm”, and “mm”.

Default value is 1 pt.

Left

BorderColor

Specifies the left border’s color as a 6 digit hex number.

Default value is ffffff.

Right

BorderWidth

Specifies the right border’s width as a decimal number.

The units of measure are “pt”, “cm”, and “mm”.

Default value is 0.5 pt.

Right

Padding

Specifies the right padding size as a decimal number.

The units of measure are “pt”, “cm”, and “mm”.

Default value is 1 pt.

Right

BorderColor

Specifies the right border’s color as a 6 digit hex number.

Default value is ffffff.

Color

Font

Specifies the color of the body text font.

The color code is a 6 digit hex number.

Default value is ffffff.

BackgroundColor

Style
AltStyle

Specifies the background color as a 6 digit hex number.

Default value is 000000.

Italic

Font

True	Display the text in italics.
False	Do not display the text in italics.

Default value is False.

Bold

Font

True	Display the text as boldface.
False	Do not display the text as boldface.

Default value is False.

Underline

Font

True	Display the text as underlined.
False	Do not display the text as underlined.

Default value is False.

TextDirection

Font

LeftToRight	Display the text from left to right on the page.
RightToLeft	Display the text from right to left on the page.
LanguageDefault	Display the text based on the language or cultural default.

Default value is LanguageDefault.

Encoding

Font

Unicode	Encode the text using Unicode encoding.
None	Do not Unicode encode the text.

Default value is Unicode.

FileName

Font

Specifies the True Type font used for the report text. True Type font files have a “ttf” extension. These files are located in the “fonts” folder under the Microsoft Windows installation directory.

Iron Speed Designer only supports True Type fonts, so Chinese, Japanese, or Korean (CJK) characters can not be used in the report.

Note: When Unicode is applied, some font files cannot be used. For example, Arial supports all non-CJK (Chinese, Japanese, and Korean) strings such as Hebrew or German, but Verdana does not support Unicode.

Default value is Arial.ttf

VerticalAlign

Style

Top
Bottom
Middle
Center Middle	Middle and Center are identical.

Iron Speed Designer only supports “Top” alignment for column text.

Default value is Top.

HorizontalAlign

Style

Top
Bottom
Middle
Center Middle	Middle and Center are identical.

Default value is Default.

Size

Font

Specifies the size of the body text font as a decimal height in points (“pt”). “pt” is unit of measure.

Default value is 8 pt.

Value

LeftHeader
LeftFooter
RightHeader
RightFooter
CenterHeader
CenterFooter
Header
Detail

Specifies the text to be displayed in the page header, page footer, and table detail.

Default value is an empty string.

ReportDirection

Report

LeftToRight	Display the columns from left to right on the page.
RightToLeft	Display the columns from right to left on the page. If RightToLeft is chosen, columns’ order is ‘reversed’ from most European languages, which display left to right. Also, the left and right alignments are swapped throughout the report.
LanguageDefault	Display the text based on the language or cultural default.

Default value is LanguageDefault.

Width

Column

Specifies the column width as a relative width of the column. The actual column width is prorated based on the widths of all of the columns included in the page and the report’s page width.

Default value is 100.

Applying properties specified in .word configuration files

When an application user clicks a “Microsoft Word report” button in your application, it reads and applies the .word files in this order:

Button-specific configuration file (e.g., ShowEmployeesTable.EmployeesWordButton.word)
Culture-specific configuration file (e.g., WordReport.en-CA.word)
Language-specific configuration file (e.g., WordReport.en.word)
Page style-specific configuration file (e.g., WordReport.word)

Let’s assume you have specified at least one column in the button-specific configuration file. While a report is created, your application attempts to apply the properties specified in the button-specific configuration file. If some properties are not available, it will then look for the missing properties in the culture-specific configuration file. If some are also not available in that file, it will look in the language-specific configuration file. Finally, if they are not specified in the language-specific configuration file, it will find them in the page style-specific configuration file. If a property is not specified in any of these files, then default properties will be used.

The properties specified in the button-specific configuration file have the highest priority. If their properties are specified in the right format, they can override properties specified in the other files. If the properties are inappropriate, for example, the color codes are not six digit hex numbers, they will be discarded.

The following example illustrates how to override various properties in the .word files.

WordReport.word:

<Style>

<Font>

<Color>ffffff</Color>

<FileName>Arial.ttf</FileName>

<Bold>False</Bold>

<Italic>False</Italic>

<Underline>False</Underline>

</Font>

</Style>

</Header>

<Style>

<Font>

<FileName>Verdana.ttf</FileName>

<Bold>False</Bold>

<Italic>False</Italic>

<Underline>False</Underline>

</Font>

</Style>

</Detail>

</Column>

</Columns>

WordReport.en.word:

<Style>

<Font>

<FileName>Arial.ttf</FileName>

</Font>

</Style>

</Header>

<Style>

<Font>

<FileName>Arial.ttf</FileName>

<Italic>False</Italic>

</Font>

</Style>

</AltStyle>

</Detail>

</Column>

</Columns>

Word.en-CA.word:

<Style>

<Font>

<Color>ffffff</Color>

<FileName>Ariaal.ttf</FileName>

</Font>

</Style>

</Header>

<Style>

<Font>

<FileName>Arial.ttf</FileName>

</Font>

</Style>

</AltStyle>

</Detail>

</Column>

</Columns>

ShowEmployeesTable.EmployeesWordButton.word:

<Value>First Name</Value>

</Header>

<Value>${Customers.FirstName}</Value>

<Style>

<Font>

</Font>

</Style>

</Detail>

</Column>

<Style>

<Font>

<Underline>False</Underline>

</Font>

</Style>

</Header>

<Value>${Customers.LastName}</Value>

<Style>

<Font>

</Font>

</Style>

</Detail>

</Column>

</Columns>

Overridden result:

<Value>First Name</Value>

<Style>

<Font>

<Color>ffffff</Color>

<FileName>Arial.ttf</FileName>

<Color>ffffff</Color>

<Bold>False</Bold>

<Italic>False</Italic>

<Underline>False</Underline>

</Font>

</Style>

</Header>

<Value>${Customers.FirstName}</Value>

<Style>

<Font>

<FileName>Arial.ttf</FileName>

<Italic>False</Italic>

<Bold>False</Bold>

<Underline>False</Underline>

</Font>

</Style>

</AltStyle>

</Detail>

</Column>

<Style>

<Font>

<Color>ffffff</Color>

<FileName>Arial.ttf</FileName>

<Bold>False</Bold>

<Italic>False</Italic>

</Font>

</Style>

</Header>

<Value>${Customers.LastName}</Value>

<Style>

<Font>

<FileName>Arial.ttf</FileName>

<Italic>False</Italic>

<Bold>False</Bold>

<Underline>False</Underline>

</Font>

</Style>

</AltStyle>

</Detail>

</Column>

</Columns>

In the example, the button-specific configuration file contains two Column tags. Each Column tag specifies properties for a particular column. However, the other .word files can specify one Column tag only because the properties specified in this tag are shared by all columns. How can the button-specific configuration file override the other .word files? When your application determines the overridden result, Column tags in the first three files are cloned to the amount matching the button-specific configuration file. Then your application searches the appropriate values from the button-specific configuration file to the page style-specific configuration file in order to produce the overridden result. If a .word file is missing or was not written in the appropriate XML format, your application will move on to the next file in the hierarchy.