FreeData2 Applet

FreeData2 is a free database applet with which you can add a simple searchable database to your website without any need for server-side scripts. Just upload the applet's .class and .jar files to your server, along with your database definition file (DDF) and you're set to go. The applet supports a database with as many as 3000 records and 50 fields per record. You can also switch the DDF file, which is a simple .txt file, via JavaScript.

Here is an example of FreeData as a contact list: (Search using an 'n' in the Name field to see all 3 contact records.)

You must have a java-enabled browser to view this page.

Database Definition File (DDF)



The applet parses a Database Definition File (DDF) that you create and upload to your web server in the same directory containing the FreeData .class files. The DDF file is a standard text file created with a text editor, such as Notepad or DOS Edit. The default name for the DDF file is database.txt, but you can change this via the FileName applet parameter. As outlined below, if the database you create contains one of the special field names URL: or e-mail:, a link button will be provided either linking to the associated URL or bringing up the client computer's default e-mail program. FreeData will also display an image in the RESULTS pane for matching records if the special field name Image: is found and that applet parameter HasImages is set to "1". The image will act as a hyperlink when clicked upon if a special field named ImageLinkURL: is found. Image:, URL:, E-Mail:, and ImageLinkURL: fields may be hidden if desired.

The DDF file must be formatted as follows: 

[Fields]
Field Name 0
Field Name 1
Field Name 2
Field Name 3
[Records]
Field Name 0 value for record 0
Field Name 1 value for record 0
Field Name 2 value for record 0
Field Name 3 value for record 0
blank line to separate records
Field Name 0 value for record 1
Field Name 1 value for record 1
Field Name 2 value for record 1
Field Name 3 value for record 1

Here is a sample DDF file used in the example above:

[Fields]
Name:
phone number:
e-mail:
URL:
[Records]
Mark Ganson
555-5555
java4free@bigfoot.com
http://www.bigfoot.com/~java4free

John Doe
5IM-LOST
n/a
n/a

Jane Doe
IM-LOST2
jdoe2@lost2.com
http://www.ThisIsNotARealURL.com?id=Test

To automate the creation of DDF's, you may download a freeware utility from Benjamin Zeleznik, called FreeData File Maker (FDFM). Go to his website and click the Programs link in the left frame. You will need the Borland Database Engine, which is also available for download from his site, to use the program. If you find his program of value, please be sure to send him a thank you message for his generous contribution.

Here is the HTML for producing the above sample:
Keep the following rules in mind when creating the DDF file:

1) The first line must contain the keyword "[Fields]" (case in-sensitive).
2) The next lines must contain the names of the fields in the database.
3) Blank lines in the "[Fields]" section of the DDF will be interpreted as multi-line fields.
4) The line immediately following the last field name must contain the keyword "[Records]".
5) The line immediately following the "[Records]" keyword contains the value of record 0.
6) Record definitions must be separated by an empty line.
7) Note that there is no blank line separating the "[Records]" keyword and record 0.
8) Each line must end with a hard return.
9) URL: and e-mail: are special field names that contain links the Link Button will automatically link to.
10)Image: is a special field name that contains the name of an image to display for matching records.
11)ImageLinkURL: is a special field name that contains a hyperlink for when the image is clicked.
12)To use the Image: and ImageLinkURL: fields, be sure to use the HasImages applet parameter.
13)Be sure to include a file named "default.jpg" to be displayed when the image field is "n/a" or for non-matching records.


Multi-line fields are supported. To create a multi-line field, enter one or more blank lines following the name of the field (in the [Fields] section of the DDF file). YOU MUST be sure to enter the appropriate number of lines in the [Records] section for each record definition!

