Skip Headers

Oracle® Application Server Forms Services Deployment Guide 10g Release 2 (10.1.2) B14032-03 |
| Library | Product | Contents | Index

Previous | Next |

# 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.