Customizing the HotJava Browser Interface

Read this page to learn how to customize the HotJava Browser to add your own company's look and feel, or to use the HotJava Browser as a user interface to your product.

Without programming, you can customize the HotJava Browser in the following ways:

- Using the user interface
- Modifying your "personal" properties file
- Modifying the "system" properties files
- Modifying the HotJava Browser's HTML Pages and Templates

For examples of HotJava Browser customization, please see Examples.

# HotJava Browser's User Interface

Using the Display Preferences page, you can change HotJava Browser's default Home page (where the Home button leads), where the navigation buttons, URLs, activity monitor, and message line appear, and the typeface and typeface size. You can also choose whether hypertext links are underlined, and whether the HotJava Browser's clock, HTML Errors button, and certain Places menu items are displayed.

To modify the HotJava Browser using the user interface, choose Edit->Preferences->Display.

Customizing the HotJava Browser using the user interface is described in the Display Preferences section of the User's Guide.

# Properties

HotJava establishes values for property settings by reading four files: one personal properties file, and three system properties files. HotJava system properties files contain properties for both the HotJava Browser and the HotJava HTML Component. The HotJava HTML Component is available with the HotJava Browser source code or as a separate product, but it is not available with the HotJava Browser binary product. Therefore, HotJava Browser binary users should ignore any HTML Component (or "Bean") properties.

The system properties files of interest to HotJava Browser customizers are:

- hjResourceBundle.properties, which contains properties used by people localizing the HotJava Browser for other languages, such as font properties and text strings displayed by the HotJava Browser.

- hotjava.properties, which contains properties that are common to both the HotJava HTML Component and the HotJava Browser.

- hotjavaBrowser.properties, which contains properties that are explicitly used for the HotJava Browser (and not the HotJava HTML Component). There is also a file called hotjavaBean.properties, which contains properties explicitly used for the HotJava HTML Component, but not the HotJava Browser. Because it does not contain HotJava Browser properties, this file is not listed here as a properties file of interest.

If a property is duplicated in hotjava.properties and hotjavaBrowser.properties, the value in hotjavaBrowser.properties overrides the one in hotjava.properties.

These system properties files control many aspects of the HotJava Browser interface, including:

- Browser window title, placement, size, and background color
- Content viewer configuration
- Dialog content
- Error and status messages
- Font usage
- HTML element appearance
- Internationalization features
- Menu bar and Menu item content
- Navigation button icons and actions
- Preference pages appearance
- Security features
- User interface applets
- Window content

You can make many significant changes to the HotJava Browser interface simply by modifying the personal or system properties files. Personal property settings take precedence over system property settings. Usually only a system administrator or person with system-wide responsibility can modify the system properties files.

Note: Changes made to the system properties files affect all client users of the HotJava Browser within a given installation. Changes to a personal properties file are on a per-user basis.

Modifying properties for desired effects is shown in the Examples.

Occasionally, there will be a property that HotJava recognizes that doesn't appear in any of the properties files by default. One such property is `hotjava.date.format`, which can be added to your properties file and then modified to customize the format of the optional HotJava Browser clock. For information, see Date Format for the HotJava Browser Clock.

## Personal `properties` File

Edit your personal properties file to customize the HotJava Browser for your HotJava Browser sessions. Changes made to this file do not affect other users running the HotJava Browser from the same installation. Values of properties found in this file override values of the same properties in any of the system properties files.

On Solaris systems, when HotJava initializes, it checks for personal property definitions by reading:

    	your-home-directory/.hotjava/properties

On Windows NT and Windows 95 systems, if the environment variable HOME, HOMEDRIVE, or HOMEPATH is set, your personal properties file will be in:

    	your-home-directory\.hotjava\properties

On Windows NT and Windows 95 systems without home directories, your personal properties file will be in:

    	hotjava-install-directory\.hotjava\properties