The field names URL: and e-mail: have special meanings. These contain links that the link button in the upper left corner will link to whenever a record containing one of these special fields is found. (If the URL: or e-mail: field value for a given record is n/a, the link button's label and URL will not be changed from its original values. The label of the link button will change to Visit URL or Send Mail, depending on which of the special field names are part of the set of field names. What happens if both the e-mail: and URL: special field names are available? The one that occurs last in the DDF file will take precedence. If you wish to hide these fields, set the applet parameter HideLinkField to "1".

The field names Image: and ImageLinkURL: have special meanings, too. The Image: field must contain either "n/a" or the name of an image file (.jpg or .gif) to be shown in the RESULTS pane when a matching record is found. You must include the applet parameter HasImages in order to activate this feature. Otherwise, the Image: and ImageLinkURL: fields will be treated as ordinary fields. The ImageLinkURL: field contains a hyperlink to be used when the user clicks the image. The ImageLinkURL: may be hidden by using the applet parameter HideImageLinkURLField = "1". The Image: field may be hidden by using the applet parameter HideImageField = "1". The ImageLinkURL hyperlink may be targeted by using the ImageLinkURLTarget applet parameter ("_top", "_blank", "_self", "_parent", or frame name may be used.)

Here is an example of FreeData used as an image album. Search for hare, tortoise, go, or stop:

You must have a java-enabled browser to view this page.

As mentioned above, it is vital that you format the DDF file with the appropriate number of blank lines if you are creating multi-line fields as in the recipe example. This can be tricky at times! If you mess up with the formatting, your data will be placed into the wrong fields.

Depending on the number of fields you specify in the DDF file, you will need to adjust the height of the applet to line up the text fields used to display the query and result views at the desired heights. Trial and error is the best strategy.

Here is the HTML for creating the image album sample:

Here is the imagealbum.txt file:



Applet Params



FileName
This tells the applet the name of the DDF file that you wish to use for this database. The default name is database.txt.

BGColor
The applet's background color is set with this param. You must use a 6-digit hexadecimal notation, similar to the way colors can be set in HTML. The first 2 digits are for the red component, the next 2 for the green component, and the final 2 for the blue component. For example, to specify a blue background, use 0000ff. To specify a green background, use 00ff00. A grey background: 7f7f7f.

FGColor
Sets the foreground color. See the description for BGColor param above.

BGButtonColor
Sets the background colors of the buttons, such as the Search button, Clear button, etc. See the description of BGColor param above.

FGButtonColor
Sets the foreground colors of the buttons, such as the Search button, Clear button, etc. See the description of BGColor param above.

LinkURL
At the top left of the applet, there is a link button. By default, the link button is labeled Java4Free! and serves as a hyperlink to my own website: http://www.bigfoot.com/~java4free, but you may modify this to link to the URL of your choice, such as an advertisement link. You may also have this URL modified by the applet automatically whenever a matching record is found which contains the field with a special field name: URL:. For an example look at the image album example above wherein I have replaced Java4Free! with NFLPicker in the applet HTML.

LinkLabel
Works in conjunction with LinkURL above. This sets the label for the link button. Obviously, if you wish to provide a hyperlink to a different URL other than Java4Free!, then you will also want to change the link button label to something else. See the image album example above wherein I replaced the Java4Free! label with NFLPicker in the applet HTML.

VisitURLLabel
Similar to the LinkLabel param discussed above except that this label is only used when the database contains a field with the special field name URL: in the latest matching record following a successful query. For example, you might have a database of websites where your users can go to download free software. Each record can have a URL: field providing the URL to the website featured in that particular record where the user can go to download the software. The link button could contain a link to an advertiser selling ink cartridges except when a successful query results in a matching record at which time you could change the link button's label to something like Download Now. You would use the LinkLabel param to set the link button's label to Get Ink! and use the VisitURLLabel to set the link button's label to Download Now! whenever there is a successful query.

LinkTarget
This can be a target frame for the link button's hyperlinking capabilities. It can also be _blank, _top, _self, or _parent. (Default is _top.)

HelpURL
In the drop down menu at the top right side of the applet, there is a link to a help page. This is a generic help page that is on my freeyellow.com server. However, because there is no way for me to know the nature of your database implementation, I am not able to provide custom instructions for you. You can set this param to have the applet hyperlink the user to the help page of your choice that you create specific to your implementation. Also, since my help page is in English, you may wish to create a different language version of the help page if the visitors of your page are expected to be more fluent in a different language.

HelpTarget
Similar to LinkTarget param except that it works on the HelpURL rather than on the link button.

HasImages
Set this to "1" if you wish to have the applet display images. This is necessary to enable the special field name Image: to display that image upon successful queries. See the image album example above.

ImageLinkURLTarget
Works like the LinkTarget param above, except that it works on the images being displayed as in the image album example above. When the user clicks the image, if the image is being used as a hyperlink, this param provides the target for that link. (Default is _top.) Use the special field name ImageLinkURL: in your DDF to provide the URL to link to when the user clicks the image.

HideLinkField
If you have a special field named URL: or E-Mail:, the applet will set the link button to hyperlink to the values of these special fields upon a successful query. However, you might not wish to have these fields displayed in the RESULTS VIEW. Set this param to "1" to hide these 2 special fields.

HideImageField
Similar to HideLinkField above, except that it hides the special field named Image:

HideImageLinkURLField
Similar to HideLinkField above, except that it hides the special field named ImageLinkURL:

HideListView
Hides the LIST VIEW item from the drop down menu at the top right of the applet. Set this to "1" to hide this item. (Requires the Author and Origin params discussed below.)

ImageWidth and ImageHeight
Sets the size of the image to be displayed, forcing the applet to resize the image, if necessary. For example, you may have the applet resize all images to 100 X 100 by setting each of these params to "100". The default sizes for these params is 200 X 200.

ResizeImage
Set this to "0" if you wish to display images in their native sizes rather than forcing them to be displayed at the sizes set with the ImageWidth and ImageHeight params above. (Images are automatically resized by default unless this param is used.)

Author and Origin
By setting Author to "Mark Ganson" and Origin to "http://www.bigfoot.com/~java4free", you will automatically remove the Java4Free! item from the drop down menu at the top right of the applet. If you do not do this and the user selects the Java4Free! item from the menu he/she will be hyperlinked to my website.

Internationalization Params
Note that the international versions of FreeData been replaced with the params below.

The following params are provided to support different languages. Set these params to display these default English language strings in a different language. For example, if you wish to have a Spanish language version of FreeData you could set the "Search" button to be labeled "Buscar" instead of "Search" by doing this:

<param name = "SEARCH_STRING" value = "Buscar">

Here is a list of the internationalization params and the default English values:
SEARCH_STRING = "Search"
QUERY_VIEW_STRING = "QUERY VIEW"
RESULTS_VIEW_STRING = "RESULTS VIEW"
LIST_VIEW_STRING = "LIST VIEW"
SEARCH_HELP_STRING = "Search Help"
CLEAR_STRING = "Clear"
MATCH_ALL_STRING = "Match All"
MATCH_ANY_STRING = "Match Any"
PREVIOUS_MATCH_STRING = "Previous Match"
NEXT_MATCH_STRING = "Next Match"
NULL_QUERY_STRING = "NULL QUERY"
NOT_FOUND_STRING = "Not Found"
END_OF_DATA_STRING = "End of Data"

JavaScript Interface:



You can do quite a few things with FreeData via a fairly extensive JavaScript interface. Heretofore this interface has been undocumented, largely because it was untested. I have decided to go ahead and document the interface and rely upon you, the user, to inform me of any problems you encounter with it so that I can then go in and fix them.

public void setFileName(String newFileName)
Sets the DDF file to the file specified in the string newFileName.

For example: document.FreeData.setFileName('database2.txt');

public int getLastMatchingRecord()
Returns an integer value (zero-based) of the last matching record found after a successful query, which might be 0 if the first record in the database was a matching record. It might also be 0 if the last search was unsuccessful. You might want to begin your DDF with an empty first record and then assume that a return value of 0 from this method call always means that the last search was unsuccessful.

For example:

var nLastMatch;
nLastMatch = document.FreeData.getLastMatchingRecord();
// if nLastMatch = 0 either the first record was a match or no matching record was found
// otherwise nLastMatch is the zero-based index of the matching record

public void showRecord(int nRecord);
Puts the applet in the RESULTS VIEW and displays the record indexed by nRecord in the results fields. This method also sets the global nLastMatchingRecord variable.

public String getFieldValue(int nWhichField, int nRecordNumberParam)
nWhichField is a zero-based index specifying which field we are looking at.
nRecordNumberParam is a zero-based index specifying which record.

Returns the string value of the specified field index and record index. Note that the return value will be "Range Error" if one or more of the indices provided are less than 0 or greater than the number of fields/records in the database.

For example:

var nLastMatch;
var strMyFieldValue;
var nWhichField = 2; //this would be the third (3rd) field in the database.
nLastMatch = document.FreeDataApplet.getLastMatchingRecord();
strMyFieldValue = document.FreeDataApplet.getFieldValue(nWhichField, nLastMatch);

// var strMyFieldValue now contains the value of the 3rd field in the last matching record,
// a successful match was found.

public void performSearch(String strWhichField, String strQueryValue);
strWhichField is an integer value expressed as a string representing the zero-based index of the field you wish to search.
strQueryValue is a string representing the actual search query.

Performs a database search.

For example: document.FreeData.performSearch('0', 'john smith'); would submit a query to the applet telling it to search for the string 'john smith' in the first field of the database.

public void nextMatch();
Simulates pressing the "Next Match" button. (Simply returns if the button is not enabled.)

public void previousMatch();
Simulates pressing the "Previous Match" button. (Simply returns if the button is not enabled.)

public void clearCurrentView();
Equivalent to clicking the "Clear" button on the applet.

public int getNumFields();
Returns the number of fields in each record in the current database.

public int getNumLinesNeeded(int nWhichField);
Tells you if this particular field is a multi-line field and, if so, how many lines are needed to support this particular field.

public String getFieldName(int nWhichField);
Returns the field name for this particular field. Use this along with getNumFields() to enumerate the field names in the current database.

There you have it, the JavaScript interface. On the surface, it does not look like much, but someone handy with HTML and JavaScript can actually do quite a bit with this. Click here to see JavaScript example page using FreeData.

Using the FreeData Applet


At the top of the applet, you will find three (3) controls: A re-definable link button to my web site, a Search button, and a drop down Choice list to be used for switching the three (3) supported views: Query view, Results view, and List view. The drop down Choice will also provide a link to my web page. The link button can be modified to point to whatever you like via the LinkURL and LinkLabel parameters. Pressing the Search button will do one of two things, depending upon which view the applet is in when it is pressed. If the applet is in Query view, the applet will search the database and switch to the Results view. If the applet is in any other view, it will switch to the Query view.

The Query view is the view from which the database may be queried. Enter keywords into the fields to be searched and press the Search button to perform the search. All searches are case in-sensitive and include substrings in the search. Words separated by spaces will be treated as separate substrings to search for. If either substring is found, the result is a match. Wildcards are not supported. Blank fields are ignored during the search. You must enter at least one keyword in at least one field. For multi-line fields, only the first field (with the label) can be used to enter the keywords to be searched for. However, all of the lines in the multi-line field will still be searched. Pressing the "Enter" key on your keyboard while in the QUERY pane view is identical to clicking the "Search" button described below.

Along the bottom of the applet, you will find four (4) buttons: a Clear button, a Match Any/Match All button, a Previous Match button, and a Next Match button. Pressing the Clear button will clear the current view only; the other views are unaffected. The Match Any/Match All button can be in one of two states: Match Any or Match All. In Match Any mode, any matching field will result in a match for that record. In Match All mode, all entered fields must match a record in the database to result in a match. The Previous Match button will return the last successful match found using either the Search button or the Next Match button. The Next Match button will perform a search similar to the Search button, except that the search will begin from the point of the last successful search, whereas the Search button always institutes its search from the beginning of the database. The Next Match button is only enabled after a successful match is found using the Search button. If the result of the search using the Next Match button is unsuccessful, the label of the Next Match button is changed to "Not Found".

The List view serves as a log for the searches that have been entered. Users can copy the data from the List view to the clipboard for use in other applications, such as word processors.

Here are the files needed for the FreeData applet:
FreeData2.jar
FreeData2.class
Record.class
Field.class
AdCanvas.class

Sample DDF files:
database.txt
imagealbum.txt

Send questions/comments/flames to java4free@bigfoot.com
Java4Free! Home