Customizing search forms

The Search utility lets users find information within a single application or an entire domain. You can customize search forms to suit organization-specific needs. An application developer can, for example, add a corporate logo to either form, or rearrange the fields.

You can also add custom forms to individual databases to customize Web searches within a single database.

For more information on setting up search for an individual application, see To create a full-text index for a database. For more information on setting up domain search, see Domino® Administration Help.

To customize the forms you can:

  • Create a database based on the Catalog (R5.0) template on the Domino server you are using for domain search.
  • Copy the forms into the domain catalog database on the Domino server you are using for domain search.

Customizing search input forms

For domain search, the Notes® client uses the form named DomainQuery in the catalog server's catalog.nsf database as the search form. This form uses the FTDomainSearch method to implement the search. Web domain searches can use any form through an OpenForm URL command and build and invoke a SearchDomain URL command to perform the search, supplying arguments either as URL command arguments or through posted field values.

Single database searches over the Web can be initiated using a $SearchForm?SearchView URL command. In this case Domino looks in the current database for a form with the actual name or the alias name $$Search. If the form exists, Domino opens it; otherwise, Domino displays a default search form based on the search.h file stored in the Domino\Icons directory. The $$Search form builds and invokes a SearchView URL command to perform the search, supplying arguments either as URL command arguments or using posted field values. You can also customize the default search.h form.

Refer to the following table if you are customizing a search form for use on the Web. The table lists the URL command arguments used to drive the initial search through the SearchDomain or SearchView URL. These values are available on the results page for use by buttons and hotspots on the results form. For example, you may specify &SearchOrder=2 on your initial search form. The field SearchOrder will have a value of two in the results page. A Next button on the results form can use this value for the next page or override it by specifying something else.

Although TRUE and FALSE can be specified for some of the fields, when the values are carried over onto the results page they are 1 or 0.

Optional arguments

Description

Default Value

Query

The search string. For more information, see "Refining a search query using operators" in the Notes client help.

none

SearchMax

Maximum number of entries to return in total; 0 = no limit

None. Note that

default and maximum SearchMax values can be configured for the Web server through settings in the Domino Directory.

SearchWv

Include word variants: TRUE or 1 or FALSE or 0

FALSE

SearchOrder

1 = by relevance

2 = by date ascending

3 = by date descending

4 = use view order (SearchView only)

1

SearchThesaurus

Use thesaurus synonyms: TRUE or 1 or FALSE or 0

(This option is ignored by the R5 search engine)

FALSE

SearchFuzzy

Use fuzzy search: TRUE or 1 or FALSE or 0

FALSE

SearchEntry

Name of form to use for each result entry

(for SearchDomain only)

"ResultEntry"

Start

Start document for paged results; 0 = unpaged

0

Count

Number to return for paged results; 0 = unpaged

0

Scope

Scope of search:

1 = notes databases only

2 = filesystem only

0 = both

0

If you are customizing search forms for Notes clients, you must use the FTDomainSearch method.

Searching for Header Information (search by Date Created or Modified)

The "Add Search" button that appears with the full text search entry area in agents lets you search for documents "by date created" and "by date modified". To write such queries yourself for use with the FTSearch method, you can use the following special item names:

Header Field

Item name

CREATION DATE

_CreationDate

REVISION DATE

_RevisionDate

DB TITLE (domain index only)

_Title

DB CATEGORIES (domain index only)

DbCategories

NOTE TITLE

_Note_Title

AUTHOR

_Note_Author

For example, to find all documents created before 5 January 2000, use the following query:

[_CreationDate] < 01/05/2000

There are no field names stored in the document; the dates actually come from the document's header, not from fields. So you can use these reserved names with any document, even though they won't appear among the field items in the Document Properties dialog.

There is no syntax corresponding to the search builder functions to find documents based on a difference from today's date, for example -- "is in the last n days". Your agent will have to supply actual dates at runtime (which it can calculate by adjusting today's date). Keep in mind that date formats vary based on user settings, and you must use a format that matches the workstation or server that will evaluate the query.

Customizing Domain search results forms

Field Name

Description

DSCreationTime

Creation time of a document

DSModifiedTime

Modification time of a document

DSURL

URL to document

DSDBTitle

Database title

DSDocSummary

Document summary

DSDocTitle

Document title

DSDocAuthor

Document author

DSScore

Relevance score

DSSServer

Name of the server that the document was indexed on

DSType

"0" indicates a Notes document, "1" indicates an external or file system document

You can name your results form whatever you want and then specify your chosen name in the SearchDomain URL or to the FTDomainSearch LotusScript® call. The Web will look for a form named $$SearchDomainTemplate if you don't name one in the URL.

When designing or viewing a Domain Search results form, it can be helpful to know where the Domain Indexer finds the titles that it displays in the results. The Indexer checks each document for the following Notes fields or items, in the order they are listed here, to use to represent the document's title: Title, Subject, Headline, and Topic field; window title (as designated by the developer of that Domino application); and view summary (using the default form and default view). If none of these items can be found, the Domain Indexer displays "Document has no title" in the results.

In file systems such as Microsoft™ Office, the title and author are extracted from the document properties fields. For HTML files, TITLE and AUTHOR tags are used.

How SearchResults and ResultEntry/DetailedResultEntry are used

