4.9 Deploying Icons and Images Used by Forms Services

This section explains how to specify the default location and search paths for icons and images in Registry.dat.

4.9.1 Managing Registry.dat with Application Server Control

Use Application Server Control to change, add, or delete parameters from Registry.dat.

To change a Registry.dat parameter value:

1. Select the Configuration page of Enterprise Manager.

2. From the View dropdown list, select Forms Font and Icon Mapping (Registry.dat).

3. Select a radio button next to a parameter and change the value(s) for it in the Value text field.

4. Click Apply.

   Your changes are saved.

To add a Registry.dat parameter and its value:

1. Select the Configuration page of Enterprise Manager.

2. From the View dropdown list, select Forms Font and Icon Mapping (Registry.dat).

3. At the bottom of the Registry.dat page, enter a name for the parameter in the Name text field.

4. Enter a value for this new parameter in the Value text field.

5. Click Add New Parameter.

   Your changes are saved.

To delete a Registry.dat parameter and its value:

1. Select the Configuration page of Enterprise Manager.

2. From the View dropdown list, select Forms Font and Icon Mapping (Registry.dat).

3. Select a radio button next to a parameter and click Delete.

4. The Confirmation page appears, click Yes.

5. The parameter is deleted and the Configuration page reappears.

4.9.2 Deploying Application Icons

When deploying an Oracle Forms application, the icon files used must be in a Web-enabled format, such as JPG or GIF (GIF is the default format).

By default, the icons are found relative to the DocumentBase directory. That is, DocumentBase looks for images in the directory relative to the base directory of the application start HTML file. As the start HTML file is dynamically rendered by the Forms Servlet, the forms directory becomes the document base.

For example, if an application defines the icon location for a button with myapp/<iconname>, then the icon is looked up in the directory forms/myapp.

To change the default location, set the imageBase parameter to codebase in the Forms Web Configuration page of Enterprise Manager Application Server Control Console. Alternatively, you can change the default.icons.iconpath value of the Registry.dat file in the forms/java/oracle/forms/registry directory.

Setting the imageBase parameter to codebase enables Oracle Forms to search the forms/java directory for the icon files. Use this setting if your images are stored in a Java archive file. Changing the image location in the Registry.dat configuration file is useful if you want to store images in a central location independent of any application and independent of the Oracle Forms installation.

4.9.2.1 Storing Icons in a Java Archive File

If an application uses a lot of custom icon images, it is recommended you store icons in a Java archive file and set the imageBase value to codebase. The icon files can be zipped to a Java archive via the Jar command of any Java Software Development Kit (Java SDK).

For example, the command jar -cvf myico.jar *.gif packages all files with the extension .gif into an archive file with the name myico.jar.

In order for Oracle Forms to access the icon files stored in this archive, the archive needs to be stored into the forms/java directory. Also, the name of the archive file must be part of the archive tag used in the custom application section of the formsweb.cfg file (for example, archive_jini=frmall_jinit.jar, myico.jar). Now, when the initial application starts, the icon files are downloaded to and permanently stored on the client until the archive file is changed.

Note: You do not need to deploy Oracle Forms default icons (for example, icons present in the default smart icon bar), as they are part of the frmall.jar file.

4.9.2.2 Adding Icon Changes to Registry.dat

If you want to add icon changes to the Registry.dat file used by your application, it is recommended that you make a copy of the existing Registry.dat file and edit the copied file.

To create a copy of the Registry.dat file: 

1. Copy the Registry.dat text file found in the ORACLE_HOME/forms/java/oracle/forms/registry directory to another directory. This directory must be mapped to a virtual directory for your Web server (for example, /appfile).

2. Rename this new file (for example, myapp.dat).

3. Modify the iconpath parameter specifying your icon location:

   default.icons.iconpath=/mydir or http://myhost.com/mydir 
   

   (for an absolute path)

   or

   default.icons.iconpath=mydir 
   

   (for a relative path, starting from the DocumentBase Directory)

4. Modify the iconextension parameter:

   default.icons.iconextension=gif
   

   or

   default.icons.iconextension=jpg
   

To reference the application file: 

• In a specific named configuration section in the formsweb.cfg file, modify the value of the serverApp parameter and set the value to the location and name of your application file.

  For example:

  [my_app]
  ServerApp=/appfile/myapp
  
  

  (for an absolute path)

  or

  [my_app]
  ServerApp=appfile/myapp
  
  

  (for a relative path, relative to the CodeBase directory)

  Table 4-12, "Icon Location Guide" describes the correct locations where to place your application icons:

Table 4-12 Icon Location Guide

