Catalog View Readme

Index

1. Disclaimer
2. License
3. Introduction
4. Installation
5. Configuration
6. Functions
7. Trouble shooting
8. Contact the Author

1. Disclaimer

The information contained in this publication is to the best of our knowledge reliable. Users should, however, conduct their own tests to determine the suitability of our products and recommendations for their own specific purposes. Statements contained herein should not be considered as a warranty of any kind, expressed or implied, and no liability is accepted for the infringement of any patents.

2. License

Catalog View is freeware. You may use and distribute Catalog View free of charge. You may not reverse engineer, decompile, or disassemble the SOFTWARE PRODUCT.

3. Introduction to Catalog View

Catalog View is a multiple purpose java database applet. It is easy for the user to browse and search in data records with Catalog View. If the data records contain images, online documents or addresses, the user can view the images, go to the documents or start the e-mail program (Not all browsers support this feature) with a single click in the data grid.

Catalog View does not require server side applications such as CGI scripts. Due to security restrictions applets cannot write to the server without communicating with a server side application. Therefore Catalog View can only be used to view data, it cannot update or edit data.

Applets are programs running within the web browser. This feature makes Catalog View a powerful user interface to your database which runs on all platforms across the internet or intranet. The browser contains a java virtual machine (JVM), which interprets the byte code in the applet's class files. Catalog View is using the java API version 1.0.2, which is the standard java API in most popular browsers. Catalog View has been tested with Netscape 3.0 and higher versions of Netscape on Windows 95, Windows 98 and Unix platforms, and it has been tested with Microsoft Internet Explorer 3.0 and higher versions Microsoft Internet Explorer. If you intend to run Catalog View at other platforms, We recommend that you conduct your own tests of Catalog View.

Catalog View starts up when the HTML document that contains the applet is loaded in the browser. When the applet's class files are loaded a clickable image button is displayed in the document. You decide which image should be used as image button. The data file is loaded in a background process (thread). If the user clicks the image button before the data file is completely loaded a progress bar pops up and displays the progress in loading the data. If the data is completely loaded when the user clicks the image button a data grid pops up. The applet can be configured to automatically show the data grid when the data is completely loaded. The applet can also be configured to display a password dialog before showing the data grid.

The pop up window contains a data grid and tool bars with buttons, drop down choice boxes and a list box. The functions are explained below. The layout of the data grid and most of the components in the tool bars can be configured to your requirements.

When the user navigates away from the document which contains Catalog View, the applet disposes most of its resources including the data. Only the small part of the applet which displays the image button is not disposed. The applet is disposed in order not to occupy the client's computer resources more than necessary. If the client decides to go back to the document that contains Catalog View applet, it will load much faster the second time, because the class files and the data are kept in the browser cache.

Catalog View has been tested with more than 10.000 records. The Sort and Search all functions begin to work slowly at approximately 1000 records. We recommend that you configure the applet to exclude the Sort choice if you have more than 1000 records. You should then keep the data in the preferred sort order in the data file. We recommend that you configure the applet to exclude the Search all button if you have more than 2000-3000 records. See how to exclude these functions in the configuration section. The indexed based search and filter functions are fast even with 10.000 records.

4. Installation

The easiest way to install Catalog View is to copy some of the example HTML documents that are included in the examples directory.

NOTE BEFORE YOU START TO INSTALL CATALOG VIEW:
when you change PARAMETER statements in the HTML code, the applet must reload before these changes will be effected. In Netscape applets can be reloaded by pressing the SHIFT key while clicking at the reload button. If you are not sure that the applet is reloaded exit all browser windows (also mail windows) and restart the browser.

Unzip the catalogview.zip file. The directory structure is:

./catview/index.html
./catview/readme.html
./catview/classes
./catview/classes/data
./catview/classes/images
./catview/examples
./catview/tools

Load the index.html in your browser. This document has links to some example HTML documents in the examples directory. Check that the examples can run on your local computer. Use one of the example HTML documents in the examples directory as a template for your own data file. The first line in the applet tag of a HTML document could for example look like

