Creating Custom Search Forms

The NXT 4 templates directory (<InstallPath>\Templates\Enu) contains the default NXT search forms.

Simple Search (banner.xsl) allows the user to do a simple keyword or phrase search.
Advanced Search (advsearch.htm) allows the user to both enter a search string and set several search options, then uses Javascript to retrieve the specified values and assign them to the form's parameters.
Boolean Search (boolsearch.htm) allows the user to enter standard Boolean search options.
Document Summary Search (metadatasearch.htm) allows the user to search on metadata.
Faceted Search (facetedsearch.htm) allows the user to search by using predefined facets.
Folio Advanced Query Search (folio-advanced-query.htm) allows the user to search by using SmartSearch components.
Country Quick Facts Search (QuickFactsSearchExample.htm) contains four forms ranging from a simple search performed on the Country Quick Facts sample content collection to two search forms that use the Javascript word wheel

If you want to create your own search forms, you should start by modifiying one of these samples using the following guidelines. Once you have completed and tested your search form, you can add it to your site.

Be sure you save and rename any of these search forms before you modify anything.

How Search Forms Work

A search form is an HTML form where users enter information that is used to search a NXT 4 site. Simple search forms contain a single input field but more complex search forms include multiple input fields and use Javascript to combine user input into a search string.

The search string and search options are stored as parameters on the form. When the user submits the form, the search terms in the form data are passed to NXT 4 using the POST or GET method and the values combined into a URL that requests a search results page.

An HTML form requires that you set the method and action attributes. For search forms, the method should be POST or GET and the action must be , which is a NXT 4 template replacement variable that resolves to a URL pointing to the NXT 4 Web extension used to process searches.

For long searches, Rocket recommends that you use POST because it does not place the contents of the search on the URL. GET places the search contents on the URL to pass it to the server. Since NXT 4 limits the length of the URL to 2,048 total characters, long searches might not get passed properly on the URL.

Design Considerations

A basic search form can use a single "text" (or "textarea") element and a button that submits a simple search to the NXT 4 server. The simplest search form does not need any scripting. As the designer of the form, you can set all other options within the form and allow users to enter their search criteria.

This example template sets all options internally and allows the user to enter the search terms.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">

<HTML>
<HEAD>
<TITLE>Super Simple Search Form</TITLE>
</HEAD>

<BODY>

<FORM NAME="SuperSimpleSearch"
ACTION="<!-- #EXECUTIVE:SCRIPT_NAME -->"
METHOD="POST" TARGET="main">
<B><!-- Enter Search Here -->

<P><INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Search!">

<INPUT NAME="xhitlist_q" VALUE="" TYPE="TEXT" SIZE="20">
<INPUT NAME="f" VALUE="xhitlist" TYPE="HIDDEN" SIZE="0">
<INPUT NAME="xhitlist_d" VALUE="" TYPE="HIDDEN" SIZE="0">
<INPUT NAME="x" VALUE="Simple" TYPE="HIDDEN" SIZE="0">
<INPUT NAME="xhitlist_s" VALUE="relevance-weight" TYPE="HIDDEN" SIZE="0">
<INPUT NAME="xhitlist_hc" VALUE="" TYPE="HIDDEN" SIZE="0">
<INPUT NAME="xhitlist_xsl" VALUE="xhitlist.xsl" TYPE="HIDDEN" SIZE="0">
<INPUT NAME="xhitlist_vpc" VALUE="first" TYPE="HIDDEN" SIZE="0">
<INPUT NAME="xhitlist_sel" VALUE="title;path;relevance-weight;home-title" TYPE="HIDDEN" SIZE="0">
</FORM>

</BODY>
</HTML>

A multi-field search form is more flexible. It can provide several input areas to search specific fields in a content collection or to prompt the user to enter certain types of information. A multi-field search form lets the user set certain values.

A multi-field search form requires scripting because it must combine the information the user enters into each input element to produce a valid search string. Additional scripting might also be necessary to set the search options.

Searching fielded information or headings can be tricky for users. Unless you provide a static list of options, users must guess when deciding which term might appear in the field or heading they are searching. Adding a word wheel to a search form gives users a list of terms to select from based on the search form's criteria.

Search Form Guidelines

The following suggestions can assist you as you plan the number and type of search forms to provide at your site.

