APPLICATION DESIGN


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:


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 argumentsDescriptionDefault Value
QueryThe search stringnone
SearchMaxMaximum number of entries to return in total; 0 = no limitNone. Note that

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

SearchWvInclude word variants: TRUE or 1 or FALSE or 0FALSE
SearchOrder1 = by relevance

2 = by date ascending

3 = by date descending

4 = use view order (SearchView only)

1
SearchThesaurusUse thesaurus synonyms: TRUE or 1 or FALSE or 0

(This option is ignored by the R5 search engine)

FALSE
SearchFuzzyUse fuzzy search: TRUE or 1 or FALSE or 0FALSE
SearchEntryName of form to use for each result entry

(for SearchDomain only)

"ResultEntry"
StartStart document for paged results; 0 = unpaged0
CountNumber to return for paged results; 0 = unpaged0
ScopeScope of search:

1 = notes databases only

2 = filesystem only

0 = both

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

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

The "Add Search" button that appears beside 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 FieldItem 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

Search results are displayed using the SearchResults, ResultEntry, and the DetailedResultEntry form. The SearchResults form defines the layout of each page of results. The ResultEntry and DetailedResultEntry forms define the format of a single result within that page, and are repeated for each result returned. On the Web you specify the name of this form through the SearchEntry field/argument. The fields below are for the ResultEntry and DetailedResultEntry forms.

Field NameDescription
DSCreationTimeCreation time of a document
DSModifiedTimeModification time of a document
DSURLURL to document
DSDBTitleDatabase title
DSDocSummaryDocument summary
DSDocTitleDocument title
DSDocAuthorDocument author
DSScoreRelevance score
DSSServerName 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 Lotus SmartSuite® or 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 below 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 nameField requiredComments
$$SearchTemplate for viewname$$ViewBodyAssociates 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$$ViewBodyDomino 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 below. 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.

FieldDescription
QuerySearch string used
StartStarting document number
CountNumber of results requested for this page
HitsActual 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.
TotalHitsTotal number of hits found by the search.
SearchMaxMaximum 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 table below are available for use with the Start and Count parameters and should be added to the results form as needed.
FieldDescription
HitsThe actual number of hits returned. This field is useful in determining the Start parameter of Next.
TotalHitsThe total number of hits found without regard to the number of pages.

See Also