Oracle® Fusion Applications Developer's Guide 11g Release 4 (11.1.4) Part Number E15524-09 |
|
|
PDF · Mobi · ePub |
This chapter describes the Oracle Fusion Applications standards and guidelines for working with localization formatting.
Section 21.9, "Implementing Localization Formatting in ADF Desktop Integration"
Section 21.10, "Implementing Localization Formatting in Oracle BI Publisher Reports"
Section 21.11, "Implementing Localization Formatting in ADF Data Visualization Components"
Section 21.12, "Configuring National Language Support Attributes"
Section 21.13, "Standards and Guidelines for Localization Formatting"
When developing applications for international users, it is often necessary to format the display of certain location-dependent data. In the context of Oracle JDeveloper and Oracle Application Development Framework, localization requires implementing formatting patterns so as to properly display the data according to local standards.
Currency, dates, numbers and time zones are localized using Oracle ADF Faces components that bind to the attribute to be localized. In some cases, Groovy or Expression Language methods are used to localize a particular UI component.
Currency values may be formatted differently, depending on the currency code associated with the value. Each currency code is associated with formatting such as precision and currency symbols.
You can format currency using the default formatting behavior, or by overriding the default formatting. Alternatively, you can format currency on the fly using partial page rendering.
Currency fields are represented by java.lang.BigDecimal
in entity objects and view objects.
A currency field should always be formatted according to the currency code chosen in the context UI of the transaction.
For example, if the user selects JPY as the currency code from the context UI, then the currency value should be formatted according to the Japanese Yen standard.
There are two implementations to format numerical values according to the corresponding currency code.
One is the Expression Language function fnd:currencyPattern(currencyCode)
that takes the currency code input in the context user interface as a parameter. If JPY is input to this Expression Language function, then the number would be formatted according to the Japanese Yen pattern: #,##0;-#,##0 without showing any decimal digits, whereas if the same Expression Language function is used for the US dollar input parameter, the number would be formatted according to the USD pattern: #,##0.00;-#,##0.00. For example, the numerical value 135.6789 that is fetched from the database needs to be shown as 135.68 USD, whereas the same number in JPY would be shown as 136 JPY.
The syntax is:
fnd:currencyPattern(bindingToAmountCurrencyCode)
The other implementation to format currency values is the fnd:currencyPatternWithPrecisionAndSymbol
Expression Language function, which is a more flexible function than fnd:currencyPattern. The fnd:currencyPatternWithPrecisionAndSymbol
function takes these input parameters:
currency code to be used for formatting
number of precision digits required in the formatted number
whether the currency code or symbol is to be shown in the formatted number
The syntax is:
fnd:currencyPatternWithPrecisionAndSymbol( bindingToAmountCurrencyCode, bindingToAttrNamePrecision, bindingToAttrNameCurrencySymbol)
For example, if JPY
is entered as the formatting currency code, and symbol
is used as the currency code/symbol parameter, and the number of precision digits is set to 1, then the number would be formatted as #,##0.0 ¥;-#,##0.0 ¥. The numerical value 135.6789 retrieved from the database needs to be shown as 135.68$ in USD, whereas the same number will need to be shown as 136¥ in JPY. (This example considers that the currencySymbol
parameter has been set to symbol). The currencySymbol
parameter can only take the values symbol
, code
, or none
.
Currency codes are stored in the FND_Currencies
table located in the Oracle Fusion Middleware Extensions for Applications schema. The currency code determines the format mask for the currency field, including:
Precision: Determines the use and number of decimal digits, comma placement, and so on.
Currency symbol: Displays the standard symbol for the currency.
The Expression Language function fnd:currencyPattern()
determines formatting for the currency field using the default precision associated with the currency code. No currency symbol or code is displayed in the user interface. The Expression Language function fnd:currencyPatternWithPrecisionAndSymbol()
determines formatting for the currency field using an extra parameter for precision. It also uses the currency code to show a currency symbol/code in the user interface. User preferences for grouping and decimal separators are used to format the value in both these functions.
To format currency, you must first set the view object custom attribute to type currency
and then select the currency code to be used in formatting the currency field. You can specify the currency code by entering its value explicitly, or by writing a Groovy expression in the transient attribute.
Before you begin:
Create an entity object and a view object.
To format currency values, use the fnd:currencyPattern()
function to obtain the format pattern of different currency codes. Therefore, a currency field, whether it is used in inputText
or outputText
, should be formatted with code similar to:
<af:convertNumber type="currency" currencyCode="#{bindingToAmountCurrencyCode}" pattern="#{fnd:currencyPattern(bindingToAmountCurrencyCode)}" />
Here, bindingToAmountCurrencyCode
should be replaced with the actual name of the field that allows users to select a currency code.
If <af:convertNumber type="currency" pattern="#{applCorePrefs.numberFormatPattern}"/>
is found, then the currency field will be formatted as a number. This is incorrect.
If the field requires displaying currency numbers combined with a currency code or currency symbol, the Expression Language function fnd:currencyPatternWithPrecisionAndSymbol()
should be used to get the format pattern.
In this sample code, the Amount field is formatted according to the currency code set in the af:convertNumber
tag.
<af:outputText value="#{node.Amount}" id="ot28"> <af:convertNumber type="currency" currencyCode="#{bindings.CurrencyCode.attributeValue}" pattern="#{fnd:currencyPattern(bindings.CurrencyCode.attributeValue)}"/> </af:outputText>
In this sample code, the grouping separator and decimal separator will be taken from the user's number preferences, and the number of precision digits will be set to 2. Also, the symbol shown will correspond to the currency code set in the af:convertNumber
tag.
<af:outputText value="#{node.Amount}" id="ot28"> <af:convertNumber type="currency" currencyCode="#{bindings.CurrencyCode.attributeValue}" pattern="#{fnd:currencyPatternWithPrecisionAndSymbol(bindings.CurrencyCode.attributeValue,2,'symbol'}"/> </af:outputText>
The fields Ordered, Total Tax, and Total in FIGURE1 show how currency values are formatted in Oracle Fusion Applications.
When dragging and dropping the view object onto a JSF page, Applications Core generates relevant bindings to the Oracle ADF Faces Number Converter attached to the user interface component.
This sample code shows bindings to the Number Converter.
<af:outputText label="Amount" value="#{bindingToOrderTotal}"> <af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}" /> <af:outputText>
As the developer, you should change the generated code according to either the fnd:currencyPattern()
Expression Language function or the fnd:currencyPatternWithPrecisionAndSymbol()
Expression Language function as shown in this sample code.
<af:outputText label="Amount" value="#{bindingToOrderTotal}"> <af:convertNumber type="currency" currencyCode="#{bindingToAmountCurrencyCode}" pattern="#{fnd:currencyPattern(bindingToAmountCurrencyCode)}" /> <af:outputText>
The bindings indicate that the Expression Language method fnd:currencyPattern()
is to be used to return the currency code for the value of the attribute.
At runtime, Applications Core Technology evaluates the bindings generated during design time to generate the correct currency format mask for the value. The fnd:currencyPattern()
and fnd:currencyPatternWithPrecisionAndSymbol()
Expression Language methods return the format mask for a given currency code, accounting for currency precision, currency symbol, and so on.
All numerical values need to be formatted correctly when they are presented to a user in Oracle Fusion Applications. Users expect that they can enter numerical values based on their formatting preferences, which include such things as options to change the grouping and the decimal separators. Number formatting preferences also let users choose the number format mask that will be used to display the number. For instance, a user might choose that the grouping separator has to be shown once every three digits with a maximum of three decimal digits (#,##0.###). An example is a value of 1234.5 in the database that might have to be displayed as 1 234,500 or 1,234.500 or 1.234,500.
Before you begin:
Create an entity object and a view object with number fields, including any of these attribute types:
java.math.BigDecimal
, java.lang.Integer
, or java.lang.Long
.
The number one thousand two hundred and thirty four point five six can display in any of the following formats:
1,234.56
1'234.56
1'234,56
1.234,56
1234.56 (ISO standard)
1234,56
1 234.56
1 234,56
View objects and entity objects can be formatted so as to display date and number data in accordance with local standards. The ISO standard is typically used when it is not desirable to use local standards.
Decimal output fields should be formatted according to the user's number formatting preferences. Use the <af:convertNumber pattern...
entry to retrieve the number formatting pattern from the applCorePrefs
bean.
<af:outputText value="#{bindings.FromValue.inputValue}" id="ot19"> <af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}"/> </af:outputText>
Input decimal fields should be formatted according to the user's number preferences. In this sample code, use the <af:convertNumber pattern...
entry to retrieve the number formatting pattern from the applCorePrefs
bean.
<af:inputText value="#{row.bindings.FromValue.inputValue}" label="#{bindings.PerformanceThreshold21.hints.FromValue.label}" required="#{bindings.PerformanceThreshold21.hints.FromValue.mandatory}" columns="#{bindings.PerformanceThreshold21.hints.FromValue.displayWidth}" maximumLength="#{bindings.PerformanceThreshold21.hints.FromValue.precision}" shortDesc="#{bindings.PerformanceThreshold21.hints.FromValue.tooltip}" id="inputText9" autoSubmit="true"> <af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}"/> </af:inputText>
The Threshold Start field in Figure 21-2 is an example of a number field that is formatted according to the user's number formatting preferences.
When a decimal number is to be shown as a part of a larger string object on the user interface, the fnd:formatNumber
and fnd:formatNumber2
Expression Language functions provided in the applCore library should be used to format such numbers. When either of these functions is used, the user's number formatting preferences are implemented according to applCorePrefs.numberFormatPattern
.
The syntaxes of the two Expression Language functions are:
fnd:formatNumber(java.lang.Number decimalValueToBeFormatted)
fnd:formatNumber2(java.lang.Number decimalValueToBeFormatted, int maximumNumberOfFractionDigits)
This sample code shows how to use these two functions for decimal number formatting.
<af:image id="img65"
source="/images/upgreenplus_status.png"
shortDesc="#{af:formatNamed(prcponnegotiationsuiBundle3['AltTxt.IncreasedbyVALUE.FavorablyIncreasedbyVALUE'], VALUE', fnd:formatNumber(bindings.ActiveResponsesChangeAmt.inputValue))}" visible="#{bindings.ActiveResponsesChange.inputValue == 'INCREASE'}"/>
As shown in the example, the variable ActiveResponsesChangeAmt
will be formatted according to the user's number preferences according to applCorePrefs.numberFormatPattern
. This formatted number is then concatenated to the externalized string FavorablyIncreasedbyVALUE
and displayed to the user.
The fnd:formatNumber2
function has the advantage of explicitly specifying the maximum number of fraction digits in the formatted number, as shown in this sample:
<af:showDetailItem text="#{PjbWorkareaGenBundle['Header.SubmittedValues']} (#{fnd:formatNumber2(pageFlowScope.InvoiceWorkareaBean.invoiceValueRowNum[1],2)})" id="tabSubmitted" disclosureListener="#{InvoiceListBean.changeStatusTab}" partialTriggers="AT1:_ATp:menuSubmit AT1:_ATp:btnSubmit AT2:_ATp:menuApprove AT2:_ATp:menuReject AT2:_ATp:menuRelease AT2:_ATp:menuReturntoDraft cl1" stretchChildren="first" disclosedTransient="true" disclosed="#{pageFlowScope.pageFocus == '2'}">
Here, the text attribute of the af:showDetailItem
tag includes a number that must be formatted before being displayed. Therefore, the fnd:formatNumber2
Expression Language function has been used to format the number to be added to the SubmittedValues
string. Here, the second parameter has been set to 2 and indicates that a maximum of two fractional digits can be shown in the decimal number. So, for example, after formatting, the number 1234.56789 that is retrieved from the database will be displayed as SubmittedValues: 1,234.57.
Integer output fields should be formatted according to the user's number formatting preferences without any decimal precision digits. For instance, the number 12345.00 stored in the database might have to be shown as 12,345 or 12.345 or 12 345 for a certain user. Notice that there is no decimal separator or any precision digits shown in these numbers. As shown in this sample, use the <af:convertNumber pattern...
entry to retrieve the number formatting pattern from the applCorePrefs
bean.
<af:outputText value="#{bindings.integerQuantity.inputValue}" id="ot19"> <af:convertNumber pattern="#{applCorePrefs.integerFormatPattern}"/> </af:outputText>
Input integer fields should be formatted according to the user's number preferences without showing any decimal precision digits. As shown in this sample, use the <af:convertNumber pattern...
entry to retrieve the number formatting pattern from the applCorePrefs
bean.
<af:inputText value="#{bindings.Point1.inputValue}" label="#{bindings.Point1.hints.label}" required="#{bindings.Point1.hints.mandatory}" columns="#{bindings.Point1.hints.displayWidth}" maximumLength="#{bindings.Point1.hints.precision}" shortDesc="#{bindings.Point1.hints.tooltip}" inlineStyle="width:100%; border-color:InactiveBorder; border-width:thin;" id="inputText5"> <f:validator binding="#{bindings.Point1.validator}"/> <af:validateLongRange minimum="0"/> <af:convertNumber pattern="#{applCorePrefs.integerFormatPattern}"/> </af:inputText>
In Figure 21-3, Point 1 is an example of an input integer field that is formatted according to the user's number preferences without showing the decimal separator or any precision digits.
When an integer number is to be shown as a part of a larger string object on the user interface, the fnd:formatNumber2
function provided in the applCore library should be used to format such numbers. When this function is used with the maximum number of precision digits set to 0, the user's number formatting preferences are used from applCorePrefs.numberFormatPattern
with no precision digits.
The syntax of the fnd:formatNumber2
function is:
fnd:formatNumber2(java.lang.Number integerValueToBeFormatted, int maximumNumberOfFractionDigits)
The fnd:formatNumber2
function can be used to format integer numbers by explicitly specifying the maximum number of fraction digits as 0 in the formatted number. This sample code shows how to use the fnd:formatNumber2
function for integer number formatting.
<af:showDetailItem text="#{PjbWorkareaGenBundle['Header.SubmittedInvoices']} (#{fnd:formatNumber2(pageFlowScope.InvoiceWorkareaBean.invoiceValueRowNum[1],0)})" id="tabSubmitted" disclosureListener="#{InvoiceListBean.changeStatusTab}" partialTriggers="AT1:_ATp:menuSubmit AT1:_ATp:btnSubmit AT2:_ATp:menuApprove AT2:_ATp:menuReject AT2:_ATp:menuRelease AT2:_ATp:menuReturntoDraft cl1" stretchChildren="first" disclosedTransient="true" disclosed="#{pageFlowScope.pageFocus == '2'}">
Here, the text attribute of the af:showDetailItem
tag includes a number that must be formatted before being displayed. The fnd:formatNumber2
function is used to format the integer to be added to the SubmittedInvoices
string. The second parameter has been set to 0 and indicates that no fractional digits can be shown in the formatted number. For example, after formatting, the number 1234 that is retrieved from the database will be displayed as SubmittedInvoices: 1,234.
An ID field is a number field that uniquely identifies an object. Typical examples of ID fields include TransactionID, Sequence Number, and Item Number. Such ID output fields should be formatted without using the user's number formatting preferences. That is, ID output fields should not display decimal precision digits or grouping separators. For example, a student's admission number should be displayed as 14567 instead of 14,567.00. The <af:convertNumber pattern...
entry in this sample code retrieves the number formatting pattern from the applCorePrefs
bean.
<af:column headerText="#{bindings.Deliveries.hints.SalesOrderLine.label} id="c9" > <af:outputText value="#{row.bindings.SalesOrderLine.inputValue}" label="#{bindings.Deliveries.hints.SalesOrderLine.label}" id="outputText3"> <af:convertNumber pattern="#{applCorePrefs.numericCodeFormatPattern}"/> </af:outputText> </af:column>
Note:
ID fields always should be aligned to the left. As a developer, you must not hardcode the align attribute of the column attribute of an af:table
, or the contentStyle
attribute of the af:outputText
tag displaying an ID field. By default, Oracle ADF supports start alignment that is appropriate for ID fields.
The field Sales Order Line in Figure 21-4 corresponds to the output ID field shown in the above sample code.
Input integer fields should be formatted according to the user's number preferences without showing any decimal precision digits or grouping separators. The <af:convertNumber pattern
entry in this example indicates that the number formatting pattern is being retrieved from the applCorePrefs
bean.
<af:inputText value="#{bindings.SequenceNumber.inputValue}" label="#{bindings.SequenceNumber.hints.label}" required="#{bindings.SequenceNumber.hints.mandatory}" columns="#{bindings.SequenceNumber.hints.displayWidth}" id="inputText1" partialTriggers="asgStat" helpTopicId="InvCoreSetup_755E15370133C364E040D30A688161D5V000" contentStyle="text-align:start" autoSubmit="true"> <f:validator binding="#{bindings.SequenceNumber.validator}"/> <af:convertNumber pattern="#{applCorePrefs.numericCodeFormatPattern}"/> </af:inputText>
The field Sequence in Figure 21-5 corresponds to the input ID field shown in the above sample code.
The fnd:formatNumber()
and fnd:formatNumber2()
functions must not be used for ID fields appearing in strings, because they introduce a grouping separator in number fields, which should not be displayed in ID fields. In such cases, output ID fields should be treated as normal text fields.
In Oracle Fusion Applications, hyperlinks are represented by af:commandLink
and af:goLink
. All numbers found in the labels of hyperlinks in the user interface must be formatted according to the user's number preferences. The number might either have to be formatted according to numberFormatPattern if the number value is decimal in nature, integerFormatPattern if the number value is integer only, and need not be formatted at all if the value corresponds to an ID value. Code to format numbers in hyperlinks is shown in Example 21-1.
Example 21-1 Formatting Numbers in Hyperlinks
<af:commandLink id="outputText6" text="" partialSubmit="true" immediate="true" action="#{LocalAreaHandlerBean.showInventory}"> <af:outputText value="#{row.InvPendingCount}" id="ot1"> <af:convertNumber type="number" pattern="#{applCorePrefs.integerFormatPattern}"/> </af:outputText> </af:commandLink>
Because af:convertNumber
is not a valid child tag of af:commandLink
, the best way to format a number on a link is by making the text attribute of the af:commandLink
tag empty and then adding an af:outputText
tag as a child tag that displays the formatted numerical value. In this case, the number is an integer (java.lang.Integer), so the pattern applCorePrefs.integerFormatPattern
has been used. In cases of decimal numbers (java.math.bigDecimal), applCorePrefs.numberFormatPattern
has to be used, while in cases of ID fields (java.lang.Long), af:convertNumber
can be removed and the field can be honored as plain text. The parent hyperlink tag can be either af:commandLink
or af:goLink
.
Similarly, numbers that are found on links represented by the af:goLink
tag in Oracle Application Development Framework (Oracle ADF) should be formatted according to the user's number formatting preferences using the Preferences bean. The procedure to be followed is very similar to that of the af:commandLink
tag. Sample code for number formatting in af:golink
is shown in Example 21-2.
Example 21-2 Formatting a Number in af:goLink
<af:goLink text="" id="gl1" destination="#{row.children[0].FileUrl}"> <af:outputText id="id1" value="#{bindings.fromValue.inputValue}"> <af:convertNumber type="number" pattern="#{applCorePrefs.numberFormatPattern}"/> </af:outputText> </af:goLink>
Again, af:goLink
cannot have an af:convertNumber
as its child tag, so the text attribute of the goLink
tag should be made empty and af:outputText
should be added as a child tag of af:goLink
. The af:convertNumber
then can be added as a subtag of the outputText tag. The pattern attribute can be changed for this af:convertNumber
tag, according to whether the number is decimal or an integer. If the number represents an ID field, no number formatting is needed.
Another way of formatting the text in af:commandLink
and af:goLink
is by using the Expression Language functions fnd:formatNumber
and fnd:formatNumber2
in their text attributes. Sample code to format a number in an commandLink using the fnd:formatNumber2
Expression Language function is shown in Example 21-3.
Example 21-3 Formatting a Number in a commandLink
<af:commandLink id="outputText6" text="#{fnd:formatNumber2(row.InvPendingCount,0)}" partialSubmit="true" immediate="true" action="#{LocalAreaHandlerBean.showInventory}"> </af:commandLink>
Here, the second parameter has been set to 0 so that no precision digits are shown. This is the same as using pattern="#{applCorePrefs.integerFormatPattern}"
as used in Example 21-1. The only added feature in this example is that there is no need to add a child af:outputText
tag for number formatting.
Similarly, af:goLink
can also be formatted using the fnd:formatNumber
and fnd:formatNumber2
Expression Language functions. An example of formatting the af:goLink
shown in Example 21-2 using the fnd:formatNumber
function is shown in Example 21-4:
Example 21-4 Formatting af:goLink Using fnd:formatNumber
<af:goLink text="#{fnd:formatNumber(bindings.fromValue.inputValue)}" id="gl1" destination="#{row.children[0].FileUrl}"/>
Here, the fnd:formatNumber
Expression Language function has been used to format the value in the af:goLink
. This is the same as using pattern="#{applCorePrefs.numberFormatPattern}"
as shown in Example 21-2.
A percentage value maps to java.math.BigDecimal in entity object and view object files and NUMBER(n, m) (where m!=0) in underlying database columns.
Such percentage values in output fields must be displayed in a locale-sensitive format. For example, 75.68% in en_US (Language: English Territory: United States) should be displayed as 75,68 % (there is a space between the number and the percentage sign) in the fr_FR (Language: French Territory: France) locale.
The number and percentage sign of a percentage value should always be displayed in a user preferred format in Oracle Fusion applications. Sample code that can display percentage values is shown in Example 21-5.
Example 21-5 Displaying Percentage Values
<af:outputText value="#{row.PercentComplete != null ? (row.PercentComplete * 0.01): row.PercentComplete}" id="outputText5"> <af:convertNumber minFractionDigits="2" maxFractionDigits="2" type="percent"/> <af:showPopupBehavior triggerType="click" popupId=":::progressTrendPopup" alignId="rowHeadCol"/> </af:outputText>
Here, maxFractionDigits can be determined by the underlying database column type using this formula:
maxFractionDigits = The scale of database Column Data Type - 2
For example, if the database column data type is NUMBER(8,4), maxFractionDigits can be "2". If "The scale of database Column Data Type - 2" <=0, attribute maxFractionDigits should not be added to the convertNumber tag.
This formula arises from the fact that a percentage value like 1% usually is stored in the database column as 0.01. Hence, the maximum number of fraction digits in the percentage value to be displayed on the user interface will always be 2 less than the scale of the database column.
In Oracle Fusion applications, you must not hardcode the % sign in the value attribute of the outputText tag, because this makes the percentage values locale-insensitive.
The Percent of Project Work Complete field in Figure 21-6 corresponds to the output percentage field shown in Example 21-5.
A percentage value in an input field generally is formatted exactly like the output percentage field. Sample code to format input percentage fields is shown in Example 21-6.
Example 21-6 Formatting Input Percentage Fields
<af:inputText value="#{bindings.PercentQuantity.inputValue}" label="#{bindings.PercentQuantity.hints.label}" autoSubmit="true" id="inputText10" <f:validator binding="#{bindings.PercentQuantity.validator}"/> <af:convertNumber type="percent" minFractionDigits="2" maxFractionDigits="2"/> </af:inputText>
All number formatting patterns default to the formats described in Section 21.3.1, "How to Format Numbers."
When dragging and dropping a view object containing an attribute of type java.math.BigDecimal
or java.lang.Integer
, or java.lang.Long
, Applications Core generates code that binds to the numberFormatPattern
property in the applCorePrefs
managed bean as shown in Example 21-7.
All date values must be formatted correctly when they are presented to a user. Users expect to input values according to their date formatting preferences. For instance, a value of 13 August, 2011 in the database might have to be displayed as 08/13/2011 or 2011.8.13. A similar example of a date-time value is a value of 26 July 2011, 2:00:00 PM might have to be displayed as 14:00 07/26/2011 or 2011.7.26 02:00:00 PM.
Before you begin:
Create an entity object and a view object with date fields, including either of these attribute types: java.sql.Date
or java.sql.Timestamp
.
Dates without time values (called dates) are mapped to java.sql.Date
in the entity object/view object layer. These fields should be formatted according to the user's date formatting preferences.
The <af:convertDateTime pattern...
entry in the sample code retrieves the date formatting pattern from the applCorePrefs
bean.
<af:column sortProperty="OrderDate" filterable="true" sortable="true"headerText="#{bindings.NlsOrders1.hints.OrderDate.label}" id="c1"> <f:facet name="filter"> <af:inputDate value="#{vs.filterCriteria.OrderDate}" id="id8" > <af:convertDateTime pattern="#{applCorePrefs.dateFormatPattern}"/> </af:inputDate> </f:facet> <af:inputDate value="#{row.bindings.OrderDate.inputValue}" label="#{bindings.NlsOrders1.hints.OrderDate.label}" required="#{bindings.NlsOrders1.hints.OrderDate.mandatory}" shortDesc="#{bindings.NlsOrders1.hints.OrderDate.tooltip}" id="id1"> <f:validator binding="#{row.bindings.OrderDate.validator}"/> <af:convertDateTime pattern="#{applCorePrefs.dateFormatPattern}"/> </af:inputDate> </af:column>
Both the filter for the date and the date field should be formatted according to the user's date formatting preferences. If this is not done, the dates will not be displayed according to the user's preferences.
The values for the Due Date field in Figure 21-7 are examples of how a date value is formatted according to the user's preferences in Oracle Fusion Applications.
Applications often show the current date on the user interface. They are mapped to the java.sql.Date
data type in the entity object/view object layer. Correctly identifying the date requires the use of particular APIs.
A server date is calculated by truncating the time portion of the current time from the system clock. However, it may not be appropriate to display the server date to end users if they are not located in the server time zone. For example, when creating an order, the order form may display with the order date filled out for the end user with the current date. In this case, the order date must be the end user's local date rather than the server date. A server in the US may be serving an end user in China, whose local date may be one day ahead due to time zone differences. It is necessary to adjust the server date to the end user's local date.
This sample shows how to adjust the server date to the local date in the Java bean.
public Date getCurrentLocalDate() {
// Get the current date and time. long date = new java.util.Date().getTime(); // Get the user preferred time zone from the ApplCore PreferencesBean. TimeZone uptz = TimeZone.getTimeZone(pb.getUPTZ()); // Get the server time zone. TimeZone crtz = TimeZone.getDefault(); // Calculate the time zone offset difference and return an adjusted date. int uptzoff = uptz.getOffset(date); int crtzoff = crtz.getOffset(date); int diff = uptzoff - crtzoff;
return new Date(date+diff);
}
This sample shows how to display the current date in the JSF page.
<af:inputDate binding="#{localDateBean.currentLocalDate}" value="#{bindings.StartDate.inputValue}" label="#{bindings.StartDate.hints.label}(Type: java.sql.Date)" required="#{bindings.StartDate.hints.mandatory}" shortDesc="#{bindings.StartDate.hints.tooltip}" id="id1"> <af:convertDateTime pattern="#{applCorePrefs.dateFormatPattern}"/> </af:inputDate>
This workaround can be used only if there is no middleware tier validation for the date field. For example, if the middleware tier validation has a condition that the date field's value cannot be more than the middleware tier's system time, the conversion with the above method will generate a validation error. In such cases, you would need the ATG enhancement to convert the server time zone date to the user's preferred time zone.
The Required Date field in Figure 21-8 should default to the user's preferred time-zone rather than the server time-zone.
Dates with time values (called datetimes) are mapped to java.sql.Timestamp in the entity object/view object layer. Format these fields according to the user's date and time formatting preferences.
All datetime fields must have at least one of these three patterns in the af:convertDateTime
tag to be formatted according to the user's date and time preferences.
Pattern 1
pattern="#{applCorePrefs.UPTZPattern}"
applCorePrefs.UPTZPattern
returns a pattern by combining the selection of the Date Format and the Time Format in User Preferences. For example, if a user selects M.d.yyyy (4.28.2010) from the Date Format list, and HH.mm (00.55) from the Time Format list, applCorePrefs.UPTZPattern
returns a pattern M.dd.yyyy HH:mm. Therefore, applCorePrefs.UPTZPattern
may return a pattern with or without Seconds, depending on the selection in User Preferences.
Pattern 2
This pattern is applicable if it always needs to display the Seconds part of a datetime value.
pattern="#{applCorePrefs.DateFormatPattern} #{applCorePrefs.timeFormatPatternWithSeconds}"
Note that there is a single space between the two Expression Language expressions.
Pattern 3
pattern="#{applCorePrefs.DateFormatPattern} #{applCorePrefs.timeFormatPatternWithoutSeconds}"
Note that there is a single space between the two Expression Language expressions.
This pattern is applicable if it does not need to display the Seconds part of a date-time value.
Both the filter for the date-time and the date-time field should be formatted according to the user's date and time formatting preferences, as shown in this sample code. If this is not done, these fields will not be processed according to the user's preferences.
<af:column sortProperty="LastUpdateDate" filterable="true" sortable="true" headerText="#{bindings.NlsOrders1.hints.LastUpdateDate.label}" id="c1"> <f:facet name="filter"> <af:inputDate value="#{vs.filterCriteria.LastUpdateDate}" id="id8" > <af:convertDateTime pattern="#{applCorePrefs.UPTZPattern}"/> </af:inputDate> </f:facet> <af:inputDate value="#{row.bindings.LastUpdateDate.inputValue}" label="#{bindings.NlsOrders1.hints.LastUpdateDate.label}" required="#{bindings.NlsOrders1.hints.LastUpdateDate.mandatory}" shortDesc="#{bindings.NlsOrders1.hints.LastUpdateDate.tooltip}" id="id1"> <f:validator binding="#{row.bindings.LastUpdateDate.validator}"/> <af:convertDateTime pattern="#{applCorePrefs.UPTZPattern}"/> </af:inputDate> </af:column>
The Last Saved field at the top right of Figure 21-9 is an example of how a date-time is formatted according to the user's preferences in Oracle Fusion Applications.
When dragging and dropping a view object containing an attribute of type java.sql.Date
or java.sql.Timestamp
, Applications Core generates code that binds to the dateFormatPattern
(date fields) or UPTZPattern
(timestamp fields) property in the applCorePrefs
managed bean.
This sample shows bindings to the dateFormatPattern
property. The pattern according to which the date value is formatted is picked up from the Preferences bean in applCore, which in turn accesses these values from the LDAP server configured with users' roles and policies.
<af:panelLabelAndMessage label="#{bindings.OrderDate.hints.label}" id="plam1"> <af:outputText value="#{bindings.OrderDate.inputValue}" id="ot1"> <af:convertDateTime pattern="#{applCorePrefs.dateFormatPattern}"/> </af:outputText> </af:panelLabelAndMessage>
This type of code is generated for both date and timestamp fields. For date fields, you should add the type="date"
attribute, whereas for timestamp fields, you should add the type="both"
attribute, and make the pattern attribute equal to one of the three patterns discussed above.
At runtime, the bindings generated at design time are executed. Dates and Timestamps are displayed according to user preferences for date and time formatting patterns (for example, 01/01/10 and 01/01/10 01:05:00).
The following standards and guidelines apply to formatting dates and timestamps.
All date-only fields must be represented only by java.sql.Date
data types.
When a value bound to a field is date-only of type java.sql.Date
, do not set the time zone to af:convertDateTime
.
Date values with time (called datetime values) are mapped to java.sql.TimeStamp
in the entity object and view object layer. In Oracle Fusion Applications, datetime values can be calculated according to one of these time zones:
Server Reporting Time Zone
This is the default and simply is the time zone of the server's operating system.
User Preferred Time Zone (UPTZ)
When UPTZ is used, the date-time changes in the UI when a user changes the Time Zone preference in User Preferences. For example, if a user switches the Time Zone preference from UTC-08:00 to UTC-11:00, the date-time 04/27/2010 01:00:00 will change to 04/26/2010 23:00:00. The value in the database is not changed, and the conversion occurs after the value is retrieved from the database and before it is shown on the user interface.
Legal Entity Time Zone (LETZ)
LETZ is defined with legal entities. It is an attribute of a legal entity business object. For example, when creating a legal entity ORACLE-CDC, it can have a time zone attribute (LETZ) which value is UTC+08:00. Thus a date-time 04/27/2010 01:00:00 in UTC will change to 04/27/2010 09:00:00 accordingly. The value in the database is not changed, and the conversion occurs after the value is retrieved from the database and before it is shown on the user interface.
The business logic of the application decides which time zone to use to calculate the date-time value.
The different types of tags required to implement either the User Preferred Time Zone or Legal Entity Time Zone are shown in this section.
Before you begin:
Create an entity object and a view object with date fields, and include the java.sql.Timestamp
attribute type. Note that the middle-tier time zone and the database time zone always must match. If they do not match, the conversions will be invalid.
Using the Server Reporting Time Zone
Use this code sample if the date-time value is to be calculated according to the Server Reporting Time Zone:
<af:outputText value="#{bindings.StartDate.inputValue}" ... > <af:convertDateTime type="both" pattern="#{applCorePrefs.UPTZPattern}" /> </af:outputText>
This is to say that nothing needs to be explicitly added into the automatically generated af:convertDateTime
tag.
Using the User Preferred Time Zone
Use this code sample to calculate the date-time value according to the User Preferred Time Zone:
<af:outputText value="#{bindings.StartDate.inputValue}" ... > <af:convertDateTime type="both" pattern="#{applCorePrefs.UPTZPattern}" timeZone="#{applCorePrefs.UPTZ}" /> </af:outputText>
Converting a Timestamp to the Legal Entity Time Zone
Follow this method to convert a timestamp value to the Legal Entity Time Zone:
Retrieve the Legal Entity time zone. Each legal entity has a LETZ. Determining a LETZ starts with a legal entity's address that is used to look up a specific location and a unique time zone attribute. This time zone is the LETZ for the legal entity.
Related tables in the database are:
FND_TIMEZONES_B
and FND_TIMEZONES_TL
, tables to record time zone related information.
XLE_REGISTRATIONS
, a table of Legal Entity data.
HZ_LOCATIONS
, table to store geographical locations.
Use this PL/SQL API to obtain the Legal Entity Time Zone code. This API is found in the package XLE_LE_TIMEZONE_GRP and is to be called in the following way:
Get_Le_Tz_Code(?,?)
The ? indicates an input parameter.
This is sample code for using the Get_Le_Tz_Code(?,?) API:
l_timezone_code = XLE_LE_TIMEZONE_GRP.Get_Le_Tz_Code('BUSINESS_UNIT_ID', p_ou_id); l_timezone_code = XLE_LE_TIMEZONE_GRP.Get_Le_Tz_Code ('INVENTORY_ORG_ID', p_inv_org_id); l_timezone_code = XLE_LE_TIMEZONE_GRP.Get_Le_Tz_Code ('LEGAL_ENTITY_ID', p_le_id);
To retrieve the current date and time in the Legal Entity Time Zone, use this PL/SQL API to calculate the current date and time in the Legal Entity Time Zone. This is particularly useful while creating or saving a transaction, when the legal entity date and time is to be displayed. This API is found in the XLE_LE_TIMEZONE_GRP package and is to be called in the following way:
Get_Le_Sysdate_Time(?,?)
The ? indicates an input parameter.
This is sample code using this API to determine the current date and time in the LETZ:
l_sysdate = XLE_LE_TIMEZONE_GRP .Get_Le_SysDate_Time('BUSINESS_UNIT_ID', p_ou_id); l_sysdate = XLE_LE_TIMEZONE_GRP .Get_Le_SysDate_Time ('INVENTORY_ORG_ID', p_inv_org_id); l_sysdate = XLE_LE_TIMEZONE_GRP .Get_Le_SysDate_Time ('LEGAL_ENTITY_ID', p_le_id);
This function will invoke the API (Get_DefaultLegalEntity)
when the input parameter passed is the Business Unit or the Inventory Organization.
To convert the server date and time into the LETZ, use this PL/SQL API. This is useful while retrieving an already saved transaction and showing the already saved timestamp in the LETZ. This API is found in the XLE_LE_TIMEZONE_GRP
package and is to be called in the following way:
Get_Le_Day_Time(?,?,?)
The ? indicates an input parameter.
Sample code using this API to convert a given date and time from the server time zone to the LETZ:
l_le_day_time = XLE_LE_TIMEZONE_GRP . Get_Le_Day_Time ('BUSINESS_UNIT_ID', p_ou_id, p_trxn_date); l_le_day_time = XLE_LE_TIMEZONE_GRP . Get_Le_Day_Time ('INVENTORY_ORG_ID', p_inv_org_id. p_trxn_date); l_le_day_time = XLE_LE_TIMEZONE_GRP . Get_Le_Day_Time ('LEGAL_ENTITY_ID', p_le_id, p_trxn_date);
Here the p_trxn_date
is the transaction date and time value in the server time zone.
To convert the legal entity date and time into the server time zone, use this PL/SQL API. This API is found in the XLE_LE_TIMEZONE_GRP
package and is to be called in the following way:
Get_Server_Day_Time(?,?,?)
The ? indicates an input parameter.
This API will be for reverse LETZ conversion. Calling applications can pass in the Legal Entity Date Time and the Business Unit/Inventory Organization/Legal Entity ID to convert the Legal Entity datetime to the Server datetime.
Sample code using this API to convert the LETZ timestamp value to server time zone:
l_Server_Date := XLE_LE_TIMEZONE_GRP .Get_Server_Day_Time ('INVENTORY_ORG_ID', p_inv_org_id, p_Le_Date);
l_Server_Date := XLE_LE_TIMEZONE_GRP .Get_Server_Day_Time ('BUSINESS_UNIT_ID', p_ou_id, p_Le_Date);
l_Server_Date := XLE_LE_TIMEZONE_GRP. Get_Server_Day_Time ('LEGAL_ENTITY_ID', p_inv_org_id, p_Le_Date);
These PL/SQL APIs must be called in the Java entity object implementation classes for time zone conversion. The JSF code corresponding to the date field need not be changed.
Here is a sample of a JSF date field in the server time zone and its corresponding conversion into the LETZ. The code in the JSF page corresponding to a date field is shown in Example 21-8:
Example 21-8 Converting a Date Field into the LETZ
<af:inputDate value="#{bindings.InvoiceDate.inputValue}" label="#{bindings.InvoiceDate.hints.label}" required="#{bindings.InvoiceDate.hints.mandatory}" shortDesc="#{bindings.InvoiceDate.hints.tooltip}" showRequired="true" autoSubmit="true" valueChangeListener="#{pageFlowScope.invoiceActionsBean.invoiceDateValueChangeListener}" columns="#{bindings.InvoiceDate.hints.displayWidth}" disabled="#{pageFlowScope.matchPopupVisible}" id="id2"> <f:validator binding="#{bindings.InvoiceDate.validator}"/> <af:convertDateTime pattern="#{applCorePrefs.dateFormatPattern}"/> </af:inputDate>
As shown, you do not need to change the date field's snippet in the JSF page, or add a time zone attribute in the af:convertDateTime
tag for this field.
The calculation of LETZ date values should be triggered when changing the value for the Business Unit field in the user interface. The value change should invoke a method that can calculate values according to the LETZ in the EOImpl
class. In this case, this method is the setOrgID()
method, shown in Example 21-9.
Example 21-9 Using the setOrgID() Method
public void setOrgID(Long orgID) { ... //To convert the current timestamp to the LETZ, we call another method getLEDateTime this.setInvoiceDate(this.getLEDateTime(orgID, this.getDBTransaction())); } //This method calls the PL/SQL API to get the current date and time in the LETZ public Date getLEDateTime(Long orgId, DBTransaction dbTransaction) { // 1. Define the PL/SQL block for the statement to invoke String stmt = "begin ? := XLE_LE_TIMEZONE_GRP.Get_Le_Sysdate_Time(?,?); end;"; // 2. Create the CallableStatement for the PL/SQL block st = (OracleCallableStatement)dbTransaction.createCallableStatement(stmt, 0); // 3. Register the positions and types of the OUT parameters st.registerOutParameter(1, Types.DATE); // 4. Set the bind values of the IN parameters st.setObject(2,"BUSINESS_UNIT_ID"); st.setObject(3,orgId); //5. Execute Query st.executeUpdate(); return st.getDate(1); }
In Figure 21-10, the field Receipt Date is an example of how a date-time or a timestamp field in Oracle Fusion Applications is calculated according to the user's preferred time zone rather than the server time zone.
In Figure 21-11, the Business Unit field determines the LETZ according to which the date fields Date and Terms Date on the right of the screenshot are converted in Oracle Fusion Applications. Thus, the fields Date and Terms Date change according to the Business Unit field in the Create Invoice transaction.
Some date-time values are not associated with a specific time zone. For example, an application may execute a job at 9 AM local time in every location across different time zones. Such values are called invariant or floating times. To print an invariant time zone value, use the default time zone such that no specific time zone is applied to the value.
When printing a date-time value for a specific time zone derived from an invariant time zone value, you may need to adjust the formatting so as to neutralize the effect of time zone conversion. This is because the server default time zone is applied implicitly.
When you drag and drop a timestamp field onto the JSF page, Applications Core generates these tags:
<af:outputText label="orderDateTime" value="#{bindingToOrderDateTime}"><af:convertDateTime pattern="#{applCorePrefs.dateFormatPattern}"/> <af:outputText>
You need to change the tags depending on whether the field is to be calculated according to the UPTZ or the server time zone (invariant timestamp values), for example Default : Server Time Zone.
This should be used only for invariant timestamp values. Invariant timestamp values are timestamps in which varying Timezone will not make a difference to the business logic of the application.
<af:outputText label="orderDateTime" value="#{bindingToOrderDateTime}"><af:convertDateTime pattern="#{applCorePrefs.UPTZPattern}"/> <af:outputText>
This is an example of a User Preferred Time Zone.
<af:outputText label="orderDateTime" value="#{bindingToOrderDateTime}"><af:convertDateTime timeZone="#{applCorePrefs.UPTZ}" pattern="#{applCorePrefs.UPTZPattern}"/><af:outputText>
At design time, Applications Core uses the Date-Time Sensitive custom property to generate bindings to the time zone attribute on the Oracle ADF Faces Date Time Converter. The attribute is bound to the applCorePrefs
managed bean.
At runtime, the Applications Core managed bean applCorePrefs
, implemented by oracle.apps.fnd.applecore.common.PreferencesBean
and registered with the faces-config.xml
file, retrieves the relevant formatting masks from Applications Session.
By default, date-time data may display as shown in Example 21-10.
The following standards and guidelines apply to formatting time zones:
All date time fields must be represented only by java.sql.Timestamp
data types (used by default in time zone view object attributes).
The database and middle-tier Timezone must always be the same in Oracle Fusion Applications.
Expression Language functions provide an alternative to the formatting procedures described in Section 21.2, "Formatting Currency,", Section 21.3, "Formatting Numbers" and Section 21.5, "Formatting Time Zones."
Oracle ADF Faces Expression Language functions of the type af:formatNamed
and af:format
only support String
objects as parameters. Consequently, other object types such as Date
and BigDecimal
must be converted to the String
object type.
For example, when binding the date object dateValue
as shown in Example 21-11, the dateValue
object must be converted to a String
object by calling the toString()
method.
However, the toString()
method does not support Oracle Fusion Applications user preferences. Oracle Fusion Applications thus require the use of Expression Language format functions to convert the following data objects to String objects:
Number and currency objects:
java.math.BigDecimal
java.lang.Integer
java.lang.Long
Date and DateTime (Timestamp) objects:
java.sql.Date
java.sql.Timestamp
You can format numbers, currency and dates using Expression Language functions.
Use the following Expression Language functions to format numbers.
The number Expression Language formatting function is shown in Example 21-12.
Example 21-12 formatNumber(java.lang.Number value) Function
fnd:formatNumber(java.lang.Number value)
Returns the formatted number value using the user preferences for the number format mask, grouping separator and decimal separator.
This function produces the tag shown in Example 21-13.
Example 21-13 Tag Produced by the Function fnd:formatNumber(java.lang.Number value)
<af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}"/>
An additional Expression Language formatting function for numbers is shown in Example 21-14.
Example 21-14 formatNumber2(java.lang.Number value, int maxFractionDigit) Function
fnd:formatNumber2(java.lang.Number value, int maxFractionDigit)
Returns the formatted number value using the user preferences for the number format mask, grouping separator and decimal separator.
Overrides the scale—the number of digits following the decimal point—of the user preferred number format pattern using the value assigned to maxFractionDigit
.
This function produces the tag shown in Example 21-15.
Use the Expression Language function shown in Example 21-16 to format currency.
Example 21-16 fnd:formatCurrency(java.lang.Number currencyAmount, java.lang.String currencyCode) Function
fnd:formatCurrency(java.lang.Number currencyAmount, java.lang.String currencyCode)
Returns the formatted currency amount value in numeric form along with the relevant currency code. Applications Core uses the currency code as defined in FND_CURRENCIES
to format the currencyAmount
value, rather than the number format mask preference. User preferences for grouping and decimal separators are used to format the value.
This function produces the tag shown in Example 21-17.
Use the Expression Language function shown in Example 21-18 to format dates.
Example 21-18 fnd:formatDate(java.util.Date dateValue) Function
fnd:formatDate(java.util.Date dateValue)
Returns the formatted date value based on the user preferred date format mask.
This function produces the tag shown in Example 21-19.
Example 21-19 Tag Produced by the Function fnd:formatDate(java.util.Date dateValue)
<af:convertDateTime pattern="#{applCorePrefs.dateFormatPattern}"/>
Use the Expression Language function shown in Example 21-20 to format date time values.
Example 21-20 fnd:formatDateTime(java.util.Date dateTimeValue) Function
fnd:formatDateTime(java.util.Date dateTimeValue)
Returns the formatted date time value using the user preferences for the date and time format masks and time zone.
This function produces the following tag as shown in Example 21-21.
Example 21-21 Tag Produced by the Function fnd:formatDateTime(java.util.Date dateTimeValue)
<af:convertDateTime type="both" timeZone="#{applCorePrefs.UPTZ}" pattern="#{applCorePrefs.UPTZPattern}"/>
Use the Expression Language function shown in Example 21-22 to format date time values with user formatting masks and the user-specified time zone.
Example 21-22 fnd:formatDateTimeTZ(java.util.Date dateTimeValue, java.util.TimeZone timeZone) Function
fnd:formatDateTimeTZ(java.util.Date dateTimeValue, java.util.TimeZone timeZone)
Returns the formatted date time value using the user preferences for date and time format masks and the user-specified time zone.
This function produces the tag shown in Example 21-23.
Applications Core formats the value as defined by the Expression Language function and produces the tags described in this section.
For example, the date formatting Expression Language function produces a tag such as the one shown in Example 21-24.
For more information about what happens at runtime when you format numbers, currency and dates using Expression Language functions, see Section 21.2, Section 21.3 and Section 21.5.
Oracle Fusion applications should be enabled to provide bi-directional support. Examples of bi-directional languages are Arabic (Middle East and North Africa) and Hebrew (Israel). These scripts are generally written from right to left. The entire UI must also render from right to left. That is, if you took a standard English UI and placed a mirror next to your computer screen, the image in the mirror is exactly what is expected of speakers of bi-directional languages. Some rules come into play, such as how to correctly render English text or numerals embedded in a bi-directional script, but this generally is handled by underlying technologies (in this case, Oracle ADF). An example of this is that the text, which translates to United Arab Emirates:
for a user with English locale needs to be displayed as:
for a user with Arabic Locale.
Before you begin, create an entity and a view object from ADF Business Components. Drag and drop some of the attributes from the view object into a JSF page.
UI Components such as af:panelGroupLayout
and af:column
have an align
or an halign
attribute that allows developers to align a particular component in one direction. A typical example of this is a number field that is always aligned to the right by Oracle Fusion Applications standards. Now, if a UI component (a non-number field) is hardcode-aligned to the left or right in the JSF page, the implication in the Arabic locale is that the UI component does not switch to its corresponding mirror image position. As a result, there are discrepancies in the user interface in the Arabic locale.
To correct this situation, you must not hardcode a UI component (non-number field) to the left or right. You should always use the start
or end
values for the halign
and align
attributes to make them bi-directional compatible, as shown in Example 21-25.
Example 21-25 Making align Attributes Bi-directional
<af:panelGroupLayout id="pgl5" layout="horizontal" halign="end"> <af:commandButton text="#{ResourcesGenBundle['Action.Advanced.AdvancedSearch']}" actionListener="#{ItemRelationshipRegionalSearchBean.onAdvancedButtonClick}" id="cb4"/> <af:spacer width="8" height="10" id="s7"/> <af:image source="/images/seperator_img.png" id="i2" shortDesc=""/> <af:spacer width="8" height="10" id="s8"/> <af:commandButton textAndAccessKey="#{ResourcesGenBundle['Action.Search1']}" id="cb5" actionListener="#{ItemRelationshipRegionalSearchBean.onRegionalAreaSearchClick} "/> <af:spacer width="5" height="10" id="s9"/> <af:commandButton text="#{ResourcesGenBundle['Action.Reset']}" id="cb6" actionListener="#{ItemRelationshipRegionalSearchBean.onResetBtnClick}"/> <af:spacer width="5" height="10" id="s10"/> </af:panelGroupLayout>
Here, the halign
attribute for the panel group has been set to end
, which means that this component will be bi-directional compatible and will switch to its mirror image position in the Arabic locale.
In the English locale shown in Figure 21-12, the panel containing the three buttons Advanced, Search and Reset is aligned to the right.
Therefore, the expected behavior is that, in the Arabic locale shown in Figure 21-13, the panel, with the buttons' text in Arabic, is aligned to the left.
In Oracle Fusion applications, all UI components should provide bi-directional support. This means that, in bi-directional locales such as Arabic and Hebrew, UI components should be shown from right-to-left instead of left-to-right. This also includes images that are shown on the UI to give a pictorial representation of an instruction to the end user. If an image is directional (unsymmetrical), it should be flipped and shown as its corresponding mirror image from right-to-left. However, if an image is non-directional (symmetrical) it need not be flipped since its mirror image is the image itself. To make an image bi-directional, you have to use the function fnd:bidiImage
(<Image-Path>)
, shown in Example 21-26, that is provided as a part of the ApplCore library.
Example 21-26 Using fnd:bidiImage to Provide Bi-directional Support for an Image
<af:commandImageLink icon="#{fnd:bidiImage('search_ena.png')}" action="search" />
In bi-directional locales, instead of displaying the image search_ena.png
directly, the fnd:bidiImage
suffixes an _rtl
just before the start of the extension to the parameter file-name given to it (in this case, the image icon search_ena.png
becomes search_rtl_ena.png
), and then displays the image search_rtl_ena.png
on the JSF page. Now, if the latter image has been stored as a mirror image of the former, bi-directionality is ensured for the image.
Figure 21-14 shows how the search image next to the Search by Year option appears in an English locale.
Figure 21-15 shows how the command image link supports bi-directional behavior in an Arabic locale.
A mnemonic key, also called a soft key, is a shorthand name for a key, command, or menu option. Mnemonic keys are used in Oracle Fusion applications to activate the buttons in a page. This is made possible by using a <Modifier>+<Access Key>.
Note that modifiers are browser-specific. Internet Explorer, Safari and Google Chrome use the Alt key; Firefox uses Alt+Shift.
The Access Key is defined in the source code by the developer.
In Oracle Fusion applications, the access key for a particular button needs to be externalized so that the keys for different locales are different. Do not hardcode the accessKey
or the textAndAccessKey
attribute provided as a child attribute of the af:commandButton
tag. Hard-coding these keys would cause mnemonic key issues. For example, if an English letter is hardcoded as an access key in the JSF layer, an Arabic user may not be able to use this key because there are no English letters on his keyboard. Instead the accessKey
and textAccessKey
attributes should be externalized using either the applCoreBundle or any resource bundle defined in an Oracle Fusion application's project.
Before you begin, create an entity object and a view object from ADF Business Components. Drag and drop some of the attributes from the view object into a JSF page. Create a panel group and add a command button to it.
There are two attributes provided by Oracle ADF for mnemonic keys for buttons: accessKey
and textAndAccessKey
. The attribute accessKey
takes as a value just the access key to be typed by the user, whereas the attribute textAndAccessKey
takes as a value the text to be displayed on the button and the short-hand key to be typed by the user. You must make sure that the accessKey
and textAndAccessKey
attributes are never hard-coded. Both should be externalized and read from resource bundles. In the case of the textAndAccessKey
attribute, the value of the access key usually is preceded by an ampersand (&) in the resource bundle. In case the ampersand sign is not present in the bundle, the first letter of the text is treated as the access key.
How to use the textAndAccessKey
attribute using the applCoreBundle is shown in Example 21-27.
Example 21-27 Using the textAndAccessKey Attribute Using the applCoreBundle
f:facet name="actionButtonBar"> <af:panelGroupLayout layout="horizontal" id="panelGroupLayout11" styleClass="AFStretchWidth"> <af:commandButton id="commandButton2" textAndAccessKey="#{applCoreBundle.SAVE}" actionListener="#{bindings.Commit.execute}"/>
How to use the textAndAccessKey attribute using the resource bundles is shown in Example 21-28.
Example 21-28 Using the textAndAccessKey Attribute Using Resource Bundles
<af:commandButton id="commandButton2" textAndAccessKey="#{TemporaryBundle.SAVE}" actionListener="#{bindings.Commit.execute}"/>
Here, the resource bundle TemporaryBundle must be defined in the JSF page containing the af:commandButton
tag. Also, the textAndAccessKey
has been externalized and is read from the applCore bundle and the resource bundle , as shown in the examples, which is the correct way to define mnemonic keys. The values for this particular id SAVE in the resource bundles are "Save" in the English locale, "\uC800\uC7A5(&S)" in the Korean locale (S is the access key) and "\u062D\u0641&\u0638" (\u0638 is the access key) in the Arabic locale.
Example 21-29 shows how to externalize the accessKey
attribute using the applCoreBundle.
Example 21-29 Externalizing the accessKey Attribute Using the applCoreBundle
<af:commandToolbarButton text="#{applCoreBundle.SAVE_AND_CLOSE_SHORT_DESC}" id="ctb1" actionListener="#{BillingCycleBean.saveAndClose}" accessKey="#{applCoreBundle.ACCESSKEY}">
Example 21-30 shows how to externalize the accessKey
attribute using a resource bundle.
Example 21-30 Externalizing the accessKey Attribute Using a Resource Bundle
<af:commandToolbarButton text="#{TemporaryBundle.SAVE_AND_CLOSE_SHORT_DESC}" id="ctb1" actionListener="#{BillingCycleBean.saveAndClose}" accessKey="#{TemporaryBundle.ACCESSKEY}">
Here, the accessKey attribute has been externalized and is read from the applCore bundle and the resource bundle as shown in the examples. Note that the TemporaryBundle
has to be defined as the viewControllerBundle
in the JSF page containing the command button. The values for this particular resource ID ACCESSKEY
are "S" in the English locale, ""\uC800" in the Korean locale and "\u0638" in the Arabic locale, as defined in the resource bundle.
Notes:
When a textAndAccessKey
attribute has a value with more than one "&", the letter following the first "&" is chosen as the access key.
When an accessKey
attribute has more than one letter, the first letter is chosen as the access key.
In Figure 21-16, the buttons on the top right are examples of buttons with soft keys that must not be hardcoded, so that they can be different for different locales.
With ADF Desktop Integration technology, users can browse, edit and upload data through a Microsoft Excel spreadsheet. Localization formatting differs from to ADF Faces pages:
Number and date/time values are formatted based on the format pattern specified by the styles in the Excel spreadsheets. The format pattern follows Microsoft standard instead of Java standard.
Number separators are decided by the client operating system locale.
In ADF Faces pages, number and date/time values are formatted based on the format patterns selected in the Oracle Fusion application's Preference UI. Number separators are extracted from the application's number format patterns.
Number separators in ADF Desktop Integration spreadsheets vary according to the client OS locale. Number formatting is decided by the style defined in Excel spreadsheet. For example, when opening an ADF Desktop Integration spreadsheet with French Windows XP and Excel, number 1000.5 (One thousand point 5) displays as 1 000,5. It is displayed as 1.000,5 in German Windows XP and Excel. Assuming one fractional digit is specified in the style.
To achieve this, developers need to specify correct styles for numbers at design time.
For more details about Excel styles, refer to the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.
Before you begin, create a workable ADF Desktop Integration spreadsheet and have the attributes in place. Related attributes are of types: java.math.BigDecimal, java.lang.Integer, or java.lang.Long.
Define styles for each type of cells and configure the cell appearance using the Oracle Fusion Applications UI standard.
Decimal Number Formatting
Follow these steps to modify the existing style for formatting decimal numbers and apply the style to the cell containing a decimal number value.
In Excel, select Home > Cell Styles.
Right-click the style name and select Modify from the context menu, as shown in Figure 21-17.
On the Style dialog, shown in Figure 21-18, click Format.
Select the Number tab and select the Number category. Specify the number of decimal places and the format of negative numbers according to your business logic. If you want to see grouping separator in the number values, make sure that Use 1000 Separator is checked, as shown in Figure 21-19.
Click OK and save the Excel file.
Integer Formatting
Integer formatting is the same as decimal formatting except no fractional digit should display. This can be done by specifying 0 for Decimal places when modifying the style.
ID Formatting
An ID value is a sequence of digits, such as an Invoice Number, Service Request ID, or Bank Account. Displaying ID values should not vary based on a user's preference or client OS locale. That is, ID values should be printed as text instead of numbers.
In Oracle Fusion applications, the length of an ID value typically is 13 or 18. By default, Excel formats such long numbers with Scientific Notation format, which is not desired for Oracle Fusion applications. For instance, an Invoice Number 1234567890123 (13 digits) is displayed as 1.23457E+12. It is not a valid Invoice Number when it is printed out.
To avoid the default formatting of Excel in such cases, developers need to customize the styles for ID values.
In Excel, select Home > Cell Styles
Right-click the style name and select Modify from the context menu.
Click Format.
Select the Number tab and select the Text category.
Click OK. In the Style dialog, Figure 21-20 shows that @ is defined as the Number style.
Click OK and save the file.
As a result, Figure 21-21 shows that an ID value is displayed as text without any number formatting.
When dragging and dropping a binding to generate the components in an ADF Desktop Integration spreadsheet, the framework generates default styles for those values based on the Java type of the values. However, these styles may not be correct for formatting number values. Therefore, you may need to refine the styles according to business logic.
At runtime, ADF Desktop Integration will pass the style specified in the ADF Desktop Integration unpublished spreadsheet (known as the design time file) to the published spreadsheet during the publication process. When a user opens the published spreadsheet, Excel formats the numbers according to the combination of styles and client OS locale.
Grouping and decimal separators of currency values vary based on the client OS locale, while the number of fraction digits is controlled by the style defined in the Excel spreadsheet.
You should not display currency symbols or currency codes with currency numbers in the same cell. Instead, you need to display currency symbols or currency codes in a separate cell.
Before you begin, create a workable ADF Desktop Integration spreadsheet and have the attributes in place. The related attribute is of type java.math.BigDecimal.
Define styles for each type of cells and configure the cell appearance using the Oracle Fusion Applications UI standard.
Follow these steps to modify an existing style for formatting currency values and apply it to the corresponding cells.
In Excel, select Home > Cell Styles, right-click the style name and select Modify from the context menu.
Click Format.
Select the Number tab and select the Currency category. Specify the number of Decimal places and the format of negative numbers according to your business logic.
In Oracle Fusion applications, you should display the currency symbol in a separate cell. Make sure None is selected for Symbol, as shown in Figure 21-22.
Click OK and save the file.
When dragging and dropping a binding to generate the components in an ADF Desktop Integration spreadsheet, the framework generates default styles for those values based on the Java type of the values. However, these styles may not be correct for formatting number values. Therefore, you may need to refine the styles according to business logic.
At runtime, ADF Desktop Integration will pass the style specified in the unpublished spreadsheet (the design time file) to the published spreadsheet during the publication process. When a user opens the published spreadsheet, Excel formats the numbers according to the combination of styles and the client OS locale.
The currency code should be displayed in a cell other than the cell containing the Currency Value. The currency code in this cell should be printed as text.
The format of date and timestamp values in ADF Desktop Integration spreadsheets varies according to the client OS locale.
For example, when opening an ADF Desktop Integration spreadsheet with French Windows XP and Excel, the date May 25th, 2011 is displayed as 25/05/2011. It displays as 2011-05-25 in Korean Windows XP and Excel.
To achieve this, developers need to specify correct styles for date and timestamp values at design time.
For more details about Excel styles, refer to the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.
Before you begin, create a workable ADF Desktop Integration spreadsheet and have the attributes in place. Related attributes are of types: java.sql.Date or java.sql.Timestamp.
Define styles for each type of cell and configure the cell appearance using Oracle Fusion Applications UI standards.
Formatting the Date
Follow these steps to modify an existing style for formatting dates and apply it to the correspondent cells.
In Excel, select Home > Cell Styles
Right-click the style name and select Modify from the context menu.
Click Format.
Select the Number tab and select the Date category. Set the value of Locale (location) to your Windows OS locale. For example, if you are using English Windows XP, this Locale should be set to English (U.S.).
Select a type beginning with an asterisk (*), as shown in Figure 21-23. There are two such Types: one is short date format, and the other is long date format. Choose one according to your business requirement.
Note that date formats display date and time serial numbers as date values. Date formats that begin with an asterisk (*) respond to changes in regional date and time settings that are specified for the operating system. Formats without an asterisk are not affected by operating system settings.
Click OK and save the file.
Formatting the Timestamp
Follow these steps to define a style for formatting the timestamp and apply it to the corresponding cells.
In Excel, select Home > Cell Styles.
Right-click the style name and select Modify from the context menu.
Click Format.
Select the Number tab and select the Time category. Set the value of Locale (location) to your Windows OS locale. For example, if you are using English Windows XP, this Locale should be set to English (U.S.).
Select the type beginning with an asterisk (*), as shown in Figure 21-24.
Click OK and save the file.
Note: With current ADF Desktop Integration support, it is impossible to display both the date and the time part of a timestamp value in a single cell if you want to see its format varying according to client OS locale.
Workaround
To display the date and time, formatted according to the client OS locale, you can use two cells: One for displaying the date part and another for displaying the time part of the timestamp. Then format each of these cells separately as described for date and time format.
When dragging and dropping a binding to generate the components in an ADF Desktop Integration spreadsheet, the framework generates default styles for those values based on the Java type of the values. However, these styles may not be correct for formatting number values. Therefore, you may need to refine the styles according to business logic.
At runtime, ADF Desktop Integration will pass the style specified in the unpublished spreadsheet (the design time file) to the published spreadsheet during the publication process. When a user opens the published spreadsheet, Excel formats the date or timestamp values according to the combination of styles and the client OS locale.
For timestamp values, time zone conversion also happens at runtime. See Section 21.9.3.4, "Honoring Time Zones" for more details.
There are two time zones involved in time zone conversion for timestamp values in ADF Desktop Integration spreadsheets. One is the time zone of the Oracle Fusion Applications server, called the server time zone. The other is the time zone of the client system on which the ADF Desktop Integration spreadsheet is open, which is called the client time zone.
At runtime, conversion between server time zone and client time zone happens automatically for timestamp values in ADF Desktop Integration spreadsheets.
For example, if the server time zone is (GMT-8:00) Pacific Time (US & Canada) and the client time zone is (GMT+8:00) Beijing, Chongqing, Hong Kong, Urumqi, the timestamp value in the database 2011-05-22 20:00:00 is converted to 2011-05-23 12:00:00 at runtime and displayed as 2011-05-23 or 12:00:00 in the ADF Desktop Integration spreadsheet, depending on the format style defined for the corresponding cells.
BI Publisher can pass Oracle Fusion applications Preferences Number Format, Date Format and Time Format to BI Publisher reports using function format-date, format-number or format-currency, if BI Publisher is running in BI Publisher and Oracle Fusion applications integration mode.
Note:
To modify RTF templates, BI Publisher Template Builder for Word should be installed on Microsoft Word 2003, 2007 or higher version. After it is installed, there is a BI Publisher menu in the Word menu bar.
To format numbers in an RTF template with an Oracle Fusion application user-preferred number format pattern, Oracle's format-number function must be used with 'XDODEFNUM' used as a format mask, for example:
<?format-number:fieldName; 'XDODEFNUM'?>
For details about the format-number function, see "Number, Date and Currency Formatting" in the Oracle Fusion Middleware Report Designer's Guide for Oracle Business Intelligence Publisher.
Follow these steps to format numbers with the Oracle Fusion application user-preferred number format pattern:
Open your RTF template file with Word.
Select BI Publisher > Sample XML and select a sample XML file that contains sample data for the number fields to be formatted in the RTF template.
Double-click the number field to be modified (such as ORDER_TOTAL). In the BI Publisher Properties dialog, select the Properties tab and make sure that Regular Text is selected for Type.
Select the Advanced tab and enter format code, as shown in Figure 21-25.
Click OK and save the RTF template file.
Follow these steps to format a number value in graphs in BI Publisher reports
To set format masks for graphs, an Oracle Fusion application BI Publisher report designer needs to change the RTF template graph code manually.
Edit the graph and change the graph definition code in the Advanced tab of the Graph dialog in the template builder.
Use an XSLT format such as:
<xsl:value-of select="xdoxslt:xdo_format_number($_XDOXSLTCTX,current-group()/SGT_NUMBER,'XDODEFNUM')" />
to format a currency value on the graph.
At runtime, XDODEFNUM is replaced with the number format pattern selected in the Oracle Fusion application Preferences UI. Consequently, the number is formatted with the Oracle Fusion application number format pattern. For example, if a user selects -1'234,567 as the Number Format in the Preferences UI, as shown in Figure 21-26, the number 1000.8888 (one thousand point eight eight eight eight) will be displayed as 1'000,889 in the BI Publisher report.
When using XDODEFNUM as the format mask in format-number, the format of the number is fully controlled by the Oracle Fusion application Number Format, including grouping separator, decimal separator, number of fractional digit, and form of negative numbers.
In the BI Publisher and Oracle Fusion application integration environment, if format-number is used to format a number, whether or not XDODEFNUM is used as the format mask, the grouping separator and decimal separator are always derived from the Oracle Fusion application Number Format.
Therefore, an integer could be formatted as:
<?format-number:fieldName; '999G999'?>
In this case, if the Number Format is -1'234,567, the integer 10000 is displayed as 10'000 in the BI Publisher report.
If you do not wish to display a number with fractional digits or grouping separators (such as PO numbers, Bank Accounts, or Invoice Numbers), enter <?fieldName?> in step 4 of [To format numbers]. In such cases, the Number Format has no effect on the field; it always is displayed as text.
Currency fields in RTF templates can be formatted with the format-currency function:
<?format-currency:Amount_Field;CurrencyCode;displaySymbolOrNot?>
where
Amount_Field takes the tag name of the XML element that holds the amount value in your data.
CurrencyCode can be set to a static value or it can be set dynamically. If the value will be static for the report, enter the ISO three-letter currency code in single-quotes, such as 'USD'.
To set the value dynamically, enter the tag name of the XML element that holds the ISO currency code. Note that an element containing the currency code must be present in the data.
At runtime, the Amount_Field will be formatted according to the format you set up for the currency code in the report properties.
displaySymbolOrNot takes as a value either 'true' or 'false' in single quotes. When set to 'true', the currency symbol will be displayed in the report based on the value for CurrencyCode. If you do not wish the currency symbol to be displayed, you can either enter 'false' or simply omit the parameter.
For details about the format-currency function, see "Number, Date and Currency Formatting" in the Oracle Fusion Middleware Report Designer's Guide for Oracle Business Intelligence Publisher.
To use the format-currency function, the currency values in your data source must be in a raw format, with no formatting applied (for example: 1000.00). If the value has been formatted for European countries (for example: 1.000,00), the format will not work.
To format your currency values with the currency code passed dynamically from a particular business flow, you must have the currency code defined in your data source.
In the Oracle Fusion application and BI Publisher integration environment, Currency is passed to BI Publisher through XDODEFCC. For example, if US Dollar is selected for Currency in Preferences, as shown in Figure 21-27, at runtime, XDODEFCC is replaced with USD.
Therefore, to format a currency value with the Currency selected in Oracle Fusion application Preferences, you can use:
<?format-currency:Amount_Field; 'XDODEFCC'?>
or
<?format-currency:Amount_Field; 'XDODEFCC';'true'?>
To format currency values with the currency code selected in a particular business flow instead of the Currency code selected in Oracle Fusion application Preferences, you can use:
<?format-currency:Amount_Field; CurrencyCode_Field?>
or
<?format-currency:Amount_Field; CurrencyCode_Field;'true'?>
where CurrencyCode_Field is the tag name of the XML element that holds the currency code selected in the business flow. At runtime, CurrencyCode_Field is replaced with a currency code, such as USD, JPY, or EUR.
Note: Whether the currency code is set to a static value, such as XDODEFCC, or a dynamic value passed from a particular business flow, the grouping separator and decimal separator in currency values are always derived from the Number Format selected in Oracle Fusion application Preferences. The parameter currency code in the format-currency function controls the number of fraction digits and the placement of the grouping separator in the output.
Example
Assume that <?format-currency:Amount_Field; CurrencyCode_Field?> is applied in the RTF template for a currency field.
In the report properties, if the format mask for USD is 9G999D99, for JPY it is 9G999 and for INR it is 9G99G99G999D99, and if a user has set the Number Format as -1,234.567 in Preferences (uses comma (,) as the grouping separator and dot (.) as decimal separator), the currency value of 1234567.89 will display as shown here, depending on the currency passed to CurrencyCode Field at runtime.
If 'USD' is passed to CurrencyCode_Field at runtime, the value displayed is 1,234,567.89.
If 'JPY' is passed to CurrencyCode_Field at runtime, the value displayed is 1,234,568.
If 'INR' is passed to CurrencyCode_Field at runtime, the value displayed is 12,34,567.89.
If a European user changes the Number Format to -1'234,567 in Preferences (uses the apostrophe (') as the grouping separator and comma (,) as the decimal separator), the currency value of 1234567.89 will display as:
If 'USD' is passed to CurrencyCode_Field at runtime, the value displayed is 1'234'567,89.
If 'JPY' is passed to CurrencyCode_Field at runtime, the value displayed is 1'234'568.
If 'INR' is passed to CurrencyCode_Field at runtime, the value displayed is 12'34'567,89.
Follow these steps to format a currency field in the BI Publisher RTF template.
Open the RTF template file with Word.
Expand BI Publisher > Sample XML and select a sample XML file that contains sample data for the number fields to be formatted in the RTF template.
Double-click the currency field to be modified (for instance ORDER_TOTAL). In the BI Publisher Properties dialog, click the Properties tab and make sure Type is set to Regular Text.
Click the Advanced tab and enter format code, as shown in Figure 21-28.
Click OK and save the RTF template file.
Follow these steps to format a currency value in graphs in BI Publisher reports
To set format masks for graphs, an Oracle Fusion application BI Publisher report designer needs to change the RTF template graph code manually.
Edit the graph and change the graph definition code in the Advanced tab of the Graph dialog in template builder.
Use an XSLT format, such as <xsl:value-of select="xdoxslt:xdo_format_currency($_XDOXSLTCTX,current-group()/SGT_CURRENCY,'XDODEFCC')" />
to format a currency value on the graph.
In the BI Publisher RTF template, a date or timestamp can be formatted as:
<?format-date:date_string; 'ABSTRACT_FORMAT_MASK';'TIMEZONE'?>
where:
ABSTRACT_FORMAT_MASK can be any date format pattern supported by BI Publisher, such as YYYY-MM-DD or DD/MM/YYYY.
TIMEZONE is optional. It can be any valid time zone ID, such as PST or UTC. If it is not specified, the BI Publisher report time zone is applied implicitly.
For details about the format-date function, see "Number, Date and Currency Formatting" in the Oracle Fusion Middleware Report Designer's Guide for Oracle Business Intelligence Publisher.
To use the format-date function, the date from the data source must be in canonical format, which is YYYY-MM-DDThh:mm:ss+HH:MMwhere:
YYYY is the year
MM is the month
DD is the day
T is the separator between the date and time component
hh is the hour in 24-hour format
mm is the minutes
ss is the seconds
+HH:MM is the time zone offset from Universal Time (UTC), or Greenwich Mean Time
For example: 2011-05-26T09:30:10-07:00.
The data after the T is optional, therefore 2011-05-26 is a valid date.
Note:
If the time component and time zone offset are not included in the XML source date, BI Publisher assumes it represents 12:00 AM UTC (that is, YYYY-MM-DDT00:00:00-00:00).
In the BI Publisher and Oracle Fusion application integration environment, XDODEFDATE is used to pass the Oracle Fusion application date format pattern to BI Publisher, and XDODEFTIME can pass the Oracle Fusion application time format pattern to BI Publisher reports.
Consider that "yyyy-MM-dd (2011-05-27)" is selected for the Date Format, and "a hh:mm:ss (AM 12:49:13)" is selected for the Time Format in Oracle Fusion application Preferences, as shown in FIGURE5:
At runtime, XDODEFDATE is replaced with "yyyy-MM-dd" and XDODEFTIME is replaced with "a hh:mm:ss".
Therefore, to format date or timestamp values in BI Publisher reports with the Date Format or Time Format selected in Oracle Fusion application Preferences, the format-date function can be used:
To display date only values
<?format-date:Date_Only_Field; 'XDODEFDATE'?>
Only the date is displayed, such as 2011-05-27.
To display time only values
<?format-date:Time_Only_Field; 'XDODEFTIME'?>
Only the time is displayed, such as AM 12:49:13.
To display datetime values
<?format-date:Datetime_Field; 'XDODEFDATE XDODEFTIME'?>
Both date and time are displayed, such as 2011-05-27 AM 12:49:13.
To display System Date (sysdate)
<?format-date:xdoxslt:sysdate_as_xsdformat();' XDODEFDATE XDODEFTIME '?>
A sample output: 2011-05-27 AM 12:49:13.
With these codes, the format of date or timestamp values varies according to the Date Format or the Time Format chosen in Oracle Fusion application Preferences.
Follow these steps to format date or timestamp values in the RTF template.
Open the RTF template file with Word.
Select BI Publisher > Sample XML and select a sample XML file that contains sample data for the number fields to be formatted in RTF template.
Double-click the date or timestamp field to be modified, such as ORDER_DATE. In the BI Publisher Properties dialog, click the Properties tab and make sure that Type is set to Regular Text.
Click the Advanced tab and enter format code, as shown in FIGURE6.
Click OK and save the file.
Follow these steps to format date or timestamp values in graphs in BI Publisher reports.
To set format masks for graphs, an Oracle Fusion application BI Publisher report designer needs to change the RTF template graph code manually.
Edit the graph and change the graph definition code in the Advanced tab of the Graph dialog in template builder.
Use an XSLT format such as <xsl:value-of select="xdoxslt:xdo_format_date($_XDOXSLTCTX,current-group()/SGT_DATE,'XDODEFDATE XDODEFTIME')" />
to format a date-time value on the graph.
If you do not wish to format date or timestamps according to the Oracle Fusion application Date or Time format, you can use Oracle abstract format masks, such as:
<?format-date:ORDER_DATE;'SHORT'?>
<?format-date:ORDER_DATE;'LONG'?>
<?format-date:xdoxslt:sysdate_as_xsdformat();'MEDIUM'?>
For more abstract format masks, see "Oracle Abstract Format Masks" in "Number, Date, and Currency Formatting" in the Oracle Fusion Middleware Report Designer's Guide for Oracle Business Intelligence Publisher.
With using abstract format masks, date and timestamp values are formatted according to the default format of the Oracle Fusion application user's locale.
In the BI Publisher and Oracle Fusion application integration environment, the Time Zone selected in Oracle Fusion application Preferences is passed to the BI Publisher server and overrides the BI Publisher report time zone automatically. As a result, if the TIMEZONE parameter is not specified in the format-date function, a date/time field in the BI Publisher report is formatted with the Time Zone selected in Oracle Fusion application Preferences. That is, time zone conversion happens between the BI Publisher server time zone and the Oracle Fusion application Preferences time zone.
If you do not wish to format a date/time field with the Oracle Fusion application Preferences Time Zone, you must explicitly specify a time zone ID in the format-date function:
<?format-date:Datetime_Field; 'XDODEFDATE XDODEFTIME', 'timezone'?>
where timezone is a static value, such as PST, UTC, or IST.
Note:
There is no parameter that passes the Oracle Fusion application Corporation Time Zone (CRTZ) or Legal Entity Time Zone (LETZ) to the BI Publisher server. Therefore, you cannot format a date/time value with CRTZ or LETZ dynamically by using a parameter to pass CRTZ or LETZ to BI Publisher reports. Instead, you have to hard-code the time zone ID within the format-date function.
All numerical-based values need to be formatted correctly when they are presented to a user in Oracle Fusion applications graphs. For instance, a value of 1234.5 in the database might need to be displayed as 1 234,500 or 1,234.500 or 1.234,5. The user can change the number of digits found after the decimal digit, grouping separator, and decimal separator.
Before you begin, create an entity object and a view object with number fields, including any of the following attribute types: java.math.BigDecimal, java.lang.Integer, or java.lang.Long. Drag and drop the entity and create a data visualization component such as a pie graph, bar graph or a line graph.
Numerical values on all parts of the graph need to be formatted according to the user's number formatting preferences in Oracle Fusion applications. Developers need to add the tag <af:convertNumber>
to all the tags in the graph where numerical values are displayed.
The ADF Data Visualization area graph supports number formatting on its Y1 and Y2 axis tick labels, and for marker text that appears on the data points. Users can customize the number formatting by adding <af:convertNumber>
to the <dvt:y1TickLabel>
, <dvt:y2TickLabel>
, <dvt:y1Format>
, and <dvt:y2Format>
tags. Example 21-31 shows how to configure these tags.
Example 21-31 Area Graph Y1 Axis Number Formatting
<dvt:y1TickLabel> <af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}"/> </dvt:y1TickLabel> <dvt:markerText><dvt:y1Format> <af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}"/> </dvt:y1Format></dvt:markerText>
In Figure 21-31, numbers such as 20,000 and 40,000 on the Y axis and numbers such as 12,003.67 on the tooltip are examples of numbers on an area graph that should be formatted according to the user's number preferences in graphs in Oracle Fusion applications.
Note: For integer fields, use pattern="#{applCorePrefs.integerFormatPattern}"
just like integer formatting in ADF Faces.
Generally, an attribute on an ordinal axis (O1 axis and X1 axis) of a graph in ADF Data Visualization is considered to be text, irrespective of its data type in the model or view layer. A developer can add af:convertNumber to such a view attribute by first adding dvt:attributeFormat
to it, and only then will the resultant values on the x-axis and o-axis be formatted according to the user's number preferences. The name="size"
entry refers to the categorical attribute (attribute on the ordinal/x axis). To format the integers, use pattern="#{applCorePrefs.integerFormatPattern}"
, as shown in Example 21-32.
Example 21-32 Area Graph O Axis Formatting
<dvt:attributeFormat id="af1" name="size"> <af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}"/> </dvt:attributeFormat>
In Figure 21-32, numbers such as 2234 and 1014 are examples of numbers on the O axis of an area graph that should be formatted according to the user's number preferences.
Other Types of Graphs
Example 21-32 just gives an example of number formatting in area graphs. Table 21-1 presents the tags in which af:convertNumber
can be added for number formatting in other types of graphs, such as bar graphs and pie charts, and the graphs in which dvt:attributeFormat
can be used to format text attributes on the ordinal axis.
Table 21-1 Using af:convertNumber for Number Formatting and dvt:attributeFormat for Text Formatting
Graph Type | Parent Tags for af:convertNumber | Is dvt:attributeFormat Needed for Number Formatting? |
---|---|---|
Bar Graph |
<dvt:y1TickLabel>, <dvt:y2TickLabel>, <dvt:y1Format>, and <dvt:y2Format> |
Yes (for O1 axis) |
Bar Horizontal |
<dvt:y1TickLabel>, <dvt:y2TickLabel> ,<dvt:y1Format>, and <dvt:y2Format> |
Yes (for O1 axis) |
Bubble Graph |
<dvt:x1TickLabel>, <dvt:y1TickLabel>, <dvt:y2TickLabel>, <dvt:x1Format>, <dvt:y1Format>, <dvt:y2Format> and <dvt:zFormat> |
Yes (but not for O1 axis, for X1 axis) |
Combination graph |
<dvt:y1TickLabel>, <dvt:y2TickLabel>, <dvt:y1Format>, and <dvt:y2Format> |
Yes (for O1 axis) |
Funnel Graph |
<dvt:sliceLabel> |
Yes (for funnel section values) |
Line Graph |
<dvt:y1TickLabel>, <dvt:y2TickLabel>, <dvt:y1Format>, and <dvt:y2Format> |
Yes (for O1 axis) |
Pareto Graph |
<dvt:y1TickLabel>, <dvt:y2TickLabel>, and <dvt:y1Format> |
Yes (for O1 axis) |
Pie Graph |
<dvt:sliceLabel> |
Yes (for slice values) |
Pie Bar Charts |
<dvt:y1TickLabel>, <dvt:sliceLabel> and <dvt:y1format> |
Yes (for slice values) |
Gantt Chart |
<af:column> |
Yes (for O1 axis) |
Gauge |
<dvt:metricLabel> and <dvt:tickLabel> |
Yes (for O1 axis) |
ADF Pivot Table |
<af:inputText> or <af:outputText> whose parent tag is <dvt:dataCell> <af:inputText> or <af:outputText> whose parent tag is <dvt:headerCell> |
dvt:numberFormat
has been deprecated and all Oracle Fusion applications developers should use only af:convertNumber
to format numbers on graphs.
Before adding an af:convertNumber
tag to a graph, make sure that the autoPrecision
attribute of the parent tag (for example dvt:MarkerText
) is set to off. If autoPrecision
is set to on, ADF Data Visualization does not follow the converter correctly, and formats numbers automatically, which will be incorrect in Oracle Fusion applications, as the number will not honor user preferences.
Set scaling="none"
before adding the af:convertNumber
tag to a graph. Otherwise ADF Data Visualization will not follow the converter correctly.
Currency fields are represented by java.lang.BigDecimal in entity objects and view objects.
A currency field should always be formatted according to the currency code chosen in the context UI of the transaction.
For example, if the user selects "JPY" as the currency code from the context UI, the currency value should be formatted according to the Japanese Yen standard, whereas if USD is chosen as the currency code, the currency value should be formatted according to the American Dollar standard.
Oracle Applications Technology (ATG) provides two implementations to format numerical values according to the corresponding currency code:
fnd:currencyPattern(bindingToAmountCurrencyCode)
: This function formats the numerical value according to the currency code input as a parameter (for example, if "USD" is the input parameter, the value is formatted as #,##0.00)
fnd:currencyPatternWithPrecisionAndSymbol(bindingToAmountCurrencyCode, bindingToAttrNamePrecision, bindingToAttrNameCurrencySymbol)
: This function formats the numerical value according to the currency code input as the first parameter; the second parameter indicates the number of decimal digits in the formatted value; the third parameter determines whether the formatted string shows the symbol for the currency code, the currency code itself or nothing after the numerical value. (The third parameter can be symbol, code or none.)
Before you begin, create an entity object and a view object with number fields, including any of the following attribute types: java.math.BigDecimal, which is a currency value. Drag and drop the entity and create an ADF Data Visualization component, such as a pie graph, bar graph, or a line graph.
Numbers on the Y and O axis can be formatted as currency and can be displayed with the currency symbol, as shown in Example 21-33.
Example 21-33 Area Graph Y1 Axis Currency Value Formatting
<dvt:y1TickLabel> <af:convertNumber pattern="#{ fnd:currencyPattern(YourCurrencyCode)}"/> </dvt:y1TickLabel> <dvt:markerText><dvt:y1Format> <af:convertNumber pattern="#{ fnd:currencyPattern(YourCurrencyCode) }/> </dvt:y1Format></dvt:markerText>
In Figure 21-33, number values such as 40,000.00 and 80,000.00 on the Y axis, and 13,344.22 on the tooltip, are examples of number fields in an area graph that should be formatted according to the currency code for these values. Numbers on the O1 axis should also be formatted according to the currency code. (In this case, for USD, the format is #,##0.00.)
Other Types of Graphs
Example 21-33 gives an example of currency formatting in area graphs. Table 21-2 presents the tags in which af:convertNumber
can be added for currency formatting in other types of graphs, and the graphs in which dvt:attributeFormat
can be used to format text attributes on the ordinal axis.
Table 21-2 Using af:convertNumber for Currency Formatting and dvt:attributeFormat for Text Formatting
Graph Type | Tags in which af:convertNumber Can Be Added for Currency Formatting | Can dvt:attributeFormat Be Added for Currency Formatting of Attributes on the Ordinal Axis? |
---|---|---|
Bar Graph |
<dvt:y1TickLabel>, <dvt:y2TickLabel>, <dvt:y1Format>, and <dvt:y2Format> |
Yes |
Bar Horizontal |
<dvt:y1TickLabel>, <dvt:y2TickLabel>, <dvt:y1Format>, and <dvt:y2Format> |
Yes |
Bubble Graph |
<dvt:x1TickLabel>, <dvt:y1TickLabel>, <dvt:y2TickLabel>,<dvt:x1Format>, <dvt:y1Format>, <dvt:y2Format> and <dvt:zFormat> |
Yes (but not for O1 axis, for X1 axis) |
Combination Graph |
<dvt:y1TickLabel>, <dvt:y2TickLabel>, <dvt:y1Format>, and <dvt:y2Format> |
Yes |
Funnel Graph |
<dvt:sliceLabel> |
Yes (for funnel section values) |
Line Graph |
<dvt:y1TickLabel>, <dvt:y2TickLabel>, <dvt:y1Format>, and <dvt:y2Format> |
Yes |
Pareto Graph |
<dvt:y1TickLabel>, <dvt:y2TickLabel>,and <dvt:y1Format> |
Yes |
Pie Graph |
<dvt:sliceLabel> |
Yes (for slice values) |
Pie Bar Charts |
<dvt:y1TickLabel>, <dvt:sliceLabel> and <dvt:y1format> |
Yes (for slice values) |
Gantt Chart |
<af:column> |
No |
Gauge |
<dvt:metricLabel> and <dvt:tickLabel> |
No |
ADF Pivot Table |
<af:inputText>/<af:outputText> whose parent tag is <dvt:dataCell> <af:inputText>/<af:outputText> whose parent tag is <dvt:headerCell> |
Before adding an af:convertNumber
tag to a graph, make sure that the autoPrecision
attribute of the parent tag (such as dvt:MarkerText
) is set to off. If autoPrecision
is set to on, ADF Data Visualization does not follow the converter correctly, and instead formats numbers automatically, which will be incorrect in Oracle Fusion applications, as the number will not honor user preferences.
Set scaling="none"
before adding the af:convertNumber
tag to a graph. Otherwise, ADF Data Visualization will not follow the converter correctly.
All date values on a graph need to be formatted correctly when they are presented to a user. Users expect that they can input values according to their date formatting preferences. For instance, a value of 13th August, 2011 in the database might have to be displayed as 08/13/2011 for a certain user. A similar example of a date-time value is that a value of 26th July 2011, 2:00:00 PM might have to be displayed as 14:00 07/26/2011.
Before you begin, create an entity object and a view object with date or timestamp fields, including any of these attribute types: java.sql.Date or java.sql.Timestamp. Drag and drop the entity and create an ADF Data Visualization component, such as a pie graph, a bar graph or a line graph.
A graph typically uses categorical attributes, such as product, geography or year, on an ordinal axis (x axis or dvt:o1Axis) and for the marker tooltips. For the dvt:o1 axis, the data is considered as text no matter what its type in the underlying layers. Therefore, any number or date on the dvt:o1 axis does not honor any formatting.
A user can add af:convertNumber/af:convertDateTime
by first adding dvt:attributeFormat
to it, and the resultant values on the x-axis will be formatted, as shown in Example 21-34. Also, with this code, wherever the ordinal axis values are used in the user interface, they will appear with the proper formatting.
Example 21-34 Date Formatting on the O1 Axis
<dvt:attributeFormat id="af1" name="OrderDate"> <af:convertDateTime type="date" pattern="#{applCorePrefs.dateFormatPattern}"/> </dvt:attributeFormat>
Notes:
If there is a single categorical Date attribute being displayed on the O1Axis, the graph displays a TimeAxis instead of the typical O1 / Ordinal Axis. The TimeAxis will show dates in a hierarchical format instead of as a single label on an O1 Axis, for example June 27, 2001. To show a single label on the O1 Axis, the TimeAxis should be turned off (timeAxisType="TAT_OFF") and a <dvt:attributeFormat> should be used to specify the date format.
The Area graph displays a time axis when dates (object type java.util.Date) are specified for the column labels. Several timeXXX attributes are defined on the graph tag to customize the time axis. The child tag timeAxisDateFormat controls the format in which the time axis labels are displayed.
<dvt:timeAxisDateFormat dayFormat="DAY_OF_MONTH" monthFormat="MONTH_LONG" quarterFormat="NONE" yearFormat="YEAR_LONG" timeFormat="HOUR_MINUTE_SECOND"/>
Example 21-35 shows timestamp formatting on the O1 axis.
Example 21-35 Timestamp Formatting on the O1 Axis
<dvt:attributeFormat id="af1" name="LastUpdateDate"> <af:convertDateTime type="both" pattern="#{applCorePrefs.UPTZPattern}"/> </dvt:attributeFormat>
This is the same as the case of ADF Faces, in which the UPTZPattern is used to format timestamp values and dateFormatPattern is used to format date values.
In Figure 21-34, dates such as 2/1/2015 on the O1 axis and 8/9/2009 on the tooltip are examples of date fields on an area graph that should be formatted according to the user's date formatting preferences.
Other Types of Graphs
Example 21-35 just gives an example of date and date-time formatting in area graphs. Table 21-3 shows the tags in which af:convertDateTime can be added for date and timestamp formatting in the other types of graphs.
Table 21-3 Using af:convertDateTime for Date and Timestamp Formatting
Graph Type | Is dvt:attributeFormat Required? |
---|---|
Bar Graph |
Yes |
Bar Horizontal |
Yes |
Bubble Graph |
Yes |
Combination Graph |
Yes |
Funnel Graph |
Yes (for funnel section values |
Line Graph |
Yes |
Pareto Graph |
Yes |
Pie Graph |
Yes |
Pie Bar Charts |
Yes |
Gantt Chart |
No (Add |
Gauge |
N/A |
ADF Pivot Table |
<af:inputText>/<af:outputText> whose parent tag is <dvt:dataCell><af:inputText>/<af:outputText> whose parent tag is <dvt:headerCell> |
In Oracle Fusion Applications, National Language Support (NLS) refers to the ability to run an application instance in any single supported language, including specific regional or territorial number and date formats. Typically, in order to support a given language, only the customer-facing components of the software (user interface, lookup tables, online documentation, and so on) are translated. Translations are delivered via NLS patches.
Oracle Fusion Applications manage NLS attributes at the session level. At runtime, these attributes are initialized based on the user's profile, and are applied when needed by Applications Core. For example, the session date format mask is initialized based on the user's preferred date format mask. The date format mask is automatically applied when date is rendered and parsed. As such, it is unnecessary to manually specify NLS attributes in design time.
In certain situations, however, you may need to access the NLS attributes for the purposes of data formatting or parsing your code. To do so, use the managed bean ApplCorePrefs
.
Table 21-4 lists the Oracle Fusion Applications session NLS attributes, the profile used to set each attribute and the possible values for session attributes.
Table 21-4 Session NLS Attributes
Session Attribute | Profile | Values | Comments |
---|---|---|---|
|
|
Primary attribute used to represent the current language. Corresponds to the Looks up the corresponding |
|
|
Represents the two letter language code, which is derived using the |
||
|
Represents the NLS language, which is derived from the |
||
|
|
|
Setting this attribute results in an altered session in the database for the |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This attribute specifies the preferred currency code. It has no corresponding database attribute. |
|
|
|
This attribute specifies the preferred territory. This attribute differs from the database attribute |
|
|
|
This attribute specifies the preferred time zone value. |
|
|
|
Table 21-5 lists language and territory values used with NLS attributes.
Table 21-5 Language and Territory Values
LANGUAGE_TAG |
LANGUAGE_CODE |
LANGUAGE_ID |
NLS_LANGUAGE |
NLS_TERRITORY |
ISO_LANGUAGE |
ISO_TERRITORY |
NLS_CODESET |
ISO_LANGUAGE_3 |
---|---|---|---|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Oracle Fusion Applications does not use most of the database session NLS parameters. Instead, these are set to constant values such that typically, the user's preferred values are not reflected. This is true for most parameters except the following: NLS_LANGUAGE
which is set to view link view access, and NLS_SORT
, which is set to use the database linguistic sorting functionality.
The parameters TO_NUMBER
, TO_DATE
, TO_TIMESTAMP
and TO_CHAR
are used to format and parse SQL or PL/SQL statements. These parameters are based on constant values, the canonical format. The parameter FND_DATE
for PL/SQL packages also works with the canonical format. Formatting and parsing should be done at the presentation, rather than the model layer.
Oracle Fusion Applications session management controls database session parameters. As such, the database NLS session parameter values must not be altered.
Table 21-6 lists the following:
Database attribute: The database NLS session parameter name.
Associated session attribute: The Oracle Fusion Applications NLS session attribute name related to the database attribute name, if one exists. If the attributes are indeed related, configuring a value for the Oracle Fusion Applications NLS session attribute results in an ALTER SESSION
in the database layer.
Default value: The default value of the attribute. This value is configured both in the database and init.ora
as the database default.
Alter Session: Indicates whether an ALTER SESSION
is created in the database. When an ALTER SESSION
initiates at session creation or attachment, execute NLS_LANGUAGE
and NLS_TERRITORY
first, as these may affect other attributes.
Create: An ALTER SESSION
is created once, when the connection is first created.
Update: The ALTER SESSION
updates when the session attaches, or whenever an associated attribute value changes mid-session.
Never: An ALTER SESSION
is not created, and the default database value is unchanged.
Table 21-6 Localization Database Attributes
Database Attribute | Default Value | Alter Session | Comments |
---|---|---|---|
|
None |
Never |
This attribute need not be set as the default value is |
|
None |
Never |
This attribute need not be set as the default value is |
|
None |
Never |
Accept the default value. |
|
|
Create |
Fixed value. |
|
|
Create |
Fixed value. Does not require an attribute or profile. |
|
None |
Never |
Accept the default value. |
|
None |
Update |
The value of this attribute is based on the |
|
|
Create |
The value of this attribute is fixed. See the |
|
|
Create |
Fixed value. Does not require an attribute or profile. |
|
None |
Never |
Accept the default value. This parameter is not used. |
|
|
Create |
Fixed value. Choose group and decimal separators independently. |
|
None |
Update |
In order to enable linguistic sorting, the |
|
|
Create |
Fixed value. Does not require an attribute or profile. |
|
|
Create |
Fixed value. Does not require an attribute or profile. |
|
|
Create |
Fixed value. Does not require an attribute or profile. |
|
|
Create |
Fixed value. Does not require an attribute or profile. |
|
None |
Never |
Accept the default value. |
Note:
As the language attributes tracked on the session reflect Java values, you cannot use them for formatting on the PL/SQL layer.
The following standards and guidelines apply to localization formatting:
After dragging and dropping a view object onto a JSF page, the Oracle ADF tags for that view object are set. If you change the attributes of the view object after you create the JSF page, new Oracle ADF tags are not created. You must make these changes manually by editing the tags.
You can change tags generated by Applications Core at design time by editing them manually.