Oracle Forms Server 6i

CalendarWidget JavaBean

Author: Oracle Forms Product Management Team

Creation Date: 10-FEB-1999

Last Updated: 20-FEB-2000

Version: 1.0

Copyright (C) 2000 Oracle Corporation
All Rights Reserved

Change Record

Date Author Version Comments

10-FEB-1999 PM Team 0.5 initial creation

20-FEB-2000 PM Team 1.0 modified to use 6i

Overview

This CalendarWidget JavaBean provides an example of an extension component that can be embedded and used within a Forms application. The CalendarWidget is a JavaBean that displays a push button with a settable label. When the user clicks on the button, a separate frame with a calendar layout is displayed. The calendar frame allows a user to select a date of their choice by clicking on one of the shown dates. The year and month can be chosen by the user and the days displayed will be automatically changed to relfect the chosen month and year. The CalendarWidget JavaBean can be used as a standalone JavaBean.

When the user selects a date, a custom event will be sent to the hosting Forms application to indicate that the user has selected a date. Associated with the custom event will be data that indicates what date was selected by the end user.

The Distribution

This distribution contains the following directories:

Directory Contents

.\src The Java source files for the JavaBean and wrapper code.

.\classes The compiled classes for the JavaBean and wrapper code that can be used in an Oracle Forms application.

.\doc The Javadoc generated documentation from the JavaBean and wrapper source files. This documents the method and attributes used within the JavaBean and wrapper. Click here to view the documentation.

.\forms Contains example Forms which use the component and demonstrate how to work with the JavaBean from the Forms environment.

Deployment

You should perform the follwing steps to install and configure the JavaBean for development and deployment in an Oracle Forms Server application:

Copy the entire oracle directory and its subdirectories from the classes directory to the <ORACLE_HOME>\orant\forms60\java directory. This will place the class files for the JavaBean in the location where the Oracle Form Builder can locate them at development time.
Place the JavaBean JAR file (CalendarWidget.jar) in the codebase directory being used to deploy Oracle Forms Server 6i applications. This will allow the client machine to download the class files for use at runtime.
Modify the HTML page being used to launch the Oracle Forms application to reference the JAR file in the ARCHIVE tag. This should be in addition to the standard Oracle Forms Server JAR Files and notifies the client JVM which archive files it must download before starting the application.

        <ARCHIVE = "f60all.jar, CalendarWidget.jar">

Using the CalendarWidget JavaBean

The fully qualified name for this JavaBean is oracle.forms.demos.CalendarWidgetWrapper (note that Java is case sensitive).

This JavaBean must be added to a Form application using the BeanArea item. Place the BeanArea item on a canvas and then set the implementation class property to be the fully qualified name of the CalendarWidget JavaBean wrapper. You do not need to add the .class suffix.

The BeanArea containing the CalendarWidget JavaBean must be set to visible in your application otherwise it will not be initialized and therefore will not work. Note that you can set all of the properties of the BeanArea such as the Background, Foreground, Font, FontSize, etc. and these will be reflected by the CalendarWidget JavaBean at runtime when the Forms application is run.

When the user clicks on the actual calendar that is created and displated by the CalendarWidget JavaBean, a CustomEvent is created and dispatches this back to the running Forms application. The Forms application will then raise the WHEN-CUSTOM-ITEM-EVENT trigger on the BeanArea item as an event of DateChange type, with the associated information contained in the corresponding DateValue object.

The example Form that ships with this distribution demonstrates how to use the component in an Oracle Forms Server 6i environment. This JavaBean has not been tested with an Oracle Forms Server 6.0 environment.

SETDATE;
DATECHANGE;
DATEVALUE;
BUTTONLABEL;
FOREGROUND;
BACKGROUND;
OUTERSIZE;

PL/SQL Property Parameter Type Usage

SETDATE Required String format : "Mon DD, YYYY" This custom Forms property is used to set the date that the Calendar should display when it becomes activated. The date should be passed in as a string in the format of "Mon DD, YYYY".

Forms 6i Usage

SET_CUSTOM_PROPERTY('hBean',1,'SetDate',to_char(:date,'Mon DD, YYYY'));

BUTTONLABEL Optional String This custom Forms property is used to set the label on the button that is displayed for the component.

Forms 6i Usage

SET_CUSTOM_PROPERTY('hBean',1,'BUTTONLABEL','Press Me');

FOREGROUND Automatically set by the Forms Runtime accoring to the Foreground property associated with the BeanArea item This standard Forms property is used to indicate to the CalendarWidget wrapper what foreground color it should tell the JavaBean to use. This property is obtained from the foreground property set on the BeanArea item in the Form Builder. This allows the Form Builder to be used to set the foreground color property of the JavaBean at design time. Note that any changes made to this property in the Property Palette will not be displayed at design time but will be used at runtime.