Provide a simple form for simple searches: This may appear obvious, but the tendency is to add too much to a form. For quick searches, a text input field and a submit button are often enough.
Provide a multi-field form for "advanced" or "detailed" searches: For more complicated searches, or for instances where you want to guide a user through the search process, using several text input fields is required.
Use the "getDomain" function: Include the getDomain function in a search form to allow the users to limit the scope of their search to selected branches of the site's table of contents. See the Advanced Search template (AdvSearch.htm) for an example on calling the function. The getDomain function is found in the SearchForm.htm template.
Use the domain element (d) to limit the scope of a search: Hard code this value in templates designed for a specific content collection or a set of content collections.
Use the xhitlist_q parameter to specify a NXT 4 query string: Search options are set through the other arguments used to request a search results page.
Use FORM elements to allow the user to specify search terms and search options: Use the form's "ONSUBMIT" script to retrieve information from a form's elements and set it into the forms parameters for compilation into a URL.

For example, a search form might include a "test" element named "Query" to allow the user to enter a query string. When the user submits the form, a script assigns the form's xhitlist_q parameter the value specified in the Query element. For multi-field search forms, you must use a script to gather the search terms from the various input elements and create a single query string stored in the xhitlist_q parameter.

Use option buttons to switch between the available query syntax methods: Depending on the option button selected, the "ONSUBMIT" script sets the xhitlist_x parameter to the correct syntax.

The sample script below shows how to assign the contents of the "Query" element to the xhitlist_q parameter. It also shows how to set the query syntax. The script assumes that it is called when the "onSubmit" event is triggered.

<form name="query" action="/nxt/gateway.dll" method="GET">
  <input type="text" size="15" name="xhitlist_q"/>
  <input type="submit" class="button" value="Search"/>
  <input type="hidden" size="0" name="f" value="xhitlist" />
  <input type="hidden" size="0" name="xhitlist_x" value="Simple" />
  <input type="hidden" size="0" name="xhitlist_s" value="relevance-weight"/>
  <input type="hidden" size="0" name="xhitlist_d" value=""/>
  <input type="hidden" size="0" name="xhitlist_hc" value=""/>
  <input type="hidden" size="0" name="xhitlist_xsl" value="xhitlist.xsl"/>
  <input type="hidden" size="0" name="xhitlist_vpc" value="first"/>
  <input type="hidden" size="0" name="xhitlist_sel" value="title;path;relevance-weight;content-type;home-title" />
</form>

Turn off caching when developing a search form: When developing search forms you want to be able to view the results of your changes quickly. The NXT 4 install configures the server so that templates are cached in memory. Each time you modify a template you must bring down the Web server to force NXT 4 to reread the template from disk so you can test the results of your modifications.

To turn off caching, modify the siteview.ini file (in the NXT 4 bin directory) to specify Cache=0 in the [FILECACHE] section. Specifying this option causes NXT 4 to reread templates from disk any time they are changed. Because NXT 4 never frees templates from memory, you should restart your Web server after a significant number of changes to your templates.

When you are done designing the site, change siteview.ini to the originial Cache=1 to allow for caching.

Adding Your Custom Search Form

To use your custom seach form, you must add it to your site by performing these steps:

Create the form.
Save it in the ../NXT 4/Online Server/Templates/Enu directory.
Use Content Network Manager to add it to the site.

SmartSearch components

NXT 4.12.2 gives you an opportunity to make your search simpler, more vivid and convenient. You can customize your search forms and add dynamic elements to them. The SmartSearch feature includes the following components:

Type ahead: Displays a drop-down list of hints.
Query tree: Displays a tree of the current request.
Word list: Displays a list of possible variants for the term autocompletion.
Document counter: Displays a number of results for the current request.
Context help: Displays a context help for the current request.
Search button control: Enables or disables the Search button automatically.

For more information about adding SmartSearch components to your search forms, read Adding SmartSearch components.

Type ahead

The Type ahead component displays a drop-down list of hints. The drop-down list includes the hints of the following types: corrections of misprints, completion of the current term according to the context, possible keyword suggestions that are available at the current position. Those parts of your current request that contain available suggestions are displayed in the bold type.

Different lists of hints are formed for each cursor position in the input field.

The Type ahead component validates the correctness of your input data. If your request is valid and returns hits, the border of the input field is blue. The border of the input field is red in the following cases:

A request returns zero hits.
A request contains syntax errors.
A request is incomplete

Figure 1 shows the validation process of the input data in the search field.

Figure 1. The Type ahead component.

Query tree

The Query tree component displays the tree of the current request. You can see a number of hits for every term in the request in the parentheses. Those parts of the request that return no hits are displayed in red.

Figure 2 shows the query tree for the following search request: term or bem and cold or four.

Figure 2. The Query tree component.

Word list

The Word list component displays a list of possible variants for the term autocompletion. If you double click the term in the list, the selected term is pasted in the input field.

Figure 3 shows an example of the word list.

Figure 3. The word list component.

Document counter

The Document counter component displays a number of hits for the request.

Figure 4 shows a number of hits for the term and request request.

