Compass Server 3.0 Developer's Guide

[Contents] [Previous] [Next] [Last]

Chapter 5
Opening the End User Page With Query String URLs

You can invoke the Compass Server End User Page by opening a URL that has a query string appended. This section describes how to do this, and discusses some of the uses.

Attributes for Query String URLs

 This section lists the attributes you can use in the query string. The section Using Forms to Submit Searches discusses how to use forms to submit query strings URLs to the Compass Server.

ui

Selects the mode of the End User Page, which is either browse or search-results. The default is bw, which is the same as browse. The value can be:

bw
browse
 
sr
 
search-results
 For example:

http://www.yourcompass.com/compass?ui=browse

view-template

 The name of the template to use. The default is normal. The value can be the main part of the name of any configuration file in the templates directory. For example:

http://www.yourcompass.com/compass?view-template=searchandbrowse

taxonomy

 The name of the taxonomy. This is the name of the top level category in the category tree.

The value can be any text string (which should specify an existing top level category if you want any results returned). There is no default.

browse-category

The category to browse. This is only applicable when UI is bw or browse. The default is the root category. For example:

http://www.yourcompass.com/compass?ui=bw&browse-category=netscape

scope

 The search criteria to search for. This is only applicable when UI is sr or search-results. There is no default. The following query string URL returns the results of searching for the string "netcaster."

http://www.yourcompass.com/compass?ui=sr&scope=netcaster

chunk-size

 The maximum number of hits to display per page. This value sets the limit for both the number of categories and number of documents listed per page. The default is 10, and the maximum allowable value is 2730. For example:

http://www.yourcompass.com/compass?ui=sr&scope=netcaster&chunk-size=8

page

 This is the number of the page to display. This is only applicable when UI is sr or search-results. For example, if a search yields 300 hits, and the chunk-size is 10, there will be 30 pages, so you could display the 15th page as follows:

http://www.yourcompass.com/compass?ui=sr&scope=netcaster&page=15

search-category

 This is the category to search. This is only applicable when UI is sr or search-results. The possible value can be any classification id, such as arts:music or netscape:netcaster. For example:

http://www.yourcompass.com/compass?ui=sr&scope=netcaster&search-category=netscape

Using Forms to Submit Searches

 As already mentioned, you can invoke the Compass Server End User Page by opening a URL that has a query string appended. Thus you can use forms to submit searches. These forms can appear on any page on your web site, so long as you give the form elements names that the Compass Server can parse.

To use a form to initiate a search, the form must have a METHOD attribute of GET, and its ACTION must be a URL to your Compass Server. The form must contain at least the following elements:

The form can contain any additional elements you like whose names correspond to attributes that the Compass Server can understand. For example, you could have a SELECT menu whose name is search-category that lists the categories that a user can search.

The following code shows a simple form that allows users to submit a search. This form can be placed on any web page. It will return the Compass Server UI page listing the results of the search.

<FORM METHOD=GET ACTION=http://your.host.com/compass>
 <INPUT TYPE=text NAME=scope>
 <INPUT TYPE=submit VALUE=Search>
 <INPUT TYPE=hidden NAME=ui VALUE=sr>
</FORM>
The following code creates a form that uses the "Search button" image that the Compass Server End User page uses. This form uses JavaScript so that it can specify an image as the button. 

<NOSCRIPT>This page requires JavaScript</NOSCRIPT>
<FORM METHOD=GET 
  ACTION=http://your.host.com/compass NAME=searchform>
  <NOBR>
  <INPUT TYPE=text NAME=scope>
  <A HREF="javascript:document.searchform.submit()">
    <IMG SRC=http://your.host.com//images/search.gif BORDER=0       ALIGN=ABSMIDDLE ALT=Search></A>
  </NOBR>
  <INPUT TYPE=hidden NAME=ui VALUE=sr>
</FORM>
 The following form also uses an image for its Submit button. It uses an INPUT tag whose type is image as the Submit button. This form does not require JavaScript. However, the <INPUT TYPE=image> tag does not take an ALT attribute, so it cannot specify alternative text for the image if the image does not appear.

