Sun Java System Web Server 6.1 SP7 Programmer's Guide to Web Applications

JSP Search Tags

Sun Java System Web Server includes a set of JSP tags that can be used to customize the search query and search results pages in the search interface. This section describes the tags and how they’re used. For more information about using the search feature, see the Sun Java System Web Server 6.1 SP7 Administrator’s Guide.

The search tag library is packaged into the install_dir/bin/https/jar/webserv-rt.jar file, which is always on the server classpath. The sun-web-search.tld tag description file can be found in the install_dir/bin/https/tlds directory, and can be copied into the WEB-INF directory of your web application.

The search tags are as follows:

Note –

The Sun Java System Web Server search feature is i18n compliant, and supports multiple character encoding schemes in the same collection. Custom JSPs that expose search can be in any encoding.

<searchForm>

Function

Constructs an HTML form that contains default and hidden form elements such as the current search result index and number of records per page by default. The default names for the form, index, and number of records are searchform, si, and ns.

Attributes

Name. Specifies the name of the form. The default is searchform. The name of a form is the identifier for all other tags.

Action. (optional) Specifies the form action.

Method. (optional) Specifies the method of submission, GET or POST. The default is GET.

elemStart. (optional) Specifies the name of the hidden Start element. If not specified, the default "si" will be used.

Start. (optional) An integer indicating the starting index for displaying the search result. The default is 1.

elemNumShown. (optional) The name of the nShown element. If not specified, the default "ns" is used.

numShown. (optional) An integer indicating the number of results to be shown per page. The value of the attribute will be retrieved by requesting parameter elemNumShown. The default is 10.

Usage

<s1ws:form action="results.jsp" >
...
</s1ws:searchForm>

This creates an HTML form tag <form name="searchform" action="results.jsp" method="GET"> along with two hidden inputboxes:

A hidden inputbox for starting index named "si" with a value from the "si" parameter or default 1, and
A hidden inputbox for number of records per page named "ns" with a value from the ns parameter or default 20.

<CollElem>

Function

Creates a hidden inputbox or select box, or multiple checkboxes depending on the attribute input. If there is only one collection, the tag creates a hidden inputbox by default.

Attributes

Name. Specifies the name of the form element created. The default is "c."

items. (optional) A comma-delimited string representing search collections available. The tag retrieves all collections available on the server if the attribute is empty.

Type. (optional) The type of form element used for displaying collections. Valid options are hidden, select, and checkbox. If there is only one collection, the default value is hidden else the default value is checkbox.

Rows. (optional) Represents size if type is select, or number of rows if checkboxes. The default behavior is to satisfy the Cols attribute first. That is, the collections will be listed in columns as specified by the Cols attribute.

Cols. Represents number of columns and is only required if type is checkbox. If Cols and Rows are not specified, the collections will be listed horizontally, that is, in one row.

Defaults. Specifies a comma-delimited string containing 1s or 0s indicating the selection status of the search collections. An item is selected if 1, and not selected if 0. If there is a form action, these values will be retrieved from the form elements.

cssClass. (optional) The class name that will be used in every HTML tag created in this tag. This is particularly useful when the type is checkbox, since an HTML table will be used for the layout. See the sample code below for details.

Usage

<s1ws:collElem type="checkbox" cols="2" values="1,0,1,0" cssClass="body" >

This creates checkboxes in 2 columns with a default name "c," with the first and third items selected. Fonts and any other HTML styles are defined in css classes "body," which includes tr.body, td.body, and input.body.

<collection>

Function

Retrieves the name of search collections on the server, and iterates through and passes each of them to the collectionitem tag. Users may choose to use this tag along with collection item tags so they can write their own HTMLs.

Attributes

items. (optional) A comma-delimited string representing the search collections available. The tag retrieves all collections available on the server if the attribute is empty.

Usage

<table border=0>
<s1ws:collection>
<tr><td><input type=checkbox name="c" 
value="<s1ws:collItem property="name" >">
<s1ws:collItem property="display name" >
</td></tr>
</s1ws:collection>
</table>

The above code will display all collections with checkboxes.

<select name=elementname>
<s1ws:collection>
<option value="<s1ws:collItem property=\"name\" >">
<s1ws:colleItem property="display name" >
</s1ws:collection>
</select>

This iterates through the available collections and passes each item to the collection item tag, which in turn displays the name and display name of the item.

<colIItem>

Function

Displays the name and label of one collection item. Must be used inside the collection tag.

Attributes

property. Specifies a keyword indicating which property the tag should output. Valid inputs include name, display name, and description. Default is name.

Usage

<select name=elementname>
<s1ws:collection>
<option value="<s1ws:collItem property=\"name\" >">
<s1ws:collItem property="display name" >
</s1ws:collection>
</select>

This iterates through the available collections and passes each item to the collection item tag, which in turn displays the name and display name of the item.

<queryBox>

Function

Creates an inputbox.

Attributes

name. (optional) The name of the inputbox. The default is "qt."

