Customizing PDF Report Configuration Files

PDF reports can be configured by four types of PDF report template (.report) 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 “PDF.report”.

...\<App Name>\Reports\PDF.report

This template file is shared by all PDF 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 PDF.en.report.

...\<App Name>\Reports\PDF.en.report

Language-specific report templates are shared by all PDF 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 PDF.en-us.report.

...\<App Name>\Reports\PDF.en-us.report

Culture-specific configuration files are shared by all PDF 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 PDF report in your application. The file name is in the format:

<Page>.<Button Control Name>.report

For example, if you have a PDF report button named CustomersPDFButton, a report configuration file called “ShowCustomersTable.CustomersPDFButton.report” is automatically created.

...\MyApp\Customers\ShowCustomersTable.CustomersPDFButton.report

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

The .report 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 .report file (right).

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

Parameter
(Tag / Node)

Where Used
(Parent Node)

Values

BackgroundColor

Style
AltStyle

Specifies the background color as a 6 digit hex number.

Default value is 000000.

Bold

Font

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

Default value is False.

Bottom

BorderColor

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

Default value is ffffff.

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

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.

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.

Color

Font

Specifies the color of the body text font.

The color code is a 6 digit hex number.

Default value is ffffff.

Encoding

Font

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

Default value is “Unicode”.

Note: This parameter has no effect when running your application in Medium Trust mode.

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

Note: This parameter has no effect when running your application in Medium Trust mode.

HorizontalAlign

Style

Top
Bottom
Middle
Center Middle	Middle and Center are identical.

Default value is Default.

For more information regarding to Default, visit Horizontal alignment for PDF report

Italic

Font

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

Default value is False.

Left

BorderColor

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

Default value is ffffff.

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.

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.

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.

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.

Right

BorderColor

Specifies the right 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.

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.

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.

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.

Top

BorderColor

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

Default value is ffffff.

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

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.

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.

Underline

Font

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

Default value is False.

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.

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.

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 .report configuration files

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

Button-specific configuration file (e.g., ShowEmployeesTable.EmployeesPDFButton.report)
Culture-specific configuration file (e.g., PDF.en-CA.report)
Language-specific configuration file (e.g., PDF.en.report)
Page style-specific configuration file (e.g., PDF.report)

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 .report files.

PDF.report:

<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>

PDF.en.report:

<Style>

<Font>

<FileName>Arial.ttf</FileName>

</Font>

</Style>

</Header>

<Style>

<Font>

<FileName>Arial.ttf</FileName>

<Italic>False</Italic>

</Font>

</Style>

</AltStyle>

</Detail>

</Column>

</Columns>

PDF.en-CA.report:

<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.EmployeesPDFButton.report:

<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 .report 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 .report 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 .report file is missing or was not written in the appropriate XML format, your application will move on to the next file in the hierarchy.