Figure 4. The document counter component.

Context help

The Context help component displays a context help for the request.

Figure 5 shows an example of the context help.

Figure 5. The context help component.

Messages in Context Help

As you type your request in the Folio Advanced Query form, you can see messages that advise you the possible continuation of your input. Table 1 shows possible user messages that are available in the Folio Advanced Query form.

Table 1. User messages in Context help

Message	Description
`The query syntax is invalid. To complete the query, remove the text after the following position: %1`	You have an error in your query. Delete a part of your query after the specified position. `%1` is a position number of the symbol after which you must delete a part of your query. Spaces are treated as symbols.
`The query syntax is invalid, check the following position: %1. To complete the query, remove text after this position and type:[suggested_variant]`	You have an error in your query. Verify that a part of your query after the specified position is correct. You can use a suggested variant for your query after the specified position. `%1` is a position number of the symbol after which you must verify the syntax. Spaces are treated as symbols.
`The query syntax is invalid. Delete a query, and type the query again.`	The beginning of your query is incorrect. Verify the syntax and the structure of the query.
`The query is incomplete. To complete the query, type:[suggested_variant]`	You did not finish your query. You can use a suggested variant to complete your query.
`Start typing your query`	You can start typing your query. The default message when the search form is empty.
`Type a [suggested_variant]`	You can use a suggested variant to continue your query.
`or`	You can select the continuation of the query among the suggested variants. Possible variants are joined by the `or` conjuction.

Table 2 shows the terms that are used in user messages from Table 1.

Table 2. Terms that are used in user messages

Message	Description
`term`	Words or phrases that compose your search query. You can use a single word as a term, or a number of words. For example, the `cat dog` query performs a search for two terms: `cat` and `dog`.
`field_name`	A name of the field in which you want to perform a search.
`keyword`	A special word that is reserved by the search syntax. For example, the `cat and dog` query performs a search for two terms (`cat`, `dog`) that are joined by the union operator (`and`). As a result of this query, you have a hit list with documents that contain both `cat` and `dog` terms.
`rank_value`	A value for the `Rank` parameter. For more information about the ranked search, read the Ranked search topic.
`weight_value`	A value for the `Weight` parameter. For more information about the weight of an item in a ranked query, read the Setting the Weight of an Item in a Ranked Query section in the Ranked search topic.
`proximity_operator`	A value for the proximity search. For more information about the proximity search, read the Proximity search topic.
`field_contents`	A search query that you want to perform in the specified field.
`weight_contents`	A search query for which you set the `weight_value` parameter. For example, in the `[rank 100][weight 200: cat dog] mouse`, the `cat dog` part is `weight_contents`.
`domain_value`	A name of the domain in which you want to perform a search.
`query`	A set of keywords, terms, and special symbols that are available in the syntax. For example, `cat and dog` is a query.
`or_operand`	The logical OR operator. The `cat or dog` request returns documents with either `cat` or `dog` terms.
`and_operand`	The logical AND operator. The `cat and dog` request returns documents with both `cat` and `dog` terms.
`not_operand`	The logical NOT operator. The `not cat` request returns documents that do not contain the `cat` term.
`xor_operand`	The logical XOR operator. The `cat xor dog` request returns documents with either the `cat` term or the `dog` term, but not both terms.
`less_operand`	The operand for the less than comparison operation (`<`).
`greater_operand`	The operand for the greater than comparison operation (`>`).
`less_equal_operand`	The operand for the less or equal comparison operation (`≦`).
`greater_equal_operand`	The operand for the greater or equal comparison operation (`≧`).
`domain_contents`	A name of the domain in which you want to perform a search. For example, consider the following query: `[rank 100][domain: domain_contents] cat or dog`. You can set `domain_contents` only in ranked queries.
`prox_val`	A value for the `proximity` parameter. You can use the ordered proximity (`/`), or the unordered proximity (`@`). For more information about the proximity search, read the Proximity search topic.
`date_value`	A value for the `date` parameter.
`time_value`	A value for the `time` parameter.

Note: You can apply the following operands only to date and numerical fields: less_operand, greater_operand, less_equal_operand, greater_equal_operand. Consider the following query: [field capacity: > 10 < 12]. If you use a comparison operator (<, >, ≦, ≧), you must continue your query with the corresponding operand.

Note: The work of Context help is valid only when data-content-type="query" and data-syntax="advanced". For more information about adding SmartSearch components, read the Adding SmartSearch components topic.

Search button control

The Search button control component disables or enables the search button. In most cases, the search button is enabled. The component disables the search button in the following cases:

Request returns zero hits.
Request contains syntax errors.
Request is incomplete.

Figure 6 shows the disabled search button.

Figure 6. The search button control component.