Oracle Forms Server 6i
HyperLink JavaBean

Author: Oracle Forms Product Management Team

Creation Date: 20-FEB-2000

Last Updated: 20-FEB-2000

Version: 1.0

Copyright (C) 2000 Oracle Corporation
All Rights Reserved

Change Record

Date Author Version Comments

20-FEB-2000 PM Team 1.0 initial creation

Overview

This HyperLink JavaBean provides an example of the way in which the UI capabilities of an Oracle Forms application can be extended through the use of client side UI code in the form of JavaBeans. The JavaBean and wrapper classes provide a new UI type which can be embedded within an Oracle Forms application that resembles and mimics a common Web browser style of HyperLink. The HyperLink can be can be programatically set to display a text label which is underlined in the standard Web browser manner. The HyperLink can be set to modify the colors displayed when the user moves the mouse over the link and when the user clicks the link. When the user clicks on the link, the HyperLink component will dispatch an event back to the running Forms application to indicate that the user had clicked on the link.

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 that can be used in an Oracle Forms application.

.\doc The Javadoc generated documentation from the JavaBean 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 (HyperLink.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. An example is shipped in the \forms directory

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

Using the HyperLink JavaBean

The fully qualified name for this JavaBean is oracle.forms.demos.HyperLinkWrapper (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 HyperLink JavaBean wrapper. You do not need to add the .class suffix. In this case, we specify to use the wrapper class since this class will acts as the glue between the Oracle Forms environment and the HyperLink JavaBean itself.

The BeanArea containing the HyperLink 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 HyperLink JavaBean at runtime when the Forms application is run.

In addition to the standard BeanArea properties that can be set on the BeanArea item, the HyperLink JavaBean also contains some additional properties that can be set to configure it for use as a HyperLink. These properties, such as the URL and the various colors for the different states indicate to the HyperLink how it should behave and display itself when it is used.

When the user clicks on the HyperLink, the wrapper class is notified since it has registered as an actionListener with the HyperLink JavaBean. The wrapper class then creates a CustomEvent 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 LINKEVENT type, with the associated information contained in the LINKEVENTDATA object.

The example Form that ships with this distribution demonstrates how to use the component in the Oracle Forms 6i world. Whilst the wrapper class is generic and should function in the Forms 6.0 worlkd, the Forms 6i implementation is much more efficient and cleaner and should be used where possible. Also note that this component has not been tested with Oracle Forms 6.0.

PL/SQL Property Parameter Type Usage

NORMALCOLOR not required default = FOREGROUND property This property is used to indicate to the HyperLink what color it should display the text and underline as when it has not been clicked nor when the mouse is currently over it.

The color that is being set should be the RGB String value of the color, prefixed with the # symbol. An example of this for the color white is: #FFFFFF

Forms 6i Usage

SET_CUSTOM_PROPERTY('hBean1',1,'NORMALCOLOR','#FFFFFF');

ncolor := GET_CUSTOM_PROPERTY('hBean1',1,'NORMALCOLOR');

ACTIVECOLOR not required default= FOREGROUND property This property is used to indicate to the HyperLink what color it should display the text and underline as when the user has the mouse over the component and it is 'active'.

The color that is being set should be the RGB String value of the color, prefixed with the # symbol. An example of this for the color white is: #FFFFFF

Forms 6i Usage

SET_CUSTOM_PROPERTY('hBean1',1,'ACTIVECOLOR','#FFFFFF');

ncolor := GET_CUSTOM_PROPERTY('hBean1',1,'ACTIVECOLOR');

VISITEDCOLOR not required

default = Purple This property sets the HyperLink to use the indicated color it should display for the text and underline when it has been clicked by the user or 'visited'. The default color is a Purple style of color (#840084)

The color that is being set should be the RGB String value of the color, prefixed with the # symbol. An example of this for the color white is: #FFFFFF

Forms 6i Usage

SET_CUSTOM_PROPERTY('hBean1',1,'VISITEDCOLOR','#FFFFFF');

ncolor := GET_CUSTOM_PROPERTY('hBean1',1,'VISITEDCOLOR');

LINKLABEL optional This property sets the label that should be displayed on the HyperLink. This is equivalent to the <href="....">label</a> label element in the preceding HTML tag.

Forms 6i Usage

SET_CUSTOM_PROPERTY('hBean1',1,'LINKLABEL','My Yahoo!');

linklabel := GET_CUSTOM_PROPERTY('hBean1',1,'LINKLABEL');

LINKURL optional This property sets the URL that should be associated with the HyperLink and is returned to the running Forms application via a CustomEvent when the user clicks on the HyperLink.

Forms 6i Usage

SET_CUSTOM_PROPERTY('hBean1',1,'LINKURL','http://my.yahoo.com');

linkurl := GET_CUSTOM_PROPERTY('hBean1',1,'LINKURL');

LINKEVENT optional The property is used by the HyperLinkWrapper class to indicate to the running Forms application that the HyperLink JavaBean has been clicked on.

Forms 6i Usage

declare
eventName varchar2(20) := :system.custom_item_event;
begin
if(eventName = 'LINKEVENT') then
message('the link was pressed');
end if;
end;

LINKEVENTDATA optional The property that is associated with the LINKEVENT event and which contains a reference to the data returned by the HyperLinkWrapper. Using this property it is possible to retrieve the event data and examine the URL that has been associated with the HyperLink JavaBean.

Forms 6i Usage

declare
eventName varchar2(20) := :system.custom_item_event;
eventValues ParamList;
eventValueType number;
url varchar2(255);
begin
eventValues := get_parameter_list(:system.custom_item_event_parameters);
if(eventName = 'LINKEVENT') then
get_parameter_attr(eventValues,'LINKEVENTDATA',eventValueType,url);
web.show_document(url,'_blank');
end if;
end;

Running the Sample

The sample form that ships with this distribution uses the HyperLink JavaBean. The sample form has no dependencies on a database. To run the sample form you must perform the following steps:

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 HyperLink.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 misc directory.
Launch your web browser and open the HTML page.
When the Oracle Forms application is running, set the properties you wish to see on the HyperLink in the textfields and press the button. If you press the button and don't set the properties, the HyperLink will default to settings for the Oracle Technet website. Move the mouse over the Oracle Technet! link. Note how the color changes when the mouse is moved over the link. When the Oracle Technet! link is clicked note how it changes color and also see that another browser window is invoked and should now point to the Oracle Technet website.

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

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

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

To compile the HyperLink 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 HyperLinkWrapper.java and HyperLink.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:	20-FEB-2000
Last Updated:	20-FEB-2000
Version:	1.0

Date	Author	Version	Comments
20-FEB-2000	PM Team	1.0	initial creation

Directory	Contents
.\src	The Java source files for the JavaBean and wrapper code.
.\classes	The compiled classes for the JavaBean and wrapper that can be used in an Oracle Forms application.
.\doc	The Javadoc generated documentation from the JavaBean 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
NORMALCOLOR	`not required default = FOREGROUND property`	This property is used to indicate to the HyperLink what color it should display the text and underline as when it has not been clicked nor when the mouse is currently over it. The color that is being set should be the RGB String value of the color, prefixed with the # symbol. An example of this for the color white is: #FFFFFF Forms 6i Usage SET_CUSTOM_PROPERTY('hBean1',1,'NORMALCOLOR','#FFFFFF'); ncolor := GET_CUSTOM_PROPERTY('hBean1',1,'NORMALCOLOR');
ACTIVECOLOR	`not required default= FOREGROUND property`	This property is used to indicate to the HyperLink what color it should display the text and underline as when the user has the mouse over the component and it is 'active'. The color that is being set should be the RGB String value of the color, prefixed with the # symbol. An example of this for the color white is: #FFFFFF Forms 6i Usage SET_CUSTOM_PROPERTY('hBean1',1,'ACTIVECOLOR','#FFFFFF'); ncolor := GET_CUSTOM_PROPERTY('hBean1',1,'ACTIVECOLOR');
VISITEDCOLOR	not required default = Purple	This property sets the HyperLink to use the indicated color it should display for the text and underline when it has been clicked by the user or 'visited'. The default color is a Purple style of color (#840084) The color that is being set should be the RGB String value of the color, prefixed with the # symbol. An example of this for the color white is: #FFFFFF Forms 6i Usage SET_CUSTOM_PROPERTY('hBean1',1,'VISITEDCOLOR','#FFFFFF'); ncolor := GET_CUSTOM_PROPERTY('hBean1',1,'VISITEDCOLOR');
LINKLABEL	optional	This property sets the label that should be displayed on the HyperLink. This is equivalent to the <href="....">label</a> label element in the preceding HTML tag. Forms 6i Usage SET_CUSTOM_PROPERTY('hBean1',1,'LINKLABEL','My Yahoo!'); linklabel := GET_CUSTOM_PROPERTY('hBean1',1,'LINKLABEL');
LINKURL	optional	This property sets the URL that should be associated with the HyperLink and is returned to the running Forms application via a CustomEvent when the user clicks on the HyperLink. Forms 6i Usage SET_CUSTOM_PROPERTY('hBean1',1,'LINKURL','http://my.yahoo.com'); linkurl := GET_CUSTOM_PROPERTY('hBean1',1,'LINKURL');
LINKEVENT	optional	The property is used by the HyperLinkWrapper class to indicate to the running Forms application that the HyperLink JavaBean has been clicked on. Forms 6i Usage declare eventName varchar2(20) := :system.custom_item_event; begin if(eventName = 'LINKEVENT') then message('the link was pressed'); end if; end;
LINKEVENTDATA	optional	The property that is associated with the LINKEVENT event and which contains a reference to the data returned by the HyperLinkWrapper. Using this property it is possible to retrieve the event data and examine the URL that has been associated with the HyperLink JavaBean. Forms 6i Usage declare eventName varchar2(20) := :system.custom_item_event; eventValues ParamList; eventValueType number; url varchar2(255); begin eventValues := get_parameter_list(:system.custom_item_event_parameters); if(eventName = 'LINKEVENT') then get_parameter_attr(eventValues,'LINKEVENTDATA',eventValueType,url); web.show_document(url,'_blank'); end if; end;

Java Source File	Notes
HyperLink.java	The source file for the JavaBean itself. This JavaBean can be used in any Java application by itself.
HyperLinkWrapper.java	The source file for the wrapper class that handles the interaction between the Forms environment and the HyperLink 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.

Oracle Forms Server 6i HyperLink JavaBean