<applet code="catalogview.class" codebase="classes" archive="CatalogView.jar" width= "124" height="44">

catalogview.class is the main class file. Catalog View consists of catalogview.class and a number of other class files. The browser looks for the class files in the directory indicated by the codebase statement. In this example the browser searches for the class files in the directory "classes" relative to the HTML document containing the applet tag. The width and height indicate the size in pixels of the applet's canvas in the HTML document. Set the width and height to the same size as the image you want to use as clickable image button (see below for details). The ARCHIVE points to an compressed jar file that contains all the class files. Newer browers will load the compressed jar file. Older browsers will load the class files one by one which is much slower. Catalog View ships with a pre-packed  jar file. We recommend that you make a jar file that includes the image button file that you want to use. Catalog View ships with jar.exe (in the same directory as the class files) and a little jar.bat file. To make a new jar file you should put the image button file you want to use together with the class files and edit the jar.bat to include your image button in the jar file. After you run the jar.bat you should get a new catalogview.jar file which contains your image button

Put image button file, catalogview.jar and the class files together in the directory indicated by the codebase. This will allow both old and new browsers to load the applet.

You need a data text file with your own data. First make a little test data file with the data structure you want to use. Each line must contain one record. Each record can contain an arbitrary number of fields. Below is an example of one record containing first name, last name, e-mail address, homepage, address, zip, city, country and an image.

"Niels Kirk"Thomsen"admin@trading.dk"www.trading.dk"www.trading.dk"Science Park"8000"Aarhus"Denmark"ist.gif"

You can introduce blanks by putting a space between delimiters. MEMO fields have a special format with new lines indicated by the | character (see below for details of the MEMO type of fields).
It is a good idea to use a spreadsheet or database to maintain the data and then export the data as a text file. The data text file must be delimited by either TAB, SEMICOLON, COMMA, QUOTE MARK or DOBBELT QUOTE MARK. First you must configure the path to the data file relative to the applet's codebase (directory of the class files). The data file must be located in the same directory as the class files or in a directory under the class files. If not the applet will give a security exception error and halt. For example

<param name="SOURCE_FILE" value="data/test.txt">

If you want to password protect your data then the path to the data file must be encoded. Use the encode applet (tools directory). Input the path to the data file in the top text field, for example "data/test.txt" and press enter or press the encode button. The middle text field will display the encoded path string to your data file. The bottom text field should display the decoded text string. Put the encoded path string in the SOURCE_FILE parameter. The encoded path must be followed by the PROTECTED keyword. The "data/test.txt" will look like

<param name="SOURCE_FILE" value="M0MDbMbrMLkMV PROTECTED">

Put an empty index.html file in the data file directory. This will prevent people from sneaking around in your directory structure. If you encode your data file path you probably also want to include the PASSWORD parameter statement. Use the encode applet again to encode a password. For example input "guest" in the top text field and press enter or click the encode button. Put the encoded password in the PASSWORD parameter. It could look like

<param name="PASSWORD" value="RrhkP">

