Date and Number Formatting¶
Using the Report Designer tool dates and numbers can be formatted to suit your requirements. In general when a dates and numbers are formatted two factors are taken to account, that is the formatting style and the locale. The formatting styles are based on Java and is specified in the layout using the tool and the locale represents the Language and Country in which the report will be run. When a date is formatted the formatting styles defined on the layout is applied on the data. However, the formatting style will be dependent on the locale, therefore the same formatting style maybe represented differently when the locale differs. This is because different locales have different representations (separator symbols and so on) of dates/times and numbers.
The Report Designer Tool provides a number of options for selecting locale and formatting styles for both numbers and dates. Below we will look at this formatting options in detail.
The default calendar used by the tool for formatting dates is the Gregorian calendar. It is also possible to use a Persian calendar instead when working with Arabic, Farsi like languages. Read Date Formatting based on Persian calendar for more details. This page continues to describe date/time formatting based on the widely and commonly used Gregorian calendar system.
To apply formatting styles, select the right mouse button menu option Format->Format Date of the table-cell or block container that has the date/time field to be formatted.
You will be presented with the following dialog.
The Format Date Dialog gives you a range of formatting styles to choose from, options on how you would like to fetch the locale, preview options and other useful help/info.
Use the Format section of the dialog to specify the formatting style and define how the locale should be fetched, whether in runtime or design time or not consider the locale at all ( custom format masks). There are three ways in which you can format a date/time. The recommended approach is to format the date based on the locale supplied in runtime. Second approach is where the locale is specified in design time (hardcoded locale) and the third is to use one of the predefined custom format masks. These methods are discussed in detail below.
Formatting dates based on locale supplied at runtime¶
In this approach the date/time is formatted in the following manner. There are number of date/time formatting styles available from the Format Date dialog, namely Short, Medium, Long, Full and None. These are Java based formats and are specified in the layout by the user while the locale is fetched in runtime. When the report is run, the dates are formatted to represent the formatting style specified in the layout, based on the locale fetched.
In the above sample form, the date is set to be formatted based on locale supplied at runtime. The formatting styles Short and Medium are applied on date and time respectively. For example consider the date 03-29-2005 and time 2.55 PM.Say the locale fetched in runtime is English (united States) and the formatting styles applied are Short and Medium as specified above. The Short date format and date separator for English (united States) in Java is "M/d/yyyy" and "/" respectively. Therefore the resulting output will be "3/29/2005". The formatting style Medium for this locale is "h:mm:ss tt" where tt is am or pm and the time separator is ":". Therefore, the time 2.55 PM when formatted will be "2:55:31PM".
Remember, for a different locale, the representation of formatting styles Short and medium may differ.
The locale being fetched in runtime differs depending on whether the report is being previewed or if it is being printed to a logical or physical printer. If the report is being previewed, the locale is fetched from the client machine, that is the locale specified in your PC's Regional and Language Options. For example English (United States) as selected in the diagram below.
Similarly, if the report is being printed to a physical printer, the locale set on the client machine (same as above) is used for date/time formatting. In both these scenarios the effect will be that dates are formatted according to the client locale. In contrast, when a report is printed to a logical printer the locale specified for that specific background job (in the Report Formatter configuration in IFS Solution Manager) is used. In a scenario where there is more than one Report Formatter (one for each locale), it will be a matter of what printer is chosen since different Report Formatters will only pick jobs bound for the specific printers in it's list. The final effect will be that dates are formatted according to the locale specified in the corresponding Report Formatter.
Note: Customizations done to Regional and Language Options using the Customize button (see above form) will not be reflected when formatting dates. This applies to both dates as well as numbers. It is only the locale that will be taken from the client, the customizations to date separator symbols, non default short and long date formats are not considered by the formatter.
Still in the topic of Regional and Language Options, you may have noticed the two formatting styles Short date and Long date listed under the Regional Options tab (marked in red squares). Note that, these two are Windows based date formats whereas the formats available from the Format Date Dialog: Short, Medium, Long and Full are java based date formats. Out of which the two common formats Short and Long , in both Windows and Java are more or less similar in most cases. Important thing to keep in mind is that when dates are formatted in Report Designer it is the Java based short, long, medium, full formats defined in the tool that will be applied and not the Windows based formats available on Regional Options.
Formatting dates based on locale supplied at design time (hardcoded)¶
Here, the locale to be used when formatting dates is specified in the layout it self. In other words the locale is hardcoded on the layout along with the formatting styles to be used. First select the formatting styles to be applied on the date and time using the Date Format and Time Format combo fields. Now, select the checkbox Hardcode locale in layout for this field and choose the locale from the list of values provided. When the report is executed the date will always be formatted based on the Swedish locale irrespective of what the locale supplied in runtime is.
Based on the settings above, the corresponding date will be formatted using the Swedish representation of the formatting style Long. Since the formatting style for time is None, time will not be shown. The locale Swedish (Sweden) that is specified in the layout overrides the runtime locales.
Formatting dates with Custom format masks¶
A Custom format mask is a pre defined formatting style. When a date/time is formatted based on a format mask neither the locale nor the formatting styles short,medium,long etc. (as used in the previous approaches) are considered. The resulting output will always take the form and shape of the specified format mask irrespective of what the locale supplied in runtime. To set a custom format mask select the Use custom format mask option and select a matching mask.
Based on the sample form above, the corresponding date and time will always be formatted as MM/dd/yy and H:mm:ss respectively.
Numbers in your XML data can also be formatted in a similar fashion as dates. The formatting is done based on the locale and the formatting criteria specified in the layout. Decimal Symbol, Digit grouping symbol, Minimum integer digits, Digit grouping size are some of the settings specified in the layout and later used for formatting. To format a number first select the number field to be formatted from the layout, right mouse click on the table-cell or block container and select Format -> Format Number.
You will be presented with the Format Number Dialog depicted below.
Under the Format section of the dialog you will find a set of properties such as Decimal Symbol, Minimum integer digits, Digit grouping symbol, Digit grouping size that has to be specified. Note that if the number being formatted is of type integer the properties Minimum digits after decimal and Maximum digits after decimal will not be shown in the dialog. These two fields are only visible for numbers of type float. Using the dialog it is also possible to preview the output for the selected settings using sample data. See the Sample section of the dialog.
Numbers can be formatted in several ways. This depends on whether or not the locale is taken from runtime or design time or if the number being formatted is a currency field or not. These options are discussed in detail below.
Formatting numbers based on locale supplied at runtime¶
If the requirement is to format the number based on runtime then this is the option for you. Simply select the option Base on locale for the formatting properties available on the dialog. As the name describes, the formatting will be based on the locale, that is the locale fetched at runtime.
As discussed in formatting of dates the locale used in runtime is differs depending on the print/preview request made. If the report is being previewed or printed to a physical printer the locale of the client machine is taken as the runtime locale. Therefore numbers are formatted according to the client locale. On the other hand if the report is being printed to a logical printer the locale specified for that specific background job (Report Formatter) is used as the runtime locale. Thereby numbers are formatted based on the locale of the corresponding Report Formatter.
In the above sample form all formatting properties (except Negative number format) is set to use Base on locale option. Say the report is printed to a local printer (physical) and the locale set in the client machine is English (united States) then properties such as Decimal symbol and Minimum integer digits will have values corresponding to the client locale which is English (united States).
Formatting numbers based on custom values¶
Another variation of run time formatting is to specify customized values for the properties. This way, the custom value will be applied on the property instead of the value returned from the runtime locale.
Looking at the sample form above the value for Decimal Symbol is set to the custom value ",". If the runtime locale is English (United States) then the value returned from the runtime locale will be "." (decimal symbol for English local). Therefore the resulting number will be formatted according to the run time locale with the exception of Decimal Symbol formatted according to the custom value "," you have chosen.
Formatting numbers based on locale supplied in design time (Hardcoded)¶
If a number should be formatted based on a predefined locale then this is the option to be selected. Simply select the checkbox Hardcode locale in layout for this field and specify the locale of your choice from the list of values in the combo field.
As you can see Swedish(Sweden) has been pre defined as the locale to be used when formatting this number field. Say the report is being previewed, in which case the client locale becomes the runtime locale as well, however irrespective of what the client locale is, may it be English or any other locale this number will always be formatted based on the hardcode Swedish locale. In other words the the formatting properties (decimal, symbol, digit grouping symbol etc.) will have Swedish values.
Note: Formatting based on runtime locale is preferred over hardcoding the locale. The latter is not recommended.
Formatting numbers as currency¶
Sometimes you may have numbers in your report data which represents currency values. These can be specially formatted as currencies using the currency feature available from the Format Number dialog. The resulting number will have the correct number of decimal digits that a currency for a given locale (runtime or design time) should have. For majority of locales the "No. of digits after decimal" for a currency is two. However there are instances where this value is zero for example Japanese and sometimes three as for Libyan.
To enable currency formatting simply select the Currency checkbox as shown below.
The number of decimal digits for the currency field will be decided based on the supplied locale. For instance, if the locale supplied at runtime is English (United States) where the number of decimals for a currency field is two and the following numbers when formatted as currencies would be displayed as follows.
|Resulting Currency Format
How this works is, for English (United States) the two properties Maximum digits after decimal and Minimum digits after decimal will be set to two. Thereby each currency value will have two decimal places each.
Out of the formatting properties available for a currency only the "No. of digits after decimal" will be applied on the data. Values for other currency properties such as Decimal symbol, Digit grouping symbol are same as the corresponding properties of a number. For most locales, above properties Decimal symbol, Digit grouping symbol are equivalent for both numbers and currencies. However there are few uncommon locales that does have different properties for numbers and currencies. Kazakh is an example of one such locale where the decimal symbol is different for a number and currency. See below.
The currency in this case will be formatted using the decimal symbol of the number "," and not "-" .
Another scenario where you might become confused is, if the locale used (runtime or designtime) comprises only of the language and not the country then the default locale is used instead. The formatting will change to reflect the default locale.