default. (optional) The default value for the query box. If the form is submitted, its value will be set using what has been submitted.

size. (optional) The size of the inputbox. The default is 50.

maxlength. (optional) The maxlength of the inputbox. The default is 50.

cssClass. (optional) The CSS class.

Usage

<s1ws:queryBox size="30" >

This creates an inputbox with default name "qt" and size=30.

<submitButton>

Function

Creates a submit button.

Attributes

name. (optional) The name of the button. The default is "sb."

default. (optional) The default value of the button, which will be "search."

cssClass. (optional) The CSS class name.

style. The CSS style.

image. The optional image for the button.

Usage

<s1ws:submitButton cssClass="navBar" style="padding: 0px; margin: 0px; width: 50px">

This creates a submit button with default name "sb."

<formAction>

Function

Handles form action. It retrieves all elements on the search form. It validates that there is at least one collection selected and the query is not empty. After validation, it passes the values on to search and results tags as parent or through the page context.

Attributes

formId. Specifies the name of the form. If not specified, the default form "searchForm" will be used.

elemColl. (optional) The name of the Collection element. The default name "c" is used.

elemQuery. (optional) The name of the Start element. The default name "qt" is used.

elemStart. (optional) The name of the Start element. The default name "si" is used.

elemNumShown. (optional) The name of the numShown element. The default name "ns" is used.

Usage

<s1ws:formAction >

<formSubmission>

Function

Tests if the form submission is successful.

Attributes

formId. Specifies the name of the form in question. It must be the same as that for <formAction>.

success. Indicates if the form submission is successful. The values true or yes represents successful action. All other inputs will be rendered as failure.

Usage

<s1ws:formSubmission success="true" >
         <s1ws:search>
         ...
   </s1ws:formSubmission>

<formActionMsg>

Function

Prints out an error message from formAction, if any.

Attributes

formId. (optional) Specifies the name of the form in question. If not specified, the default id is "searchForm."

elem. (optional) Specifies the name of the element. Valid inputs are "query" and "collection." When specified, the tag returns an error message, if any, regarding the element. Otherwise, it prints out all of the error messages generated.

Usage

<FormActionMsg elem="query">

This tag will display a message "query text not specified" if a query is not submitted.

The message is printed from the form action where the tag is placed.

<Search>

Function

Executes a search query and returns search results. The search tag retrieves a query string and collection(s) from either a form parent tag or the query and collection attributes. The search results are saved in the page context with a page or session scope.

Attributes

formId. Specifies the name of the form used for the search. The default form will be used if the attribute is left empty. If this tag is used without a form, this attribute must be set to provide an identifier for the resultIterate tag.

Collection. (optional) A comma-delimited string representing collection(s) used for a search. If there is a form action, this attribute is ignored and the values are retrieved by requesting the collection element.

Query. (optional) Specifies the query text. If not provided, it is retrieved from the query element.

Scope. Specifies an integer indicating the scope of the search results. The value 1, which is the default, indicates page scope, and 2 indicates session scope.

Usage

<s1ws:search >

This search tag uses the default parameters and executes a search. The search results will be saved in pageContext with a page scope.

<s1ws:search Collection="col1, col2" Query="Java Web Service" scope="2" >

This search tag will execute a search in col1 and col2 using "Java Web Service" as the query string. The search results will be saved in pageContext with a session scope.

<resultIteration>

Function

Retrieves the search results from either the parent search tag or the page context. The tag is responsible for iterating through the results and passing the searchitems to the item tags.

Attributes

formId. Specifies the name of the form associated. The default form will be used if the attribute is left empty. If this tag is used without a form, this attribute must be set as a reference to the search tag.

Start. Specifies an integer representing the starting position in the search results. The default is 0. The value is retrieved from the parent <formAction> tag or pageContext, or the parameter value.

numShown. Specifies an integer indicating the number of results to be shown in one page. The default is 20. The value is retrieved from the parent <formAction> tag or pageContext.

<Item>

Function

Retrieves a searchitem from the Results parent tag and outputs its properties as specified by the property attribute.

Attributes

Property. Specifies a case-sensitive string representing field names in a search item, such as title, number, score, filename, URL, size, and date.

<resultStat>

Function

Returns numbers indicating number of records returned and the range currently displayed.

Attributes

type. Specifies the type of statistics data. Valid inputs are "start," "end," "range" (for example, 1-20), and "total."

<resultNav>

Function

Creates a navigation bar.

Attributes

type. Specifies the type of navigation bar. Valid inputs are "full," "previous," and "next." A full navigation bar looks like this: previous 1 2 3 4 5 6 7 8 9 10 next, where 5 is currently selected. The number of "page number" links is determined by the "offset" attribute and the number of pages available.

caption. Only necessary if type is previous or next and the default text is not wanted. Caption can be any HTML.

offset. Specifies the number of page links around the selected page. For example, if offset=2, the sample bar above would look like this: previous 3 4 5 6 7 next . Only required for type "full."