"Status" contains the status code choices (Open, Finished, and Approved)
The QuerySyntax field is a computed field that contains this formula:
rem "Replace the spaces in the AssignedTo field with plus signs";
AssignedToNP := @ReplaceSubstring (AssignedTo; " " ; "+");
"FIELD+AssignedTo+CONTAINS+" + AssignedToNP +
"+AND+FIELD+Status+CONTAINS+" + Status
The formula will produce a full-text query that can be passed to Domino by way of a URL. The spaces are replaced with plus signs because a URL cannot contain spaces.
The $$Return field on this search form will calculate a URL that executes the search, using the query we calculated in QuerySyntax. The syntax for a search executed via a URL is:
http://HostOrIPAddress/directory/database.nsf/ViewToSearch?SearchView&Query=
QuerySyntaxSeparatedByPlusSigns
What follows the &Query= can be just a word, or it can be a more complex query like the one our QuerySyntax formula will generate. Here is the $$Return formula:
"[/" + ThisDBWR + "/ActionItemsSortable?SearchView&Query=" + QuerySyntax + "]"
The left and right brackets tell Domino that the formula contains a URL for redirecting users. Without brackets, a $$Return formula is interpreted as HTML to display to users. The redirect capability lets you do things like return users to a view after they submit a document. In our case, the URL we are redirecting users to contains the syntax for a query, so Domino receives that URL, processes the query syntax, and then returns the search results.
ThisDBWR is a computed field that contains the name of the database to search. We defined ThisDBWR on a subform called "Config" and inserted it at the top of our form. We do it this way for reusability, to avoid hard coding a database name. But, you could just as easily include the database path and file name within the quotes. Here is the formula for ThisDBWR:
@ReplaceSubstring (@Subset (@DbName; -1); "\\"; "/")
Any spaces in the database name are replaced by plus signs, and any backslashes in the path name are replaced by a forward slash.
The following two screens show a user filling out the Simple Ad-hoc Web Search form, and then the search results that Domino returns:
Notice the URL at the top of the browser for this search results page. It doesn't all fit in the screen shot because it's so long, but you can see the full-text search syntax we generated and passed to Domino on the URL. You can try this query in the Action Items Filtering database by clicking "Simple Ad-hoc Search" from the home page. Incidentally, you could execute the search by typing the search URL at the top of the browser. Not that you'd ever want to, but this may help you understand how Domino is receiving the URL and processing your search based on what it contains. (This would also be useful for editing your previous search.)
Recombinant Capital, a research firm in the biotech industry, has designed an excellent example of an ad-hoc Domino search form that is freely available. Click here and then click on their search builder link, which opens a form where you can run ad-hoc queries against ReCap's biotech alliances database.
Note: Many Web applications return a search URL when you do a search. You can study the URL and often make sense of its syntax, and then build in links to other sites from your own applications. For example, you might add a "See a Map for this Customer" link to a Customer form on your own intranet contact management system, and generate a search URL to a mapping site like zip2.com or mapquest.com. For example, here is a URL to draw a map to 1600 Pennsylvania Avenue in Washington DC.
Creating your own search results page
One problem with the search results page in the above example is that it contains an editable field at the bottom with the syntax that generated the query. The idea here is that the user can easily modify the query and run another search. This works fine for simple queries that the user types in from the standard search form, but it is confusing when you've generated the query syntax for them. So the next step is to create our own search results page. The search results come back as shown above unless you include a form called $$SearchTemplateDefault. An example is shown here:
The "Return to Home Page" and "Do Another Search" links give the user some navigational choices at the top of the results page. The $$ViewBody field is a simple editable field with no formula. It will display the actual search results in the format of whatever view the search was executed against.
The Count field gives us a way of tallying how many hits there were in the search. The number of hits is shown on the Domino default search results page, but Domino doesn't make the value available to us if we use a $$SearchTemplate form, so we need a way to tally it ourselves. There may be better ways of doing this, but the one we've come up with -- credit on this technique goes to Andy Broyles of Replica Inc. -- uses JavaScript to return the number of links on the page. Count is a computed-for-display field with this formula:
"<script>document.write(document.links.length-2 + \" documents found\") </script>"
Notice that we subtract 2 from the document.links.length, because we have two navigational links at the top of the form. This formula is simply counting the links on the search results page.
When we run a search after creating our $$SearchTemplateDefault form, we get these results:
Multi-valued searches
So far, we've got a pretty decent search form. But if you use it, you'll notice a pretty big limitation: we have no capability for multi-value search criteria. We can search for Open action items assigned to Larry Bird, but have no way of searching for either Open or Finished action items assigned to either Larry Bird or Reggie Miller.
This is where the list processing capabilities of the Notes formula language really shine. In the form "Web Search 2 - Multi-value Fields" (alias WebSearch2), we've added the multiple value capability:
Notice that the AssignedTo field shown above is a multi-value field. Notice also in the keyword formula that we are adding "Include All Assignees" to the front of the list of assignees we retrieve from the database. This way, the user can check off multiple assignees or just check "Include All Assignees" if they want all assignees included.
Because the formula to generate the query syntax is more complicated on this form, we break it into separate syntax fields for readability. We have the AssignedToSyntax field and the StatusSyntax field, which we combine to produce the QuerySyntax.
Here is the formula for AssignedToSyntax:
rem "If they chose to include all, our syntax is NULL, because we don't want to restrict by assignees at all in that case.";
rem "Otherwise, we use list processing and implode each FIELD AssignedTo with an OR";
vlist :=
@If (
@IsMember ("Include All Assignees"; AssignedTo);
NULL;
"FIELD AssignedTo = " + AssignedTo
);
@Implode (vlist; " OR ")
If the user selects "Include All Assignees," we don't want any "FIELD AssignedTo =" restrictions at all. Our search query won't include any reference to assignees. The If statement handles this pretty easily.
Processing multiple assignees, on the other hand, seems like it might be a difficult syntax to generate, but the power of Notes list processing makes it easy. The statement "FIELD AssignedTo = " + AssignedTo in the above formula automatically produces a list if AssignedTo contains multiple values. The list that is produced looks like this:
"FIELD AssignedTo = 'Dan Marino'": "FIELD AssignedTo = 'Reggie Miller'"
The next statement in the formula, @Implode (vlist; " OR "), turns the list into a single string value, putting an "OR" in between each value in the list. So, whether the user picks one assignee or five, the result is an "OR" in between each "FIELD AssignedTo = 'X'".
The formula for StatusSyntax is simpler, because we don't give the user a checkbox labeled "All Status Codes" -- they can just select all three boxes (Open, Finished, and Approved) if they want all action items included. Our formula needs to only include the @Implode (vlist; "OR") processing. The StatusSyntax formula looks like this:
vlist := "FIELD Status = " + Status;
@Implode (vlist; " OR ")
The QuerySyntax field combines AssigneeSyntax and StatusSyntax, replacing all spaces in the end result with plus signs for use on a search URL:
REM "Put the two criteria together in a list";
slist := AssignedToSyntax : StatusSyntax;
REM "Implode and explode again to get rid of any empty entries";
slist2 := @Explode ( @Implode (slist; "~"); "~");
REM "Put parentheses around each item in the list";
REM "This ensures that the ANDs and ORs get the right order of precedence.";
ListWithParen := "(" + slist2 + ")";
sstring := @Implode (ListWithParen; " AND ");
REM "Replace any spaces with plus signs";
@ReplaceSubstring (sstring; " "; "+")
The $$Return field uses QuerySyntax in the same way that it did on our simple search form. Here is how the multi-value search form looks when presented to the user. In this example, we pick two assignees and two status codes:
And here's the search results that Domino returns:
Notice that this URL produced the results:
http://localhost/directory/filename.nsf/ActionItemsSortable?SearchView&Query=
(FIELD+AssignedTo+=+Dan+Marino+OR+FIELD+AssignedTo+=+Reggie+Miller)+AND+
(FIELD+Status+=+Open+OR+FIELD+Status+=+Finished)
There are a few other things we can do to improve our ad-hoc search capabilities and the way our search results are displayed. One improvement we can make is to generate an English-like description of the user's query. The above query might be described as "Assignees (Dan Marino or Reggie Miller) AND Status (Open or Finished)." We could display the description at the top of the search results page. We could also store user queries with the descriptions included as documents so that the users could open and re-run those queries later.
For more information on the English descriptions and other ad-hoc techniques, see my earlier Iris Today article, Adding a Friendly Ad-hoc Query Tool to Domino Applications. This article focused on building ad-hoc query forms for Notes clients rather than Web browsers. The Action Items Filtering database also includes the design examples from that earlier article. See the "Custom Query - Notes" form and the Custom Queries view to see search queries that have been run and saved from Notes clients. (If you include a computed field called SaveOptions with the formula "0", the search documents are not saved. Otherwise they are saved, and you can create a prior searches view that lists them for reuse.)
Now, try Technique #2: Drill-down Views.
Copyright 1998 Iris Associates, Inc. All rights reserved.