The LotusScript shown is attached to the click event of the Search action hotspot used by the Notes client on the search form. The lines that call the name of the results form and the result entry form are bold.

Sub Click(Source As Button)
	Dim s As New NotesSession
	Dim db As NotesDatabase
	Dim w As New NotesUIWorkspace
	Dim uidoc As NotesUIDocument
	Dim q As String
	Dim l As Integer
	Dim d As Integer
	Dim sort As String
	Dim stype As Integer
	Dim useint As Integer
	Dim rtype As String
	Dim rformname As String
	Set db=s.CurrentDatabase
	Set uidoc = w.currentdocument
	uidoc.refresh
	Set doc=uidoc.Document
	
	q=doc.query(0)
	l=doc.resultlimit(0)
	d=doc.MaxDisplay(0)
	sort = doc.sort(0)
	usestr = doc.use
	sscope=doc.searchscope
	rtype=doc.GetItemValue("SearchType")(0)
	
	If rtype = "1" Then


		rformname="DetailedResultEntry"	Else
		rformname="ResultEntry"	End If
	
	Select Case sort
	Case "R"		stype = FT_SCORES
	Case "O"		stype = FT_DATE_ASC
	Case "N"		stype = FT_DATE_DES
	End Select
	
	Forall values In usestr
		If values = "2" Then useint = useint + FT_STEMS
		If values = "3" Then useint = useint + FT_FUZZY
	End Forall
	
	Forall values In sscope
		If values = "1" Then useint = useint + FT_DATABASE
		If values = "2" Then useint = useint + FT_FILESYSTEM
	End Forall
	
	On Error Resume Next   
	If db.isopen Then
		If Err <> 0 Then
			Messagebox STR_DBOPEN_ERROR
			Err = 0
			Exit Sub
		End If
		
		Set srdoc = db.ftdomainsearch(q, l, stype,useint, 0,d,rformname)
		If Err <> 0 Then
			Messagebox STR_FTERROR_PREFIX & Error$, 0 , STR_ERROR
			Err=0
			Exit Sub
		End If
		srdoc.Form="SearchResults"		Call w.EditDocument(False, srdoc, True)
	End If
End Sub
Tip: You must select the "Generate HTML for all fields" option in the Form properties box to preserve field values when data is passed between a Web browser and the server.

Customizing Web SearchView results

To customize the Web Search Results page for SearchView:

  1. Create a form and assign it one of the form names shown in the following table.

    Form name

    Field required

    Comments

    $$SearchTemplate for viewname

    $$ViewBody

    Associates the form with a specific view. Domino requires the $$ViewBody field, but ignores the value. The form name includes viewname, the alias for the view, or, when no alias exists, the name of the view. For example, the form named "$$SearchTemplate for All Documents" associates the form with the All Documents view.

    $$SearchTemplateDefault

    $$ViewBody

    Domino requires the $$ViewBody field, but ignores the value. This form is the default for all Web searches that aren't associated with a specific form.

  2. Add a field named $$ViewBody to the form.
  3. If you want to display results page-by-page, add buttons or hotspots for forward and backward navigation to the form.
  4. Use the Start and Count parameters in your URL command.

For more information on URL commands, see Programming options for Web applications.

Using navigational buttons for paged results

To make it possible to navigate forward and backward between pages of results, add buttons or hotspots to the SearchResults form. The fields available for use with next and previous buttons are listed in the table shown. In the Notes client, the buttons should reinvoke the LotusScript FTDomainSearch function with revised arguments. On the Web, they should be used to construct a new SearchDomain URL to fetch a new set of results.

Note: If you use editable fields on a search result form, select the option "Web Access: Use JavaScript™ when generating pages," in the Database properties. If selected, a URL attached to a hotspot or button will be computed on the click event. If it is not selected, the URL will be computed when the page is loaded.

Field

Description

Query

Search string used

Start

Starting document number

Count

Number of results requested for this page

Hits

Actual number of results returned this page, which may be less than Count requested. This field is useful in determining the Start parameter for a Next button.

TotalHits

Total number of hits found by the search.

SearchMax

Maximum number of entries to return in total; 0 = no limit.

SearchWv (only for URL command)

Include word variants: 1 or 0.

SearchOrder (only for URL command)

1 = by relevance 2 = by date ascending 3 = by date descending

4 = use view order (SearchView only)

SearchThesaurus (only for URL command)

Use thesaurus synonyms: 1 or 0.

SearchFuzzy (only for URL command)

Use fuzzy search: 1 or 0.

SortOptions (only for Notes client)

FT_SCORES = by relevance FT_DATE_ASC = by date ascending FT_DATE_DES = by date descending

OtherOptions (only for Notes client)

FT_STEMS = Include word variants FT_FUZZY = Use fuzzy search FT_DATABASE = search databases FT_FILESYSTEM = search file systems

SearchEntry (Domain Searches only)

Name of the result entry form used.

SearchView (only for SearchView URL command)

Text unique identifier of the view being searched. This identifier is useful in building subsequent SearchView URL commands.

Scope (only for SearchDomain URL command)

Scope of search: 1 = notes databases only 2 = file system only 0 = both

The fields in the following table are available for use with the Start and Count parameters and should be added to the results form as needed.

Field

Description

Hits

The actual number of hits returned. This field is useful in determining the Start parameter of Next.

TotalHits

The total number of hits found without regard to the number of pages.