The following is an example of a personal properties file:

    #Wed Mar 19 13:39:52 PST 1997
    https.proxyPort=80
    hotjava.locator.position=top
    hotjava.docfont=SansSerif
    hotjava.activitymonitor.position=bottom
    hotlistframe.width=300
    ftpProxySet=true
    hotjava.messageline.position=top
    anchorStyle=true
    hotlistframe.height=606
    gopherProxySet=true
    www.home=doc:/lib/hotjava/whats-hot.html
    hotjava.charset=8859_1
    gopherProxyHost=
    hotjava.docfontsize=-1
    hotjava.errors.on.toolbar=true
    awt.print.paperSize=letter
    hotlistframe.y=85
    hotjava.version=1.361, 03/18/97
    hotlistframe.x=9
    ftpProxyHost=
    hotjava.gohome=true
    hotjava.default.toolbar.buttonorder=\
    back|forward|home|reload|stop|addgoto|showfinddialog|print|hotlistframe|errors
    gopherProxyPort=80
    http.proxyHost=
    hotjava.default.toolbar.position=top
    https.proxyHost=
    ftpProxyPort=80
    http.proxyPort=80
    hotjava.clock=off

Note: HotJava both reads and writes properties in your personal properties file. When HotJava writes to the personal properties file, it reorders the items in the file for better performance. HotJava also removes any comment lines. Don't bother trying to arrange or format your personal properties file.

Note: You should edit your personal properties file only when the HotJava Browser is not running. Otherwise, your edits will be lost when you quit the current Browser session.

## System `properties` Files

HotJava also checks for property definitions by reading the system defaults from:

    	hotjava-install-directory/lib/hjResourceBundle.properties
    	hotjava-install-directory/lib/hotjava.properties
    	hotjava-install-directory/lib/hotjavaBrowser.properties

on Solaris systems, or:

    	\lib\hjResourceBundle.properties
    	\lib\hotjava.properties
    	\lib\hotjavaBrowser.properties

or:

    	hotjava-install-dir\lib\hjResourceBundle.properties
    	hotjava-install-dir\lib\hotjava.properties
    	hotjava-install-dir\lib\hotjavaBrowser.properties

on Windows systems.

Values found in your personal properties file override the same values found in any of the system files.

While viewing the system hotjava.properties, hotjavaBrowser.properties, and hjResourceBundle.properties files in the HotJava Browser, you can use Find in Document on the Edit menu to search for a particular property or category. (If your HotJava Browser displays the Unknown Viewer Application page when you follow the links above to the system properties files, click the View in HotJava button at the bottom of that page to see the files.)

When you want to customize the HotJava Browser, you should normally make changes in your personal properties file. Any changes you make to the system files (assuming you have permissions to make them) affect all other users of the browser in your installation. Furthermore, you should remember that every time you install a new version of the HotJava Browser, it comes with new versions of the system properties files, so you'll need to take extra steps at that point to merge your old changes into the new files. (You will not need to merge or re-enter changes made to your personal properties file when a new version of the browser is installed.)

# HTML Pages and Templates

To localize the HotJava Browser, you will want to modify HotJava's HTML Pages and Templates.

## Pages

The following HTML pages are displayed when you choose certain menu items. If you want to add your own pages to the HotJava Browser, you can, by modifying the properties file to add menu items, then connecting those menu items to your new pages. You could also change the existing pages to complement your own look and feel. These pages are found in hotjava-install-dir`/lib/hotjava` (Solaris) or hotjava-install-dir`\lib\hotjava` (Windows).

Note: Pages with "preferences-ssl" in their titles may not be available if you're using a version of the HotJava Browser that does not support the SSL feature.

about.html
blank.html
comments.html
copyright-splash.html
feature-list.html
getstart.html
gs-hotlist.html
gs-nav.html
gs-openurl.html
gs-pref.html
mailbug.html
memory.html
preferences-advsecurity.html
preferences-advsecurity1.html
preferences-advsecurity2.html
preferences-content-types.html
preferences-content-types1.html
preferences-content-types2.html
preferences-hotjava.html
preferences-hotjava1.html
preferences-hotjava2.html
preferences-mail.html
preferences-proxies.html
preferences-proxies1.html
preferences-proxies2-nossl.html
preferences-proxies2.html
preferences-security.html
preferences-security1.html
preferences-security2.html
preferences-ssl.html
preferences-ssl1.html
preferences-ssl2.html
progress.html
release.html
system.state.html
threads.html
whats-hot.html

## Templates

The following HTML and text pages accept variable values (mostly URLs) and display when certain conditions occur. If you customize the HotJava Browser to add your own functionality you could also add your own HTML or text template pages to hotjava-install-dir`/lib/templates` (Solaris) or hotjava-install-dir`\lib\templates` (Windows).