The default delimiter recognized by the applet is double quote mark ("). If you use another delimiter you must indicate that in the DELIMITER parameter. For example

<param name="DELIMITER" value="TAB">

If you want the applet to auto load when a client enter the document that contain the applet include the AUTO_LOAD parameter

<param name="AUTO_LOAD" value="YES">

You must include the path to the gif or jpeg image you want to use as an image button in the IMAGE_URL parameter. The path should be relative to the applet's codebase. For example include the line

<param name="IMAGE_URL" value="demo1.gif">

You can use any size of image. You must indicate the width and height in pixels of the image in the applet's tag. The reason is that an applet can't resize it's own canvas area. The size is fixed in the HTML code. You can use the imagesize applet (tools directory) to find the size of your image. Load the imagesise.html and enter the absolute URL of the image file for example file:/c:/myimages/image.gif . Then the height and width in pixels of the image is displayed. Set the width and height in the applet tag to the size of the image.
If you have the AUTO_LOAD parameter set to yes you may not want to display the image button. Then set the IMAGE_URL value to NO.

The most complex parameter is the FIELD_0, FIELD_1, FIELD_2.... parameters.
Include FIELD_0, FIELD_1,..... parameters for each of the data fields in the data text file. A FIELD parameter can have many keywords set in the value string. NAME, WIDTH, INDEXED, FILTER, SORT, NUMBER, INVISIBLE, MEMO, "IMAGE,base_url" and "URL,base_url,target". The FIELD_0, FIELD_1,.... statements must be consecutive 0, 1, 2....
The minimum requirement in a FIELD statement is the name and the width in pixels of the field, in that order. The NAME must be one word e.g. First_Name.
The INDEXED keyword indicate that the data in this field are indexed when the data load. It is very fast to search in indexed fields, but the search engine will only find exact matches of hole words. The search is case insensitive. At least one field must have the INDEXED keyword set.
The FILTER keyword indicate that the data in this field can be used to filter the data into subsets. Fields with the FILTER keyword set are automatically INDEXED, and they will appear in the Index drop down choice box with three dots after the field name. When such a FILTERED field is selected in the Index drop down choice box the Filter list box will show the indexed words of this field.
Fields with the SORT keyword set are included in the SORT choice drop down box and can be used to sort the dataset. Also INVISIBLE (see below) fields can have the SORT keyword set and be used to sort the dataset.
Fields with the INVISIBLE keyword set are not shown in the data grid, but they are still displayed in the top detail window. Invisible fields can for example be used as dummy fields to set the sort order for date fields. Date fields can be difficult to sort because they are dependent on the format. However, you can include invisible data which are ordered according to date, and then set the SORT and INVISIBLE keywords for such dummy field At least on field must be visible.

Fields with the NUMBER keyword are sorted as numbers and not as strings.
Fields with the "URL,base_url,target" set will appear with a blue color in the grid. When the user clicks at an URL type field in the data grid the applet will launch the java function showdocument("base_url + field data value", target). This function is implemented differently among browsers. Netscape support the http://, file:/ and mailto: protocols. MSIE does not support the mailto: protocol. The base_url should indicate the absolute URL of the base directory of the documents. By default base_url is set to http://. The target part of the URL keyword indicate which frame the document is launched in. Standard targets can be _self, _blank, _parent, _top and _new, or it can be a specific frame name.

• _blank : display the document in a new, nameless window.
• windowName : display the document in a window named windowName. This window is created if necessary.
• _self : display the document in the window and frame that contain the applet.
• _parent : display the document in the applet's window but in the parent frame of the applet's frame. If the applet frame has no parent frame, this acts the same as "_self".
• _top : display the document in the applet's window but in the top-level frame. If the applet's frame is the top-level frame, this acts the same as "_self".
  

Fields with the "IMAGE,base_url" keyword set are displayed in blue in the data grid. When the user click at an IMAGE type field in the data grid, the image is loaded and displayed in the Image Viewer window. The data in an IMAGE field must point at image files (gif or jpeg). The base_url part of the IMAGE keyword is implemented as the base_url part of the URL keyword.

Fields with the MEMO keyword set must have a special format in the data file. The contents of memo fields can be displayed on multiple lines in the top detail window. MEMO fields are automatically set to no INDEXED, INVISIBLE and no FILTER. The lines in a MEMO FIELD must be separated by a | character. For example:

"This is an example of the contents of a memo field in the text data file | Memo Fields are displayed as multiple lines in the top detail window | Memo FIELDs are invisible, non-indexed and non-filtered data types"

The contents of the above MEMO field will be displayed like this:

This is an example of the contents of a memo field in the text data file
Memo Fields are displayed as multiple lines in the top detail window
Memo FIELDs are invisible, non-indexed and non-filtered data types

The order of the keywords in the FIELD parameters should be : NAME WIDTH INDEXED FILTER URL IMAGE MEMO INVISIBLE

Examples:

The data in column 1 in the data file is named Author and the displayed width of this field in the data grid will be 100 pixels wide. The Author field is indexed which will make searches on this field fast

<param name="FIELD_0" value="Author 100 INDEXED SORT">

The data in column 4 in the data file specify the path to documents that can be launched in a new browser window.

<PARAM name="FIELD_3" value="Online 200 URL,http://,_new ">

If all the documents in a URL type field refer to the same base directory you can include this in the base_url. Remember the last slash /

<PARAM name="FIELD_3" value="Online 200 URL,http://www.netscape.com/java/,_new ">

The data in the column 1 in the data file specify addresses that can be launched in Netscapes e-mail window. Remember to use the "_self" as target

<PARAM name="FIELD_0" value="Author 100 SORT INDEXED URL,mailto:,_self">

The data in column 6 in the data file are local documents in the c:/mydocs/ directory, which are launched in the frame named "myframe"

<PARAM name="FIELD_5" value="Letters 100 FILTERED URL,file:/c:/mydocs/,myframe">

The data in column 4 in the data file are image file names located in http://www2.dk-online/users/nkt/classes/images

<PARAM name="FIELD_3" value="Picture 100 IMAGE,http://www2.dk-online/users/nkt/classes/images/>

The applet's layout can be configured by a number of parameter statements. All the components of the tool bars are included by default. All the buttons, drop down choices and the Filter list box, except the navigator buttons and the About button can be configured to be excluded from the tool bars. The visible width of the data grid, the number or rows and the data cell padding can be set. The number of visible lines in the top detail window can be set. The font size and type (BOLD or PLAIN) can be set for the data and the static text of the components. See the configuration section for the details on how to configure the applet.

We recommend that you make your own HTML help document that fits your configuration of the applet. The help document is launched when the client clicks the help button. The HELP_DOC parameter specify the URL and target of the help document. The HELP_DOC parameter has 3 keywords value="URL   BASE_URT   TARGET". For example

<param name="HELP_DOC value="help.html "http://www.trading.dk/catview/" http://www.trading.dk/catview/< /A> _new"> 

5. Configuration of Catalog View

Parameters	Comments	Required
<APPLET code="catalogview.class" codebase"classes" width="124" height= "44" archive= "catalogview.jar">	catalogview.class is the name of the main class file of the applet. The codebase is the directory where the applet's class files are stored. The width and height must be the same as the dimensions in pixels of the image you want to use as an image button. The archive statement point to the compressed class files in jar format which can be loaded by newer browsers	X
<param name="SOURCE_FILE" value="M0MDbMbrMLkMV PROTECTED">	path to the delimited text file relative to the codebase. In this example the path (data/test.txt) is encrypted. The data files must be located in the same directory as the class files or above. If the path is encoded by the encode applet, the encoded path must be followed by the PROTECTED word.	X
<param name="DELIMITER" value= "TAB">	the delimiter used in the data file. The applet support SEMICOLON (;), COMMA (,), Q_MARK ('), DQ_MARK (") and TAB. Default is 1MARK	(X)
<param name="PASSWORD" value= "RrhkP">	use the encode applet to encode a password. It is a good idea to encode the path to the data file as well and put an empty index.html in this directory
<param name="RECORD_NUMBER">	display the total number of records in the progress bar
<param name="AUTO_LOAD" value= "YES">	when the AUTO_LOAD value is YES the applet loads automatically when the user enter the HTML document. In addition the IMAGE_URL can be set to "NO". Then no image button will be displayed
<param name="IMAGE_URL" value= "images/demo1.gif">	path to the image button file relative to the class files	(X)
<param name="HELP_DOC" value="help.html http://myhost/pages/ myframe">	specify the name of the help document, the base_url of the help document's directory and the target frame to display the help document	(X)
<param name="WINDOW_TITLE" value= "References Window">	name of the pop up window frame	(X)
<param name="MOUSE_MSG" value="Pop up window with References">	This message is displayed in the browser status field, when the mouse is over the image button	(X)
<param name="VISIBLE_WIDTH" value= "600">	visible width in pixels of the data grid. If the VISIBLE_WIDTH is larger than the width occupied by the components (buttons, choice boxes, labels, input field) the applet will be resized to the VISIBLE_WIDTH. width. Default VISIBLE_VIDTH is 600
<param name="VISIBLE_ROWS" value= "20">	number of visible rows in the data grid. Default is 20
<param name="TOPVISIBLE_ROWS" value= "5">	number of visible rows in the top detail window. Default is 4
<param name="SEARCH_BUTTON" value= "YES">	if the value is "NO" the Search Index button is excluded from the top button panel. Included as default
<param name="SEARCHALL_BUTTON" value= "YES">	if the value is "NO" the Search All button is excluded from the top button panel. Included as default. If your data set is large (2000-3000 records), consider to set the value to "NO". Full string search is slow and halt other functions.
<param name="SHOWALL_BUTTON" value= "YES">	if the value is "NO" the Show All button is excluded from the top button panel. Included as default
<param name="HELP_BUTTON" value= "YES">	if the value is "NO" the Help button is excluded from the top button panel. Included as default
<param name="SORT_CHOICE" value="NO FIELD_number">	if the value is "NO" the Sort Order Choice is excluded from the bottom panel. Included as default. If you have a large data set (>1000 records), consider to set this to "NO" and keep the data in a preferred sort order. This will speed up the initialization of the applet, the Show All function and the filter function. You can include an integer to indicate which FIELD to sort the data when the data loads the first time
<param name="FILTER_CHOICE" value= "NO">	if the value is "NO" the Filter List Box is excluded from the panel. Included as default
<param name="INDEX_CHOICE" value= "NO">	if the value is "NO" the Index Choice is excluded from the bottom panel. Included as default
<param name="KEY_FIELD" value= "NO">	if the value is "NO" the Search String Input Field is excluded from the bottom panel. Included as default. If this is set to "NO" the SEARCH_BUTTON and SEARCHALL_BUTTON are also excluded
<param name="FONT" value="11 BOLD">	size and type of the font used in the components (buttons and labels). Only PLAIN and BOLD types are supported. Default is "11 BOLD".
<param name="DATA_FONT" value= "11 PLAIN>	size and type of the font used in to display the data. Only PLAIN and BOLD types are supported. Default is "11 PLAIN".
param name="PAD_X" value= "2">	free horizontal space between the borders of a data cell in the grid and the text in the data cell in pixels. Default is 4.
param name="PAD_Y" value= "2">	free vertical space between the borders of a data cell in the grid and the text in the data cell in pixels. Default is 2.
<param name="FIELD_0" value= "Author 200 INDEXED FILTER">	FIELD_x PARAMETER. x must be consecutive 0, 1, 2 .... The value string of the FIELD_x PARAMETER can contain: 1. NAME in one word 2. WIDTH in pixels of the field in the data grid 3. INDEXED keyword will make it fast to search on the field. At least one field must be indexed 4. FILTER keyword can be used to filter the data set. FILTERED fields are automatically INDEXED. Appear in the Index drop down choice box with three dots after the name 5. SORT keyword can be used to sort the data set. SORT fields are included in the SORT drop down choice box. 6. NUMBER keyword are sorted as numbers. 7. "URL,base_url,target" type of fields are launched in the browser when clicking on them. The base_url string must specify the first part of an absolute URL, and minimum the protocol name http://, file:/ or mailto: Default base_url is http:// The base_url part of the URL keyword can be followed by a comma and then a target specifier. Targets can be _self, _parent, _top, _blank or _new or any frame name. Default target is _new. 8 "IMAGE,base_url" keyword works like the URL,base_url part. Such Fields are launched in the Image Viewer pop up window. 9. MEMO fields are set to INVISIBLE, no INDEXED and no FILTERED. The data in MEMO fields can be displayed on multiple lines in the to detail window. The line separator is | 10. INVISIBLE fields are not displayed in the data grid, but in the top detail window At least one field must be INDEXED and not INVISIBLE	X
<param name="FIELD_1" value= "Title 300 URL,http://,_new">		X
<param name="FIELD_2" value= "Journal 200 FILTER SORT">		X
<param name="FIELD_3" value= "Year 40 INDEXED SORT">		X
<param name="FIELD_4" value="KeyWords 100 FILTER SORT INVISIBLE">		X
</APPLET>		X

6. Functions

Component	Function
<<	go to first record
<	go to previous record
>	go to next record
>>	go to last record
Search Index	uses the string entered in the "Search String" input box to search all records in the selected index for words with an exact match (case insensitive). The index is chosen in the Index drop down list. This is the default action after entering a search string in the input box and pressing the enter key
Search All	uses the string entered in the "Search String" input box to search all records (also non-indexed) for a match (also parts of words, case insensitive). Much slower than Search Index
Show All	displays all the records. Can be used after a subset of records were retrieved by a search or filter event. Does the same as selecting the "all" category in the Filter drop down box.
Select All	toggle the selection of records in the current result set for printing. Selected records are marked by a black square in the third left column. Selected records can be printed to a new browser window by clicking the print button. Records can be individually selected/deselected by clicking with the mouse in the third left column of the data grid.
Help	launch the document indicated by the HELP_DOC parameter
About	shows information about the Catalog View Applet.
Sort choice box	selects the field used to sort the records in descending order. Works on all the visible fields in the data set (also non-indexed fields). This can be slow with large data sets
Index Choice Box	selects an INDEXED field to use with the Search Index button. This search should be used for fast searches and works well even on very large data sets. If a field name with three trailing dots is selected the indexed words of this field is shown in the Filter list box.
Search String input field	used to input search strings for the Search Index and Search All buttons.
Filter list box	keywords used to filter the records. Typically this is words dividing the data set in categories.

Data Grid Features.

In order for the keys to take action the grid must have the focus. It gets the focus by clicking at the grid. In some UNIX browsers the keys does not work

Event	Function
Click in the left column (row numbers)	selects the current record and display details for this record in the top text window.
Click in the third column from the left	toggle selection of individual records for printing
Click on a data field	selects the specified field and displays the data of the field in the top text window. If the field is of type URL or IMAGE a document or image is displayed
Home Key	go to first record
End Key	go to last record
Page Up Key	go to page up
Page Down Key	go to page down
Up key	go to previous record
Down Key	go to next record
Right Key	go to next field
Left Key	go to previous field

7. Trouble Shooting

Check list

• Check the path to the CODEBASE directory. It should be set relative to the HTML document that contain the applet
• Check the path to the data file. It must be set relative to the CODEBASE
• If you use encoding make sure to set the PROTECTED word in the SOURCE_FILE parameter
• Check that the delimiter is correct.
• Check that the IMAGE_URL parameter is set correct. It must be relative to the CODEBASE.
• If you start more than one instance of the applet in the same document make sure they use the same CODEBASE
• Make sure there is no blank lines in the data file
• Some parameters like VISIBLE_WIDTH require a number value. Make sure to set the such values to a valid numbers
• Make sure the FIELD_x parameters are consecutive 0, 1, 2, 3....
• At least one FIELD must be INDEXED and visible
• Check that the base_url is correct in URL and IMAGE type of fields and in the HELP_DOC parameter. Make sure the protocol is set right http:// or file:/ or mailto: .The base_url string + the data in the URL or IMAGE must point at a valid file.
• Check that all parameter names and values are embedded between DOBBELT QUOTE MARKS. For example <PARAM name="IMAGE_URL" value= "catview.gif">

8. Contact the Author

International Starch Trading A/S
Science Park
Gustav Wieds Vej 10
DK-8000 Aarhus
DENMARK
admin@trading.dk
www.trading.dk

Back to the CatalogView applet page

How to Add Java Applets to Your Site

New on the Java Boutique:

New Review:

Time Management Made Easy with the Quartz Enterprise Job Scheduler
Why not just use the Java timer API? This open source scheduling API boasts simplicity, ease-of-integration, a well-rounded feature set, and it's free!

New Applet:

Reverse Complement
Reverse Complement is a simple applet that converts DNA or RNA sequences into three useful formats.

Elsewhere on internet.com:

WebDeveloper Java
Lots of Java information on webdeveloper.com

WDVL Java
Thorough Java resource at the Web Developer's Virtual Library.

ScriptSearch Java
Hundreds of free Java code files to download.

jGuru: Your View of the Java Universe
Customizable portal with online training, FAQs, regular news updates, and tutorials.