<FORM METHOD=GET ACTION=http://your.host.com/compass>
 <INPUT TYPE=text NAME=scope>
 <INPUT TYPE=image VALUE=Search
     SRC="http://your.host.com//images/search.gif">
 <INPUT TYPE=hidden NAME=ui VALUE=sr>
</FORM>
If you want to include the Hints link, you can just add the link, as shown below.

<NOSCRIPT>This page requires JavaScript</NOSCRIPT>
<FORM METHOD=GET
    ACTION=http://your.host.com/compass NAME=searchform>
  <NOBR>
  <INPUT TYPE=text NAME=scope>
  <A HREF="javascript:document.searchform.submit()">
  <IMG SRC=http://your.host.com//images/search.gif
     BORDER=0 ALIGN=ABSMIDDLE ALT="Search"></A>
  <A HREF=http://your.host.com/ug/hints.htm>Hints...</A>
  <INPUT TYPE=hidden NAME=ui VALUE=sr>
  </NOBR>
</FORM>
 The file mysearch.htm shows examples of these forms in a separate window. The forms in this file use dummy names for the Compass Server, thus they do not return real results. However, if you copy the code and substitute the name of your Compass Server, the forms should work.

Optional Advanced Search Interfaces

Several of the pre-defined UI templates allow the user to choose a standard search view or an advanced search view. The standard view offers a single text entry field in which the user enters the string for which to search. The advanced view offers multiple fields that allow the user to express search criteria, and the user can also add more fields dynamically.

This functionality makes use of the ability to use forms to pass name/value pairs to CGI programs. In this case, the page contains links that re-display the page by submitting an invisible form that sends a query string URL specifying a view-template attribute to the Compass Server.

You can use this approach to allow users to choose different views of the page, such as a "standard" search view or an "advanced" search view.

You can create End User pages that allow the user to choose different views of the page by using a form that contains several hidden elements. The form should have one hidden element that indicates a UI template (also known as a view template), and another hidden element that indicates the category being browsed, as shown here:

<!-- The Search Switch Form --
the view-template MUST be the 0th element -->
<FORM METHOD="GET" ACTION="/compass" NAME="searchswitch">
<INPUT TYPE=hidden NAME=view-template VALUE="$$view-template">
<INPUT TYPE=hidden NAME=browse-category VALUE="$$browse-category">
</FORM>
 You should put this form in the search-results-top and browse-results-top pattern files.

The form doesn't really do anything, instead, it provides a mechanism for passing name/value pairs to a CGI program that redisplays the page. Each component of the page that includes this form needs to have a link, that, when pressed, invokes the form with the appropriate values of view-template and browse-category.

The value of the view-template attribute should be the UI template to use when the page is redisplayed. The value of the browse-category attribute should be the category to be browsed.

To invoke a form within a link, use javascript: to specify that the link is JavaScript code. Within JavaScript, you can use the submit() function to submit a specified form. However, in this case you need to change the value of the form' s 0th element (that is, the element named view-template) to be the new template rather than the current template.

The following link says "get the document's searchswitch element (which in this case is a form). Then set the searchswitch element's 0th element (which is the hidden element named view-template). to "advanced". Then call the submit() function on the searchswitch form. The text in the link says "Advanced Search." 

<a href = "javascript:document.searchswitch.elements[0].value=&quot;advanced&quot;; document.searchswitch.submit();">
Advanced Search...</a>
 Note that there should be no line breaks in the javascript: URL.

There is no need to pass a value for the browse-category attribute, since it defaults to the existing value in the form, $$browse-category, which evaluates to the current category.

In a nutshell, when this link is invoked, it causes the page to be displayed again with the template named advanced.

When the page redisplays, it uses the pattern files defined in the configuration file for the advanced template. The entire page (rather than just the component containing the search form) is redisplayed using the pattern files specified in the configuration file for the advanced template.

The following paragraphs summarize the steps involved in creating two alternative templates, one for a standard search, and one for an advanced search.

First, create two new configuration files, one for the standard template and one for the advanced template.

[Contents] [Previous] [Next] [Last]

Last Updated: 02/07/98 20:49:01

Any sample code included above is provided for your use on an "AS IS" basis, under the Netscape License Agreement - Terms of Use