app-launch-error.html
charencode.directive.error.html
charencode.error.html
connecting.html
load.error.html
load.outofmemory.html
load.stop.html
maildoc-msg-notoaddr.html
maildoc-msg-sent.html
mailto.html
netaccess-msg-host.txt
netaccess-msg-none.txt
netaccess-msg-unrestricted.txt
open.error.html
open.forbidden.html
open.stop.html
prefs-error-badcachename.html
prefs-error-badcacheport.html
prefs-error-badfirewallname.html
prefs-error-badfirewallport.html
prefs-error-badftpname.html
prefs-error-badftpport.html
prefs-error-badgophername.html
prefs-error-badgopherport.html
prefs-error-badhttpsproxyname.html
prefs-error-badhttpsproxyport.html
prefs-error-badnoproxy-host.html
prefs-error-badsmtpname.html
prefs-error-badsockshost.html
prefs-error-badsocksport.html
prefs-error-direrror.html
prefs-error-saveerror.html
save.to.file.html
socks.open.html
unknown.file.html
unknown.host.html
unknown.link.html
unknown.protocol.html
unknown.url.html
unreachable.host.html
viewer.audio.html
viewer.image.html
viewer.started.html
viewer.unknown.html

# Examples of HotJava Browser Customization

Choose a couple of these examples for a step-by-step tutorial on how to modify properties to customize your browser.

## Simple Examples

- Add or Change Keyboard Accelerators for Menu Items
- Remove Proxies from the User Interface
- Change Title, Size, and Color of Window
- Replace "Home" Button Image with New Image
- Add a Button to the Navigation Bar

## To Add or Change Keyboard Accelerators for Menu Items

Many HotJava Browser menu items have keyboard accelerators associated with them. You can easily change these accelerators, or specify new ones. This example shows how to add the accelerator Control-w, for Clone Window.

Properties involved:

- filemenu

Procedure:

1. Quit the HotJava Browser, if it is running.

2. Edit your personal properties file using your favorite text editor.

3. Open the system hjResourceBundle.properties file hotjava-install-directory`/lib/hjResourceBundle.properties` (Solaris) or hotjava-install-directory`\lib\hjResourceBundle.properties` (Windows) in an editor in read-only mode.

4. Copy the lines for `prefssubmenu` from the system hjResourceBundle.properties file:

       filemenu=File\
               |clonewin=Clone Window		\
               |-				\
               |~o~openfile=Open...		\
       	|-				\
       	|savefile=Save...		\
       	|~p~print=Print...		\
       	|go mailto:=Send Mail...	\
       	|-				\
       	|closewin=Close			\
       	|~Q~quit=Quit

   and paste them into your personal properties file.

   The filemenu property shows the items on the File menu, each indicated by an action-label pair (e.g. openfile=Open...). A character surrounded by two tilde (~) characters at the beginning of a menu item is that item's keyboard accelerator. If it's a lower-case letter, the accelerator will be displayed in the menu as Ctrl+X (where "X" is the accelerator key). If it's an upper-case letter, the accelerator will be displayed in the menu as Ctrl+Shift+X. For example, display the HotJava Browser File menu to see that Ctrl+O is listed as the accelerator for Open, and Ctrl+Shift+Q is the accelerator for Quit.

5. To make Control-w the accelerator for Clone Window, change the Clone Window line from:

               |clonewin=Clone Window		\

   to:

               |~w~clonewin=Clone Window	\

6. Save your personal properties file.

7. Restart the HotJava Browser.
   Choose File->Clone Window, and you'll notice that the Ctrl+W is listed as the accelerator for this item. Type Control-w in the browser display window to start up a new HotJava Browser window displaying the current page.

## To Remove Proxies from the User Interface

You may want to remove an option from the user interface to allow for centralized administration of certain features, for example, to restrict users to one proxy setting.

Properties involved:

- prefssubmenu

Procedure:

1. Quit the HotJava Browser, if it is running.

2. Edit your personal properties file using your favorite text editor. (In this example, you may prefer to edit the system hjResourceBundle.properties file directly in order to affect a group of users.)

3. Open the system hjResourceBundle.properties file hotjava-install-directory`/lib/hjResourceBundle.properties` (Solaris) or hotjava-install-directory`\lib\hjResourceBundle.properties` (Windows) in an editor in read-only mode.