Icon Location	When	How
DocumentBase	Default. Applications with few or no custom icons.	Store icons in forms directory or in a directory relative to forms.
Java Archives	Applications that use many custom icons	Set ImageBase to codebase, create Java archive file for icons, and add archive file to the archive parameter in formsweb.cfg.
Registry.dat	Applications with custom icons that are stored in a different location as the Oracle Forms install (can be another server). Useful if you need to make other changes to the Registry.dat file like font mapping.	Copy Registry.dat and change ServerApp parameter in formsweb.cfg.

4.9.3 SplashScreen and Background Images

When you deploy your applications, you have the ability to specify a splash screen image (displayed during the connection) and a background image file.

Those images are defined in the HTML file or you can use the Forms Web Configuration page in Enterprise Manager:

<PARAM NAME="splashScreen" VALUE="splash.gif">

<PARAM NAME="background" VALUE="back.gif">

The default location for the splash screen and background image files is in the DocumentBase directory containing the baseHTML file.

4.9.4 Custom Jar Files Containing Icons and Images

Each time you use an icon or an image (for a splash screen or background), an HTTP request is sent to the Web server. To reduce the HTTP round-trips between the client and the server, you have the ability to store your icons and images in a Java archive (Jar) file. Using this technique, only one HTTP round-trip is necessary to download the Jar file.

4.9.4.1 Creating a Jar File for Images

The Java SDK comes with an executable called jar. This utility enables you to store files inside a Java archive. For more information, see http://java.sun.com/.

For example:

jar -cvf myico.jar Splash.gif Back.gif icon1.gif

This command stores three files (Splash.gif, Back.gif, icon1.gif) in a single Jar file called myico.jar.

4.9.4.2 Using Files Within the Jar File

The default search path for the icons and images is relative to the DocumentBase. However, when you want to use a Jar file to store those files, the search path must be relative to the CodeBase directory, the directory which contains the Java applet.

If you want to use a Jar file to store icons and images, you must specify that the search path is relative to CodeBase using the imageBase parameter in the formsweb.cfg file or HTML file.

This parameter accepts two different values:

• DocumentBase The search path is relative to the DocumentBase directory. It is the default behavior.

• CodeBase The search path is relative to the CodeBase directory, which gives the ability to use Jar files.

In this example, we use a JAR file containing the icons and we specify that the search should be relative to CodeBase. If the parameter imageBase is not set, the search is relative to DocumentBase and the icons are not retrieved from the Jar file.

For example (formsweb.cfg):

archive=frmall.jar, icons.jar
imageBase=codebase

4.9.5 Search Path for Icons and Images

The icons and images search path depends on:

• What you specify in your custom application file (for the icons).

• What you specified in the splashScreen and background parameters of your default Forms Web configuration or HTML file (for the images).

• What you specify in the imageBase parameter in the Forms Web Configuration page of Application Server Control for the file or HTML file (for both icons and images).

Forms Services searches for the icons depending on what you specify. This example assumes:

• host is the computer name.

• DocumentBase is the URL pointing to the HTML file.

• CodeBase is the URL pointing to the location of the starting class file (as specified in the formsweb.cfg file or HTML file).

• mydir is the URL pointing to your icons or images directory.

4.9.5.1 DocumentBase

The default search paths for icons and images are relative to the DocumentBase. In this case, you do not need to specify the imageBase parameter:

Table 4-13 Search Paths for Icons

Location Specified	Search path used by Forms Services
default	http://host/documentbase
iconpath=mydir (specified in your application file)	http://host/documentbase/mydir (relative path)
iconpath=/mydir (specified in your application file)	http://host/mydir (absolute path)

Table 4-14 Search Paths for Images

Location Specified	Search path used by Forms Services
file.gif (specified, for example, in formsweb.cfg as splashscreen=file.cfg)	http://host/documentbase/file.gif
mydir/file.gif	http://host/documentbase/mydir/file.gif (relative path)
/mydir/file.gif	http://host/mydir/file.gif (absolute path)

4.9.5.2 CodeBase

Use the imageBase=CodeBase parameter to enable the search of the icons (Table 4-15) and images (Table 4-16) in a Jar file:

Table 4-15 Icon Search Paths Used by Forms Services

Location Specified	Search Path Used by Forms Services
default	http://host/codebase or root of the Jar file
iconpath=mydir (specified in your application file)	http://host/codebase/mydir or in the mydir directory in the Jar file (relative path)
iconpath=/mydir (specified in your application file)	http://host/mydir (absolute path) No Jar file is used

Table 4-16 Image Search Paths Used by Forms Services

Location Specified	Search Path Used by Forms Services
file.gif	http://host/codebase/file.gif or root of the Jar file
mydir/file.gif (specified in your HTML file)	http://host/codebase/mydir/file.gif or in the mydir directory in the Jar file (relative path)
/mydir/file.gif (specified in your HTML file)	http://host/mydir/file.gif (absolute path) No Jar file is used.