|
findinsite-cd JavaScript interface
Introduction
You can use JavaScript to control FindinSite-CD using the functions listed on this page.
You can set or add to the search text and do a search. In addition, there are functions
to change the index or change subset availability.
See the example below.
The function to do a search and return the results as HTML is demonstrated
in the HTML Results example.
The field search example also uses JavaScript
to tell FindinSite-CD user field choices.
Limitations:
The FindinSite-CD JavaScript interface does not work in all browsers -
check compatibility here.
Java and JavaScript
Please note the difference between Java and JavaScript carefully:
- Java
- FindinSite-CD is an applet written in the Java programming language.
The FindinSite-CD runtime is run in a browser window using
the APPLET tag in a web page. Normally you control how FindinSite-CD runs by setting
values for various applet parameters.
You cannot write Java in a web page.
- JavaScript
- JavaScript is program script code that is added to a web page.
JavaScript can be run when a user interacts with elements on a web page,
such as button clicks or a list box selection change.
You can use JavaScript to call public functions in a Java applet such as FindinSite-CD
(provided the MAYSCRIPT attribute is in the APPLET tag).
JavaScript is sometimes called VBScript or ECMAScript.
|
Calling FindinSite-CD from JavaScript
First, the FindinSite-CD applet must be named fisCD in the APPLET tag.
FindinSite-CD word highlighting relies on having this name, so do not change it.
You do not need to change the standard invocation of FindinSite-CD
in the search page generated by FindinSite-CD-Wizard:
<APPLET CODE=fisCD NAME=fisCD WIDTH=500 HEIGHT=300 ARCHIVE=fiscd.zip MAYSCRIPT>
To call a function in FindinSite-CD, simply put the function name and any parameters after
document.fisCD. For example, to search for the end,
use the following in your JavaScript code.
document.fisCD.Search("the end");
If you want to use a double quotes character, use \" in JavaScript.
For example, to search for "the end", do this:
document.fisCD.Search("\"the end\"");
In most cases, you will not want to hard code such search strings into your script.
Instead, you will typically pick up the string a user has typed and call FindinSite-CD with this
string. This JavaScript function retrieves the string typed into the text box named SearchText
in the form called example, and calls FindinSite-CD to search for that string.
function DoSearch()
{
var Search = document.example.SearchText.value;
document.fisCD.Search(Search);
return false;
}
|
The following HTML code can be used to call the DoSearch JavaScript function.
When the user clicks on the Search button, the FORM onsubmit event handler calls
DoSearch, which must return false to ensure that the default form action
does not occur.
<FORM NAME="example" onsubmit="return DoSearch()">
<INPUT TYPE=text NAME=SearchText MAXLENGTH=30><P>
<INPUT TYPE=SUBMIT VALUE="Search">
</FORM>
|
Note that you do not need to put in any special code to handle user input of double-quotes
characters.
BODY tag onLoad event
You might think that the search page BODY tag onLoad event would be a good place
to start work controlling FindinSite-CD. Unfortunately, the onLoad event is usually
called before FindinSite-CD has finished loading, so it is not sensible to use this event.
FindinSite-CD JavaScript Interface Reference
The following table lists the public functions that are available to control FindinSite-CD.
Most of the functions do not return a value;
for these functions there is no way of determining if an error occurred,
such as invalid parameters.
| Function |
Parameters |
Returns |
Description |
|---|
|
ClearFields
|
|
|
Clear all field values.
See field search documentation.
|
|
SetField
|
String FieldName,
String SearchText |
Boolean |
Set the search string for the specified field.
Returns true if the field is set OK.
See field search documentation.
|
|
SetSearch
|
String SearchText |
|
Set the search string to the given text, but do not search. |
|
SearchAndGetResults
|
String SearchText |
String Results |
Set the search string to the given text, do search and return the results in HTML form.
See the HTML Results example.
|
|
Search
|
String SearchText |
|
Set the search string to the given text, and do search.
If SearchText is null then the search string is not set, but do search.
|
|
SetPreSearch
|
String PreSearchText |
|
Sets the text that is put before all subsequent user search text. |
|
SetPostSearch
|
String PostSearchText |
|
Sets the text that is put after all subsequent user search text. |
|
SelectSubset
|
int SubsetNo,
boolean Selected |
|
Makes the specified subset available or not
SubsetNo must be 1 or more
Selected must be true or false
|
|
SelectIndex
|
int IndexNo |
|
Changes to the specified index
IndexNo must be 1 or more
|
Pre- and Post-Search Text
The SetPreSearch and SetPostSearch
functions set text that is always added to the user's search text
(and search text set using SetSearch and
Search).
This might be a useful way of restricting the results shown to a user.
The pre- and post-search text is NOT displayed in the FindinSite-CD search text box.
Instead, it is silently added before a search is done. The user's search text
is always put in parentheses. Therefore,
SetPreSearch("hello") and
SetPostSearch("there")
followed by the user typing out would result in this full search text:
hello ( out ) there
You do not have to use both SetPreSearch and
SetPostSearch.
To clear pre- or post-search text use a blank string.
If you want the full search text displayed in the results,
set the ShowFullSearchTextInResults
parameter. The example below shows this in action.
Example
This example illustrates use of the SetSearch,
Search,
SetPostSearch and
SelectIndex functions.
Look at the source for this page and consult the notes below
for a full understanding of the code.
- The SetSearch() example sets the search text to the chosen
text when the listbox selection changes.
- The Search() example sets the search text to the user's entered
text and asks FindinSite-CD to do a search.
- The SetPostSearch() example sets the post-search text to the selected
listbox option. If you then do a search (either using the Search() example,
or by typing in text and clicking "Search") then you will see how the search is changed.
You can see the full search text because the FindinSite-CD parameter
ShowFullSearchTextInResults
has been set.
- The SelectIndex() example changes the FindinSite-CD index to the selected
listbox option.
|
|
The control panel above FindinSite-CD is enclosed in a FORM called example.
The SetSearch panel HTML code is shown here.
A SELECT input called List1 has all the text options.
When the user changes the list box selection, the onChange event handler
calls the JavaScript function SetSearchText().
<FORM NAME="example" action="javascript:void(0)">
<SELECT NAME="List1" SIZE=5 onChange="SetSearchText()">
<OPTION SELECTED>-- Clear search text --
<OPTION>FindinSite-CD
<OPTION>FindinSite-CD-Wizard
<OPTION>Findex
</SELECT>
</FORM>
|
The JavaScript function SetSearchText() is defined in this page's header
as follows. It extracts the selected index from the form control List1
and retrieves the selected text. For the special case when "-- Clear search text --"
is selected, SetSearchText() sets the search text to an empty string.
Finally, SetSearchText() calls the SetSearch
function in FindinSite-CD.
function SetSearchText()
{
var SearchIndex = document.example.List1.selectedIndex;
var Search = document.example.List1.options[SearchIndex].text;
if( SearchIndex==0)
{
Search = "";
}
document.fisCD.SetSearch(Search);
}
|
|