4. Copy the lines for `prefssubmenu` from the system hjResourceBundle.properties file:

       prefssubmenu=Preferences\
               |go doc:/lib/hotjava/preferences-hotjava.html=Display...        \
               |go doc:/lib/hotjava/preferences-proxies.html=Proxies...        \
               |go doc:/lib/hotjava/preferences-content-types.html=Viewer Applications...\
               |go doc:/lib/hotjava/preferences-mail.html=Mail...              \
               |go doc:/lib/hotjava/preferences-ssl.html=SSL and Certificate settings...\
               |go doc:/lib/hotjava/preferences-security.html=Applet Security... \

   and paste them into your personal properties file.

5. Delete the line with Proxies in it so you now have:

       prefssubmenu=Preferences\
               |go doc:/lib/hotjava/preferences-hotjava.html=Display...        \
               |go doc:/lib/hotjava/preferences-content-types.html=Viewer Applications...\
               |go doc:/lib/hotjava/preferences-mail.html=Mail...              \
               |go doc:/lib/hotjava/preferences-ssl.html=SSL and Certificate settings...\
               |go doc:/lib/hotjava/preferences-security.html=Applet Security... \

6. Save your personal properties file.

7. Restart the HotJava Browser.
   Choose Edit->Preferences and you'll notice that Proxies is no longer on the Preferences submenu.

Note: The SSL and Certificate settings are not available in versions of the HotJava Browser that do not support SSL.

## To Change the Title, Size, and Colors of the HotJava Browser Window

HotJava Browser's default title is HotJava(tm) and default size is 710 pixels wide by 730 pixels high. The title appears in the top window border. HotJava Browser's default colors are light gray for window backgrounds and an almost white color for the default page background color.

Properties involved:

- hotjava.title
- hotjava.width
- hotjava.height
- hotjava.docbgcolor
- hotjava.background

Procedure:

1. Quit the HotJava Browser, if it is running.

2. Edit your personal properties file using your favorite text editor. Move the insertion point to the end of the file.

3. Add a line for `hotjava.title`, such as the following:

       hotjava.title=The Wackiest Intranet on the Planet

4. Add lines for `hotjava.width` and `hotjava.height` to increase the window size:

       hotjava.width=1100
       hotjava.height=850

   Or to decrease the window size:

       hotjava.width=500
       hotjava.height=500

5. Add lines for `hotjava.docbgcolor`, the background color for the section of the browser window that displays information, and `hotjava.background`, the background color for the section of the browser window containing the controls and monitors.

       hotjava.background=0x893bff
       hotjava.docbgcolor=0xe3e4fa

   produces a purple window with lavender document background, or

       hotjava.background=0xc57726
       hotjava.docbgcolor=0xfffedc

   for a dark orange window with pale yellow document background.

   Note: Some Web pages explicitly set colors for the document background using the body tag (`<body bgcolor=#ffffff>` for a white background, for example). The hotjava.docbgcolor setting won't override the page's setting, but takes effect on pages that don't explicitly set the background color.

6. Save your personal properties file.

7. Restart the HotJava Browser.
   You'll notice when HotJava restarts that the title, size, and colors that you specified have changed.

The color changes don't affect the window manager-controlled elements like the window borders and resize corners.

## To Replace "Home" Button Image with New Image and Change Home Link

The HotJava Browser's "Home" button should not be confused with your personal "home" web page. HotJava's Home button displays the HotJava Browser's home page or can be used to navigate to an often-used Web location. By default, the HotJava Browser's home page is What's Hot.

To change the way the "Home" button looks, you'll need to create two images (one for the button in the "up" position and one for the button in the pushed position) and change some properties to point to your new images. HotJava's "home" icon, the little blue house, is in an image directory (folder) accessible within the HotJava Browser by the URL:

    doc:/lib/images/home.gif

You'll also need the image of the button pushed in, which by default is:

    doc:/lib/images/homeP.gif

Properties involved:

- button.home.up
- button.home.down
- button.home.height
- button.home.width

Procedure:

1. Create or find two images for the "Home" button--one for the up position (button not pushed) and one for the pushed position (button pushed down).

2. Place these images into a folder in your file system.

3. Quit the HotJava Browser, if it is running.

4. Add the following lines to your personal properties file:
   - button.home.up=file:/path-to-your-image.gif
   - button.home.down=file:/path-to-your-image-pushed.gif
   - button.home.height=height-of-your-image-in-pixels
   - button.home.width=width-of-your-image-in-pixels