BACKGROUND Automatically set by the Forms Runtime accoring to the Background property associated with the BeanArea item This standard Forms property is used to indicate to the CalendarWidget wrapper what background color it should tell the JavaBean to use. This property is obtained from the background property set on the BeanArea item in the Form Builder. This allows the Form Builder to be used to set the background color property of the JavaBean. Note that any changes made to this property in the Property Palette will not be displayed at design time but will be used at runtime.

OUTERSIZE Automatically set by the Forms Runtime accoring to the Foreground property associated with the BeanArea item This standard Forms property is used to indicate to the CalendarWidget wrapper what size it should tell the JavaBean to be. This property is obtained from the phyiscal size properties set on the BeanArea item in the Form Builder. This allows the Form Builder and Layout Editor to be used to set the actual size of the JavaBean at design time.

DATECHANGE String This custom property is always associated with the custom event that is created by the CalendarWidget wrapper. The WHEN-CUSTOM-ITEM-EVENT trigger associated with the BeanArea item that contains the CalendarWidget can check to see if the eventname is equal to this custom property. If it is then the event that has occured has been dispatched by the CalendarWidget.

declare hBeanEventDetails ParamList;
eventName varchar2(80);
paramType number;
eventType varchar2(80);
begin
hBeanEventDetails := get_parameter_list(:system.custom_item_event_parameters);
eventName := :system.custom_item_event;
if(eventName = 'DateChange') then
..

DATEVALUE String

Format : "Mon DD, YYYY" This custom property is always associated with the custom event that is created by the CalendarWidget. In particular, this custom property contains the value of the date selected by the user through the CalendarWidget. The 'DateValue' property name can be used to extract the property value from the custom event parameter list. The code listing below shows the details of a function which responds to a date change event dispatched by the CalendarWidget and extracts the date information that has been provided by the user.

function customEvent return date as
hBeanEventDetails ParamList;
eventName varchar2(80);
paramType number;
eventType varchar2(80);
newDateVal varchar2(80);
newDate date := null;
begin
hBeanEventDetails := get_parameter_list(:system.custom_item_event_parameters);
eventName := :system.custom_item_event;
if(eventName = 'DateChange') then
get_parameter_attr(hBeanEventDetails, 'DateValue', ParamType, newDateVal);
newDate := to_date(newDateVal,'Month DD, YYYY');
else
message('Uknown event received - ' || eventName);
end if;
return newDate;
end;

Running the Sample

The sample form that ships with this distribution uses the CalendarWidget JavaBean. The sample form has a dependancy on the EMP table that ships as an example with the standard SQL*Plus distribution. To run the sample form you must perform the following steps:

Ensure that you have access to a database schema which has the EMP table installed.
Place the sample form into a directory that is referenced in by the FORMS60_PATH setting
Create a HTML page to launch the an the Oracle Forms application using the appropriate tag sets for the deployment vehicle you are using. The HTML file must specify the CalendarWidget.jar file in the ARCHIVE tag. Place the HTML page in a directory which is accessible from a web browser. There is an example HTML page in the forms directory. Make sure the connection string referenced in the HTML page uses the connect string for the database instance you are going to use.
Launch your web browser and open the HTML page.
When the Oracle Forms application is running, click on the query button and note how the button in the Form has a label that represents the current hiredate of the employee. Click on the button and you will see that a calendar frame pops up. Select a date by clicking on the date of your choice. Change the year and month settings. Press the commit button and note that the record is updated in the database.
Open the supplied Form in the Form Builder and set some of the properties such as the background and foreground color of the BeanArea item. Change the size of the BeanArea item in the layout editor. Compile, regenerate and re-run the form and note the changes that have taken place.

Building the Java Classes

This distrubution contains the Java source code for the JavaBean so you can make any changes you wish to the way the component works for your applications.

Java Source File Notes

CalendarWidget.java The source file for the JavaBean itself. This JavaBean can be used in any Java application by itself.

CalendarWidgetWrapper.java The source file for the wrapper class that handles the interaction between the Forms environment and the CalendarWidget JavaBean.

To compile the CalendarWidget JavaBean and wrapper classes you will need to have the following software components installed and configured on your computer :

Oracle Forms 6i
JavaSoft JDK 1.1.7B (or later but not 1.2)

A batch script (for Windows NT) has been provided in the src directory that will compile the CalendarWidgetWrapper.java and CalendarWidget.java source files into the classes directory. This batch file also recreates the JAR file using the newly compiled classes and regenerates the Javadoc documentation. A pre-compiled JAR file has been shipped in the classes directory to use without requiring the build process.

To run the batch file the following environment variables must be set:

Environment Variable Notes

ORACLE_HOME Specifies the location of the Oracle software installation. In the case where more than one Oracle home exists, it should specify the location where Oracle Forms Server is installed.

JDK_HOME Specifies the location where a Java Development Kit is installed. This should point to the top level directory only.

Dependencies

This PJC has been tested with the following software components:

