Home > Fluid Dynamics Search Engine > Help > 1027

Advanced Search: Controlling realm options

The template "searchform.htm" includes a select drop-down box which lists all Realms in alphabetic order, and includes "[ All ]" at the top. The realm "[ All ]" is selected at first, and then after a search is performed, the previously selected realm will be the default.

Prior to version, the relevant replacement value was "SelectRealm" which expanded to the HTML select element which spanned the chain of option elements:

in Search Index: %SelectRealm%

As of version, a new replacement value was added which allows for more flexibility (the old replacement value still works):

in Search Index: <select name="Realm"><option value="All">[ All ] %realm_options%</select>

Using the new version it is easier to remove "[ All ]" as an option. The replacement value "realm_options" is the chain of option elements.

You can force a certain realm to be searched by using a hidden field instead of the select box:

<input type="hidden" name="Realm" value="MyRealm" />

You can force a subset of realms to be searched by explicitly listing them, rather than using the replacement values:

in Search Index: <select name="Realm">
<option value="All">[ All ]
<option value="foo"> foo
<option value="Pick Me!" selected="selected"> Pick Me!</select>

Note that the Realm value is optional - if omitted, all realms will be searched. On systems where there is only one realm, or where visitors are expected to search all realms anyway, it may be most convenient to just remove the Realm select box entirely.

Controlling which realm is selected

The list of realms is controlled by function PrintTemplate, which gets it data from "searchform.htm". You can control which realms are listed, if any.

The selected realm, on the other hand, is controlled by function SetDefaults which is called at runtime. From the template file, you cannot and should not try to control which realm is selected by default. You may be able to control which realm is selected by default by linking to your search script with a Realm parameter, like www.xav.com/search.pl?Realm=xav.com.

SetDefaults will try to make the Realm form element default to whatever the user previously entered. This has two implications:

First, forcing the default selected realm is generally not possible, even with code like this:

in Search Index: <select name="Realm">
<option value="All">[ All ]
<option value="foo"> foo
<option value="Pick Me!" selected="selected"> Pick Me!</select>

In this case, if the user searches realm "foo" then the SetDefaults function will be aware of this and will rewrite the above fragment as "... option selected="selected" value="foo" ...". That will conflict the other selected attribute and the first selected element will probably win. These kinds of conflicts will result in seemingly inconsistent behavior that may frustrate you and your users.

Second, the SetDefaults function makes certain assumptions about the HTML cleanliness. In particular, it assumes that the value of "name" will be double-quoted, and that option elements will included double-quoted "value" attributes. If these assumptions don't hold true, then it will not correctly default the realm to the previously-selected value. For example, the following is valid HTML but won't be recognized by SetDefaults() because "Realm" is not quoted and "value" attributes are not used consistently:

in Search Index: <select name=Realm>
<option value="All">[ All ]
<option> foo
<option selected> Pick Me!</select>

See also: Advanced Search: Selecting Realms by name

    "Advanced Search: Controlling realm options"