The Calendar is a standard object that allows selection of date and time values from a Calendar. It also allows the developer to specify validation rules ensuring that only valid dates can be selected. Both the List and Edit functions should invoke the Calendar on any date field.
For each date field within a form, you should provide the code necessary for the user to call the Calendar feature. However, the calendar is not a replacement for validating the data in the field.
The Calendar is automatically included in the TEMPLATE form.
For more information on the user interface standards for the Calendar, see the Oracle Applications User Interface Standards for Forms-Based Products.
Date and datetime fields should enable the List lamp. When the user invokes List on these fields, the form opens the Calendar window.
Date fields should use the ENABLE_LIST_LAMP LOV, which is included in the TEMPLATE form. This setting enables the menu and Toolbar List of Values entries for your date fields. Set '"Validate from List" to No on fields that use this LOV. If you leave "Validate from List" set to Yes, you will see an LOV that has no columns.
Each date field within a form needs to have the following code:
Trigger: KEY-LISTVAL:
calendar.show([first_date]);
By default, the Calendar shows the month of the value in the date field (if a value exists) upon first opening. If no specific date is supplied, the Calendar shows the current month.
Do not pass the current field into CALENDAR.SHOW as a parameter, as this forces validation of the field. The current field is used as a default. Generally, the code in KEY-LISTVAL should be:
calendar.show;
Attention: Never pass the value of the current date field as the argument to CALENDAR.SHOW. Because the calendar actually disables all Oracle Forms validation momentarily, if the user has entered an invalid date then immediately invokes the calendar, a PL/SQL error occurs. SHOW automatically handles this case when no argument is passed to it.
The KEY-LISTVAL trigger must have Execution Hierarchy "Override," and should not fire in enter-query mode.
See: CALENDAR: Calendar Package.
The entire calendar can be run in a display-only mode, where it is used to show one or more dates as Selected, rather than allowing the user to select a particular date. For example, it can be used to show all dates on which an employee was absent.
In this mode, characteristics of the field the cursor is on are ignored. All the user can do is change the month and year shown, and press 'OK' to close the window (no value is ever written back to the form).
To invoke this mode, the following calls are required in addition to those listed above:
Trigger: KEY-LISTVAL:
calendar.setup('DISPLAY');
calendar.setup('TITLE', null, null,
'<translated text for window title>');
Additional CALENDAR.SETUP calls are required after these two calls to establish those dates that should be shown as selected.
You can incorporate optional features into your Calendar call. If you use any of the optional calls, they must be placed before the mandatory calendar.show call.
The following examples customize the Calendar to show or disable specific dates.
To disable weekends (where the weekend is defined as Saturday and Sunday):
calendar.setup('WEEKEND');
To disable specific date ranges where the dates are either hard-coded or references to other fields on the form:
calendar.setup(<30 char identifying name>, <low_date>, <high_date>);
This call can be repeated as many times as needed. A null LOW_DATE is treated as the beginning of time; a null HIGH_DATE is treated as the end of time.
To disable specific date ranges where the dates are contained in a table:
calendar.setup(<30 char identifying name>, null, null, <SQL>);
This call may be made only once per field, but may return multiple rows. A null LOW_DATE is treated as the beginning of time; a null HIGH_DATE is treated as the end of time. Use NVL in your SQL statement if this is not the desired behavior.
Restrictions from several tables can be performed by using UNION SQL statements. The selected columns must be aliased to LOW_DATE and HIGH_DATE.
Suggestion: Ordering on the LOW_DATE column may improve performance. Restricting the dates returned to a small range near the anticipated selected value also improves performance.
If you need to be able to activate the Calendar from a field that is not explicitly declared as a DATE or DATETIME field (such as a CHAR text item that serves multiple purposes depending on context), write the Calendar calls as normal. The Calendar acts as if invoked from a DATE field, and when the user selects a value the date is written back to the field in the format "DD-MON-YYYY."
Then user-named trigger CALENDAR_WROTE_DATE fires. Create that trigger at the item level, and add any code you need to process the value (typically you need to apply a mask to it).
In this example, you want to open the Calendar to show either the date currently displayed in the DATE item, or the current month if no date is displayed. Additionally, you want to disable weekends (Saturdays and Sundays).
Trigger: KEY-LISTVAL:
calendar.setup('WEEKEND');
calendar.show;
In a form with the field SHIP_BY_DATE, you want to open the Calendar and customize it to:
Disable all holidays defined in the ORG_HOLIDAYS table
Disable weekends
Show the month corresponding to the date in field "LINES.NEED_BY_DATE" when the Calendar is opened
The code to implement this is:
Trigger: KEY-LISTVAL:
calendar.setup('WEEKEND');
calendar.setup('Manufacturing Holidays', null, null,
'select action_date LOW_DATE,
action_date HIGH_DATE '||
'from org_holidays where
date_type = ''HOLIDAY''');
calendar.show(:lines.need_by_date);
In a form with a field NEED_BY_DATE, you want the Calendar to show the month corresponding to the date in the field LINES.CREATED_DATE + 30 days. You also want to disable all dates before and including: LINES.CREATED_DATE.
The code to implement this is:
Trigger: KEY-LISTVAL:
calendar.setup('After created date', null,
lines.created_date);
calendar.show(:lines.need_by_date + 30);
A form uses a button called "Holidays" to show all Manufacturing holidays. The current month displays initially, and the calendar finds the selected dates in the ORG_DATES table.
The code to implement this is:
Trigger: WHEN-BUTTON-PRESSED on HOLIDAYS:
calendar.setup('TITLE', null, null,
'<translated text for "Manufacturing Holidays">');
calendar.setup('Manufacturing Holidays', null, null,
'select action_date LOW_DATE, action_date HIGH_DATE '||
'from org_dates where date_type = ''HOLIDAY''');
calendar.show;