Oracle Forms Server 6.0.8.7.1 / NT Server
Windows NT with JInitiator 1.1.7.26.1/ Client machine
Windows NT with IE 5.0 / Client machine
Sun Solaris 2.5.1 with JavaSoft JDK 1.1.7B / Client machine

Author:	Oracle Forms Product Management Team
Creation Date:	10-FEB-1999
Last Updated:	20-FEB-2000
Version:	1.0

Date	Author	Version	Comments
10-FEB-1999	PM Team	0.5	initial creation
20-FEB-2000	PM Team	1.0	modified to use 6i

Directory	Contents
.\src	The Java source files for the JavaBean and wrapper code.
.\classes	The compiled classes for the JavaBean and wrapper code that can be used in an Oracle Forms application.
.\doc	The Javadoc generated documentation from the JavaBean and wrapper source files. This documents the method and attributes used within the JavaBean and wrapper. Click here to view the documentation.
.\forms	Contains example Forms which use the component and demonstrate how to work with the JavaBean from the Forms environment.

PL/SQL Property	Parameter Type	Usage
SETDATE	`Required String format : "Mon DD, YYYY"`	This custom Forms property is used to set the date that the Calendar should display when it becomes activated. The date should be passed in as a string in the format of "Mon DD, YYYY". Forms 6i Usage SET_CUSTOM_PROPERTY('hBean',1,'SetDate',to_char(:date,'Mon DD, YYYY'));
BUTTONLABEL	`Optional String`	This custom Forms property is used to set the label on the button that is displayed for the component. Forms 6i Usage SET_CUSTOM_PROPERTY('hBean',1,'BUTTONLABEL','Press Me');
FOREGROUND	`Automatically set by the Forms Runtime accoring to the Foreground property associated with the BeanArea item`	This standard Forms property is used to indicate to the CalendarWidget wrapper what foreground color it should tell the JavaBean to use. This property is obtained from the foreground property set on the BeanArea item in the Form Builder. This allows the Form Builder to be used to set the foreground color property of the JavaBean at design time. Note that any changes made to this property in the Property Palette will not be displayed at design time but will be used at runtime.
BACKGROUND	`Automatically set by the Forms Runtime accoring to the Background property associated with the BeanArea item`	This standard Forms property is used to indicate to the CalendarWidget wrapper what background color it should tell the JavaBean to use. This property is obtained from the background property set on the BeanArea item in the Form Builder. This allows the Form Builder to be used to set the background color property of the JavaBean. Note that any changes made to this property in the Property Palette will not be displayed at design time but will be used at runtime.
OUTERSIZE	`Automatically set by the Forms Runtime accoring to the Foreground property associated with the BeanArea item`	This standard Forms property is used to indicate to the CalendarWidget wrapper what size it should tell the JavaBean to be. This property is obtained from the phyiscal size properties set on the BeanArea item in the Form Builder. This allows the Form Builder and Layout Editor to be used to set the actual size of the JavaBean at design time.
DATECHANGE	`String`	This custom property is always associated with the custom event that is created by the CalendarWidget wrapper. The WHEN-CUSTOM-ITEM-EVENT trigger associated with the BeanArea item that contains the CalendarWidget can check to see if the eventname is equal to this custom property. If it is then the event that has occured has been dispatched by the CalendarWidget. declare hBeanEventDetails ParamList; eventName varchar2(80); paramType number; eventType varchar2(80); begin hBeanEventDetails := get_parameter_list(:system.custom_item_event_parameters); eventName := :system.custom_item_event; if(eventName = 'DateChange') then ..
DATEVALUE	String Format : "Mon DD, YYYY"	This custom property is always associated with the custom event that is created by the CalendarWidget. In particular, this custom property contains the value of the date selected by the user through the CalendarWidget. The 'DateValue' property name can be used to extract the property value from the custom event parameter list. The code listing below shows the details of a function which responds to a date change event dispatched by the CalendarWidget and extracts the date information that has been provided by the user. function customEvent return date as hBeanEventDetails ParamList; eventName varchar2(80); paramType number; eventType varchar2(80); newDateVal varchar2(80); newDate date := null; begin hBeanEventDetails := get_parameter_list(:system.custom_item_event_parameters); eventName := :system.custom_item_event; if(eventName = 'DateChange') then get_parameter_attr(hBeanEventDetails, 'DateValue', ParamType, newDateVal); newDate := to_date(newDateVal,'Month DD, YYYY'); else message('Uknown event received - ' \|\| eventName); end if; return newDate; end;

Java Source File	Notes
CalendarWidget.java	The source file for the JavaBean itself. This JavaBean can be used in any Java application by itself.
CalendarWidgetWrapper.java	The source file for the wrapper class that handles the interaction between the Forms environment and the CalendarWidget JavaBean.

Environment Variable	Notes
ORACLE_HOME	Specifies the location of the Oracle software installation. In the case where more than one Oracle home exists, it should specify the location where Oracle Forms Server is installed.
JDK_HOME	Specifies the location where a Java Development Kit is installed. This should point to the top level directory only.