5. Save your properties file.

6. Restart the HotJava Browser.

For example, you could edit your personal properties file to add the following lines. (Note that the doc protocol is used here instead of the file protocol to pick up example images that ship with your HotJava Browser installation. If you create your own images and put them in your own directory, use the file protocol to specify their location.)

    	button.home.up=doc:/UsersGuide/customimages/venus.gif
    	button.home.down=doc:/UsersGuide/customimages/venusP.gif
    	button.home.height=27
    	button.home.width=41

Then save your properties file and restart HotJava.
If you use the venus images in the example above, you should see in the navigation bar instead of the usual blue house.

To cause the new image to display a page other than HotJava's default home page:

1. Choose Edit->Preferences->Display.

2. Click in the Home Page text field.

3. Edit the Show Home Page URL (for example, you might change it to http://www.deepspace.ucsb.edu/ia/nineplanets/nineplanets.html).

4. Click Apply.

Click on your new Home Page button to display the desired page. Each time you restart the HotJava Browser, this new page will display either first or after Blank Page at Startup (if you chose that option on the Display Preferences page).

As you can see, it would also be easy to keep the blue house image and change the button behavior to navigate to your personal home page.

## To Add a Button to the Navigation Bar

You may want to add a button to the navigation bar to duplicate one of the menu items. In this example, we'll create a button that opens the Remembered Places (bookmarks) window, and use a heart icon to represent Remembered Places.

Properties involved:

- button.name.up
- button.name.down
- button.name.disabled
- button.name.width
- button.name.height
- button.name.message
- hotjava.default.toolbar.buttonorder

You're going to fill in name later.

Procedure:

1. Use a graphics editor to create three button images for the new button's up, down, and disabled states.

   Note: For this example, you don't need a disabled state image. But if you ever do, for the disabled state, created a "faded" version of your image, in a lighter shade of the color used for the button in the up state.

   > An example button in the "up" state:
   > An example button in the "down" ("pushed") state:
   > An example button in the "disabled" state:

2. Quit the HotJava Browser, if it is running.

3. Open the system hotjavaBrowser.properties file hotjava-install-directory`/lib/hotjavaBrowser.properties` (Solaris) or hotjava-install-directory`\lib\hotjavaBrowser.properties` (Windows) in an editor in read-only mode.

4. Search for "Navigation Buttons" and note that the buttons have names like print, showfinddialog, reload, home, stop, etc.

5. Copy the following lines from the system hotjavaBrowser.properties file to your personal properties file:

       button.back.up=back.gif
       button.back.down=backP.gif
       button.back.disabled=backD.gif
       button.back.width=41
       button.back.height=27
       button.back.message=Previous Page
       hotjava.default.toolbar.buttonorder=\
       back|forward|home|reload|stop|addgoto|showfinddialog|print

6. In your personal properties file, edit the newly added lines to read:

       button.hotlistframe.up=doc:/UsersGuide/customimages/heart.gif
       button.hotlistframe.down=doc:/UsersGuide/customimages/heartP.gif
       button.hotlistframe.disabled=doc:/UsersGuide/customimages/heartD.gif
       button.hotlistframe.width=41
       button.hotlistframe.height=27
       button.hotlistframe.message=Show Remembered Places
       hotjava.default.toolbar.buttonorder=\
       back|forward|home|reload|stop|addgoto|showfinddialog|print|hotlistframe

   We are using "hotlistframe" for the button name because that is the name of the action the HotJava Browser performs when you choose Show Remembered Places from the Places menu to display the Remembered Places (bookmarks) window. To see this, open the system hjResourceBundle.properties file and search for "Show Remembered Places." Note that the "Show Remembered Places" menu item corresponds to the "hotlistframe" action.

7. Save your properties file.

8. Restart the HotJava Browser.

   Note that on the right edge of the toolbar there's a new button that opens the Remembered Places window. If your browser window isn't wide enough to display all the buttons in the toolbar, it will display the ones that fit, starting from the left. Widen your browser window if you suspect all the buttons aren't displayed.

Back to HotJava User's Guide Table of Contents

Back to HotJava Browser Troubleshooting (previous topic)

Continue to HotJava Browser Content and Protocol Handlers (next topic)