JavaScript
Search Service
Skip navigation Digital Library for Earth System Education
Digital Library for Earth System Education
Search tips

JavaScript Search Service Documentation

Service version JSHTML v1.1

The JavaScript Search Service (JSHTML) lets Web developers place repository search for ADN resources into Web pages with JavaScript, and is available from the Digital Discovery System (DDS). The service is designed to be used in real-time, high-availability Web sites to provide interactive search and discovery interfaces for repository resources.

The service generates interfaces for DDS resources that reside in the ADN metadata format only. For a general purpose search JavaScript client, use the Search Service API instead. A general-purpose JavaScript client that illustrates it's use is show in these examples.

With this JavaScript API, developers can place search into their web page and customize a range of options such as the interactive search features that are made available to users, the way items are displayed in the page and the behavior and content made available from the the search environment itself. Customizable options include a search interface and standard menus, search results and full descriptions of the resources and the collections in which they reside, custom menus that can be mapped to any topic or area of interest, SmartLinks that, when clicked, perform pre-defined searches and display them in the page, and non-interactive displays of resources based on developer-defined searches.

How to create a custom search page

A simple way to create your own custom search page is to start with one of the templates and examples and use it as a boilerplate for your custom page. Another way is to use the documentation provided below, which contains a detailed description of the service API and example code that can be copied and pasted directly into your existing web page.

The service API can be used in static HTML pages (.html or .htm), as well as dynamic pages such as JSP, PHP, ASP, CGI and others. The service uses JavaScript in the web browser to render the search - see the list of supported browsers below.

How to deploy and install your custom page

After you are done creating your page, simply deploy the page to your web site as you would any other HTML page. There are no special requirements needed to install or deploy pages that use the JavaScript Search API. On most computers, you can also view and interact with your page directly from your hard drive by simply double-clicking on the file (for example "index.html"), and opening it in your web browser.

Definitions and concepts

The JavaScript Search Service (JSHTML) is a web API that uses JavaScript to provide a customizable search environment and deliver search results to your web page. To use the service, you simply insert two <SCRIPT> elements into your web page at the point in which you want the search interface and dynamic content to be displayed. For example, the following code places a simple search box into a web page - simply copy and paste this code into your web page to see how it works:

<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   ShowElement("searchBox");	
   RenderPage();	
 -->
</SCRIPT>

Try it: view this example or explore this example

The first <SCRIPT> element points to the serviceURL, which is a JavaScript library that provides access to the service provider and the available commands. The second is an inline <SCRIPT> element that is used to insert one or more commands into your page. The commands provide an API to control the interactive features of the search environment and the dynamic content that is displayed in the page. Lastly, you may customize the fonts, colors and sizes of the dynamic HTML content displayed in your page using CSS, and an optional style sheet of suggested CSS styles is provided for inclusion in your page.

  • Commands - The commands provide an API used to control which interactive features are shown in the search page such as a search box, menus and SmartLinks, as well as the way information gets displayed in the search results.
  • serviceURL- The serviceURL provides the library of JavaScript commands and access to the given service provider.
  • Suggested CSS - The suggested CSS styles is a style sheet that is recommended for use in the web pages that use the service.

Example use in HTML

The following HTML code creates a simple search page using the API. You may copy this code, save it as a separate file (for example search.html) and use it to start your own page:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
   <title>Example custom DLESE search page</title>
   
   <!-- The suggested CSS styles -->
   <LINK REL="stylesheet" TYPE="text/css" 
      HREF="http://www.dlese.org/dds/services/jshtml1-1/suggested_styles.css">

   <!-- Optional CSS styles are used here to set the font to Arial throughout the page 
        and the font size to 10pt in the service output -->   
   <style type="text/css">
      BODY { font-family: Arial, sans-serif; }
      TD { font-size:10pt; }
   </style>
		
</head>
<body>

<h2 style="margin-left:4">Search DLESE</h2>

<!-- The serviceURL for this provider -->
<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>

<!-- Inline script that includes required and optional service commands -->   
<SCRIPT TYPE="text/javascript">
  <!--
   ShowElement("searchBox");
   ShowElement("gradeLevelsMenu");
   ShowElement("subjectsMenu");
   ShowElement("resourceTypesMenu");
   RenderPage();		
  -->
</SCRIPT>

<!-- A message that is displayed only when JavaScript is disabled in the browser -->
<NOSCRIPT>
   This page requires that JavaScript be turned on. 
   Please activate JavaScript in your browser.
</NOSCRIPT> 

</body>
</html>

Try it: view this page

Commands

This section describes the API for the service, knows as commands. The commands control the interactive features of the search environment and the dynamic content that is displayed in the page.

By default the service renders nothing in the page until one or more commands are inserted. In a typical development scenario, a developer will start with one of the two required commands and then add additional commands until each of the desired search and display features are included in the page.

Using the commands

With the exception of the SmartLink commands, all commands must reside within a single inline <SCRIPT> element. Prior to this inline script element you must source the JavaScript service library, or serviceURL. Together, these two <SCRIPT> elements should be placed in your HTML page at the point in which you would like the dynamic content to be displayed and they must not be used more than once within a single page.

For example:

<!-- The serviceURL -->
<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>

<!-- An inline script element where the commands are used -->
<SCRIPT TYPE="text/javascript">
 <!--	
   ShowElement("searchBox");	
   RenderPage();	
 -->
</SCRIPT>

Try it: view this example or explore this example

Summary of available commands

Commands fall into one of four categories: Display commands, SmartLink commands, Logic commands and Required commands. All commands are optional except for the required commands, and many commands may be repeated.

Display commands - These control what search options are available to your users and how the search results are displayed in your page.

ShowElement - Instructs the service to display a particular HTML element in the page.

HideElement - Instructs the service to hide or disable a particular HTML element that would normally be displayed.

CustomMenuItem - Instructs the service to create a custom menu for your page, as you define.

MaxResultsPerPage - Instructs the service to display a given maximum number of results per page.

MaxLinkLength - Instructs the service to truncate the links displayed in the page to a given length.

MaxDescriptionLength - Instructs the service to truncate the description displayed in the search results to a given length.

SmartLink commands - These control and define dynamic links and drop menus in your page.

SmartLink - Instructs the service to perform a predefined search when a given link is clicked.

SmartLinkDropList - Instructs the service to perform a predefined search when a given selection is made in a drop list.

Logic commands - These control global behaviors for your page.

SearchConstraint - Instructs the service to constrain all searches in the page to a given sub-set of resources.

SearchBoost - Instructs the service to boost the ranking of results in the page that match the criteria you define.

SortBy - Instructs the service to apply a given sort order to the results that are displayed.

RedirectSearchTo - Instructs the service to redirect the user's search request to a second page where the result will be displayed.

SuppressErrors - Instructs the service to suppress any developer errors that may be returned by the service.

Required commands - One of these two commands must be included in order to render the dynamic content.

RenderPage - Instructs the service to render the page.

RenderSearchResults - Instructs the service to perform a search based on a query you define and render the results automatically in the page.

 

Display commands

These commands are used to control what search options are available to your users and how the search results are displayed in your page.

ShowElement

Sample command

ShowElement("searchBox");

Summary and usage

The ShowElement command instructs the service to display a particular HTML element in your page. You may repeat this command as many times as needed to insert each of the elements you would like displayed. The order in which you include this command in your page has no effect on the order in which items are displayed.

Arguments

This command takes one argument. The value of the argument must be one of the following:

  • searchBox - displays a search box in your page.
  • gradeLevelsMenu - displays a menu for selecting grade levels
  • resourceTypesMenu - displays a menu for selecting resource types
  • subjectsMenu - displays a menu for selecting subjects
  • contentStandardsMenu - displays a menu for selecting content standards
  • collectionsMenu - displays a menu for selecting collections
  • gradeLevelSR - displays the grade levels in the search results
  • resourceTypeSR - displays the resource types in the search results
  • subjectSR - displays the subjects in the search results
  • collectionSR - displays the collections in the search results
  • accessionDateSR - displays the date the resource was accessioned into the library in the search results
  • annotations - displays the annotations in the search results and full description
  • searchWithinSmartLinkResults - displays an option to search within SmartLink search results

Errors and exceptions

This command returns no errors. If an incorrect argument is used, nothing is displayed.

Examples

Example 1

The following displays a search box:

<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   ShowElement("searchBox");	
   RenderPage();	
 -->
</SCRIPT>

Try it: view this example or explore this example

Example 2

The following displays a search box, the menu for grade levels, the menu for resource types, and the menu for subjects:

<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   ShowElement("searchBox");
   ShowElement("gradeLevelsMenu");
   ShowElement("resourceTypesMenu");
   ShowElement("subjectsMenu");   	
   RenderPage();	
 -->
</SCRIPT>

Try it: view this example or explore this example

Example 3

The following displays a search box, the menu for grade levels, the menu for resource types, and the menu for subjects. Then, in the search results it displays the grade levels, resource types and subjects:

<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   ShowElement("searchBox");
   ShowElement("gradeLevelsMenu");
   ShowElement("resourceTypesMenu");
   ShowElement("subjectsMenu");
   ShowElement("gradeLevelSR");
   ShowElement("resourceTypeSR");
   ShowElement("subjectSR");    	
   RenderPage();	
 -->
</SCRIPT>

Try it: view this example or explore this example - Note: when using these links, a search for 'ocean' is automatically performed for you to show how the search results are displayed.

Example 4

The following displays a search box, the menu for grade levels, the menu for resource types, and the menu for subjects. Then, in the search results it displays the grade levels, resource types and subjects:

<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   ShowElement("searchBox");
   ShowElement("gradeLevelsMenu");
   ShowElement("resourceTypesMenu");
   ShowElement("subjectsMenu");
   ShowElement("gradeLevelSR");
   ShowElement("resourceTypeSR");
   ShowElement("subjectSR");    	
   RenderPage();	
 -->
</SCRIPT>

Try it: view this example or explore this example - Note: when using these links, a search for 'ocean' is automatically performed for you to show how the search results are displayed.

HideElement

Sample command

HideElement("pager");

Summary and usage

The HideElement command instructs the service to hide or disable an HTML element that would normally be displayed by the service. You may repeat this command as many times as needed to disable each of the elements you would like hidden. The order in which you include this command in your page has no effect on it's behavior.

Arguments

This command takes one argument. The value of the argument must be one of the following:

  • pager - disables the display of the links to page through the search results. This may be useful for pages that wish to display a fixed number of resources only, for example.
  • titleRewrite - normally the service re-writes the title displayed in the page to one that reflects the search action performed by the user. Using this argument, you can disable title re-writing to preserve the title you have assigned to the page.
  • logo - disables the display of the DLESE logo at the bottom of the page. This may be useful for sites in which you want to display a simple search box in one page (with no logo) and the search results in another page, using the RedirectSearchTo( ) command.

Errors and exceptions

This command returns no errors. If an incorrect argument is used, nothing is changed.

Examples

Example 1

The following disables the display of the links to page through the results. It then displays a list of the ten most relevant classroom activities about 'earthquakes':

<b style="margin-left:4px">Classroom activities about earthquakes:</b>
<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   HideElement("pager");	
   RenderSearchResults("earthquakes AND re:0c");
 -->
</SCRIPT>

Try it: view this example or explore this example

Example 2

The following displays a simple search page with the title re-write function of the service turned off:

<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   HideElement("titleRewrite");	
   ShowElement("searchBox");
   RenderPage();
 -->
</SCRIPT>

Try it: view this example or explore this example - Note: when using these links, a search for 'ocean' is automatically performed for you to show how the search results are displayed.

CustomMenuItem

Sample command

CustomMenuItem("Topics","Biology","su:03");

Summary and usage

The CustomMenuItem command allows you to create custom menus for your page. You may repeat this command as many times as needed to define each of the menus and menu items you want for your page. The order in which you include this command in your page determines the order in which the custom menu is rendered, relative to other custom menus. Custom menus are always placed after the standard menus. Note that you may not add or remove items from the standard menus.

See related discussion about embedded search queries and escaping reserved characters.

Arguments

This command takes three arguments. The arguments are used as follows:

  • First argument: menu name - Indicates the name of the custom menu. If no custom menu exists by this name, one will first be created and then the item will be added to it. This name is set to upper case automatically.
  • Second argument: item name - Indicates the name of the item to add to the given menu.
  • Third argument: query mapping - Defines the search query that gets mapped to this menu item. When the menu item is selected by the user, their search is limited to the set of resources that match this query.

Errors and exceptions

This command returns an error if other than three arguments are supplied.

Examples

Example 1

The following creates custom menu for ocean sciences, using the three ocean science subject classifiers:

<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   CustomMenuItem("Ocean science field","Biological oceanography","su:02");
   CustomMenuItem("Ocean science field","Chemical oceanography","su:04");
   CustomMenuItem("Ocean science field","Physical oceanography","su:0p");	
   ShowElement("searchBox");
   RenderPage();
 -->
</SCRIPT>

Try it: view this example or explore this example

Example 2

The following creates two custom menus and also uses the standard menu for grade levels:

<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   // Use the placeNames field to designate locations:
   CustomMenuItem("Location","California","placeNames:california");
   CustomMenuItem("Location","Oregon","placeNames:oregon");

   // Select resource types for activities:
   CustomMenuItem("Type of resource","Activities", "re:0c OR re:0d OR re:0g OR re:0j");
   // Select all resource types in Tools:
   CustomMenuItem("Type of resource","Tools", "re:00h OR re:00i OR re:00j");
   // Select all Data set resource types:
   CustomMenuItem("Type of resource","Datasets", "re:07 OR re:08 OR re:09");   
   
   ShowElement("searchBox");
   ShowElement("gradeLevelsMenu");
   ShowElement("resourceTypeSR");
   RenderPage();
 -->
</SCRIPT>

Try it: view this example or explore this example

MaxResultsPerPage

Sample command

MaxResultsPerPage("5");

Summary and usage

The MaxResultsPerPage command instructs the service to display a given maximum number of results per page. If this command is not used, the default value is set to 10.

Arguments

This command takes one argument.

  • Argument sets the maximum number of results to display. The value of the argument must be an integer from 1 to 100.

Errors and exceptions

This command returns an error if the value provided is not an integer from 1 to 100.

Examples

Example 1

The following sets the number of results to display to 5, and displays a search box:

<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   MaxResultsPerPage("5");
   ShowElement("searchBox");
   RenderPage();
 -->
</SCRIPT>

Try it: view this example or explore this example - Note: when using these links, a search for 'seismometers' is automatically performed for you to show how the search results are displayed.

Example 2

This example demonstrates an error condition. The MaxResultsPerPage command is used improperly to set an invalid value of 200. In this case an error message is displayed immediately when the page is displayed because of the use of the RenderSearchResults command. Note that many errors are not displayed until the user performs a search in the page.

<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   MaxResultsPerPage("200");
   RenderSearchResults("global climate change");
 -->
</SCRIPT>

Try it: view this example or explore this example

MaxLinkLength

Sample command

MaxLinkLength("50");

Summary and usage

The MaxLinkLength command instructs the service to truncate the links displayed in the page to a given length. Setting a smaller value helps avoid problems with pages not wrapping properly in narrow pages and/or elements. If this command is not used, the default value is set to 80.

Arguments

This command takes one argument.

  • Argument sets the maximum length of the links that are displayed in the page. The value of the argument must be an integer greater than 0.

Errors and exceptions

This command returns an error if the value provided is not an integer greater than 0.

Examples

See the templates and examples.

MaxDescriptionLength

Sample command

MaxDescriptionLength("200");

Summary and usage

The MaxDescriptionLength command instructs the service to truncate the description displayed in the search results to a given length. This may be useful when you wish to provide a compact display of resources in your page. When truncated, the description is displayed with three trailing periods ( ... ). If this command is not used, the default value is set to 400.

Arguments

This command takes one argument.

  • Argument sets the maximum length of the description that is displayed in the page. The value of the argument must be an integer greater than 0.

Errors and exceptions

This command returns an error if the value provided is not an integer greater than 0.

Examples

See the templates and examples.

 

SmartLink commands

The two SmartLink commands (SmartLink and SmartLinkDropList) provide a way to display a set of search results when a user clicks a hyperlink or selects an item from a drop list.

SmartLink commands are different from the other commands because they are used within standard HTML elements (the <a> tag and <select> lists) in your page and not within the the inline <SCRIPT> element.

Tip: Use the SmartLink Builder tool to create SmartLinks for your pages.

SmartLink

Sample command

<a href='JavaScript:SmartLink("oceans","Oceans")'>Oceans</a>

Summary and usage

The SmartLink command allows you to create one or more custom hyperlinks for your page that is mapped to one or more search queries. When the user clicks on a hyperlink SmartLink, the given query is executed and the search results are displayed in your page. This allows you to make a group of resources available to your site visitors with a single click, and embed your knowledge of the repository's information domain into your page.

This command must be placed within an HTML <a> tag, as shown above.

See related discussion about embedded search queries and escaping reserved characters.

Tip: Use the SmartLink Builder tool to create SmartLinks for your pages. You can also create your SmartLinks by writing and editing code directly, as detailed below.

Arguments

This command takes two arguments. The arguments are used as follows:

  • First argument: query mapping - Defines the search query that gets mapped to the SmartLink. When the link is clicked by the user, this search query is executed and the results are displayed in your page.
  • Second argument: link name - Indicates the name of the SmartLink, which is displayed in the search results. Note that you also must use standard HTML to create your link and link name.

Errors and exceptions

This command returns an error if anything other than two arguments are supplied.

Examples

Example 1

The following creates two SmartLinks: one for tsunamis and one for earthquakes:

<div style="margin-left:5px">
  <b>Click on a topic SmartLink:</b><br>
  <a href='JavaScript:SmartLink("tsunamis","Tsunamis")'>Tsunamis</a><br>
  <a href='JavaScript:SmartLink("earthquakes","Earthquakes")'>Earthquakes</a><br>
</div>
<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   RenderPage();
 -->
</SCRIPT>

Try it: view this example or explore this example

Example 2

The following creates two SmartLinks: one for Florida and one for California. It also places a search box in the page and allows the user to search within the SmartLink results:

<div style="margin-left:5px">
  <b>Click on a locale SmartLink:</b><br>
  <a href='JavaScript:SmartLink("florida","Florida")'>Florida</a><br>
  <a href='JavaScript:SmartLink("california","California")'>California</a><br>
</div>
<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   ShowElement("searchBox");
   ShowElement("searchWithinSmartLinkResults");
   RenderPage();
 -->
</SCRIPT>

Try it: view this example or explore this example

SmartLinkDropList

Sample command

<select id="smartLinkDropList" onchange="JavaScript:SmartLinkDropList()">
  <option value="">-- Select a category --</option>		   
  <option value="tsunamis">Tsunamis</option>
  <option value="earthquakes">Earthquakes</option>				   
</select>

Summary and usage

The SmartLinkDropList command allows you to create a drop list containing one or more custom selections for your page that is mapped to one or more search queries. When the user selects an item in the SmartLinkDropList, the given query is executed and the search results are displayed in your page. This allows you to make groups of resources available to your site visitors from a single drop menu, and embed your knowledge of the repository's information domain into your page.

This command must be used within an HTML <select> list in conjunction with the HTML <option> tag. Specifically, this command must be placed within the 'onchange' attribute of the <select> element and/or within the 'action' element of an encompassing <form> for the <select> list. In addition, the 'id' attribute of the <select> list must be set to 'smartLinkDropList'. See the examples below.

See related discussion about embedded search queries and escaping reserved characters.

Tip: Use the SmartLink Builder tool to create SmartLinks for your pages. You can also create your SmartLinks by writing and editing code directly, as detailed below.

Arguments

This command takes no arguments within the command JavaScript, however the <option> tags used within the <select> list must contain the following:

  • The 'value' attribute of the <option> tag: query mapping - Defines the search query that gets mapped to the menu item. When the menu item is selected by the user, this search query is executed and the results are displayed in your page. If this is left empty, no action is taken.
  • Content of the <option> tag: menu name - Indicates the name of the SmartLink, which is displayed in the menu and in the search results.

Errors and exceptions

This command returns an error if the id attribute of the select list is not set properly.

Examples

Example 1

The following creates a drop list with two options: one for tsunamis and one for earthquakes. The resources are displayed automatically when the user selects an item in the list:

<div style="margin-left:5px">
  <b>View resources about the following:</b><br><br>
  <select id="smartLinkDropList" onChange="JavaScript:SmartLinkDropList()">
      <option value="">-- Select a category --</option>		   
      <option value="tsunamis">Tsunamis</option>
      <option value="earthquakes">Earthquakes</option>				   
  </select>
</div>
<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   RenderPage();
 -->
</SCRIPT>

Try it: view this example or explore this example

Example 2

The following creates a drop list with two options: one for "severe storms" and one for tornadoes. The resources are displayed after the user selects an item in the list and clicks 'Go':

<div style="margin-left:5px">
  <b>Select a topic and click Go:</b><br><br>
  <form method="get" action="JavaScript:SmartLinkDropList()">  
    <select id="smartLinkDropList">
        <option value="">-- Select a category --</option>		   
        <option value="&quot;severe storms&quot;">Severe storms</option>
        <option value="tornadoes">Tornadoes</option>				   
    </select>
    <input type="submit" value="Go">
  </form>
</div>
<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   RenderPage();
 -->
</SCRIPT>

Try it: view this example or explore this example

Example 3

The following shows a combination of using a SmartLinkDropList along with a regular search box with the option to search within the SmartLink results:

<div style="margin-left:5px">
  <b>Choose a quick link:</b><br>
  <select id="smartLinkDropList" onChange="JavaScript:SmartLinkDropList()">
      <option value="">-- Select a category --</option>		   
      <option value="tsunamis">Tsunamis</option>
      <option value="earthquakes">Earthquakes</option>				   
  </select>
  <br><br><b>Or search for resources by keyword:</b><br>
</div>
<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   ShowElement("searchBox");
   ShowElement("searchWithinSmartLinkResults");
   RenderPage();
 -->
</SCRIPT>

Try it: view this example or explore this example

 

Logic commands

Logic commands are responsible for controlling certain logic in your page such as global search constraints and boosting, how search results are sorted, and whether errors should be displayed to aid developers.

SearchConstraint

Sample command

SearchConstraint("su:08");

Summary and usage

The SearchConstraint command instructs the service to constrain all searches in the page to a given sub-set of resources that you define using a search query. When this command is used, all searches and SmartLinks conducted in the page are constrained to the sub-set of resources that match the query provided in this command.

See related discussion about embedded search queries and escaping reserved characters.

Arguments

This command takes one argument.

  • Argument defines the search query used to constrain all searches and SmartLinks in the page.

Errors and exceptions

This command returns an error if a syntax error is found in the search query.

Examples

See the templates and examples.

SearchBoost

Sample command

SearchBoost("florida");

Summary and usage

The SearchBoost command instructs the service to boost the ranking of results in the page that match the criteria you define using a search query. When this command is used, resources that match the search query are boosted in all searches and SmartLinks conducted in the page. Boosting provides extra ranking to the resources, which places them higher in results than they would normally be by default. This allows you to highlight those resources that are most relevant to your audience.

See related discussion about embedded search queries and escaping reserved characters.

Arguments

This command takes one argument.

  • Argument defines the search query used to boost resources in all searches and SmartLinks in the page.

Errors and exceptions

This command returns an error if a syntax error is found in the search query.

Examples

See the templates and examples.

SortBy

Sample command

SortBy("title");

Summary and usage

The SortBy command instructs the service to apply a given sort order to the results that are displayed. This command lets you sort the results alphabetically by their title or by the date in which they were accessioned into the library. If not used, the service orders the results by relevancy based on the search criteria provided by the user.

Arguments

This command takes one argument. The argument must be one of the following three values

  • title - Sorts the results alphabetically by their title.
  • mostrecent - Sorts the results in order by their accession date in the library, with the most recent shown first.
  • mostrelevent - Sorts the results by the most relevant to the user's search query (this is the default setting).

Errors and exceptions

This command returns an error if an incorrect value is supplied.

Examples

See the templates and examples.

RedirectSearchTo

Sample command

RedirectSearchTo("search_page2.html");

Summary and usage

The RedirectSearchTo command instructs the service to redirect the user's search request to a second page where the result will be displayed. This is useful if you would like to have a small search box on one or more pages that opens to a separate search results page within your site.

Arguments

This command takes one argument. The argument must be a valid URL that is either absolute or relative to the current page.

Errors and exceptions

This command returns no errors if used incorrectly.

Examples

See the templates and examples.

SuppressErrors

Sample command

SuppressErrors();

Summary and usage

The SuppressErrors command instructs the service to suppress any developer errors that may be returned by the service. Normally, the service will provide errors if the service is used incorrectly in your page, which can be useful during development for debugging. If you want to ensure errors are not displayed to your users, use this command. When used, this command must appear before all other commands declared in the inline <script> portion of your page.

Arguments

This command takes no arguments.

Errors and exceptions

This command returns no errors if used incorrectly.

Examples

See the templates and examples.

 

Required commands

In order to use the service, exactly one of the two required commands must be placed in the page. Additional commands may also be included in the page in addition to the required command.

RenderPage

Sample command

RenderPage();

Summary and usage

The RenderPage command instructs the service to render the dynamic portion of the page. This command must appear after all other commands declared in the inline <script> portion of your page.

Arguments

This command takes no arguments.

Errors and exceptions

This command returns no errors if used incorrectly.

Examples

See the templates and examples.

RenderSearchResults

Sample command

RenderSearchResults("colorado");

Summary and usage

The RenderSearchResults command instructs the service to perform a search based on a query you define and render the results automatically in the page. This is useful for listing resources non-interactively based on a page theme, for example. It can also be used in environments in which the search query is generated outside of the service framework such as within another application that generates the queries to display repository resources. This command must appear after all other commands declared in the inline <script> portion of your page.

See related discussion about embedded search queries and escaping reserved characters.

Arguments

This command takes one argument.

  • Argument defines the search query used to display the resources in the page.

Errors and exceptions

This command returns an error if used in conjunction with the RenderPage command or if a query syntax error is present.

Examples

Example 1

The following displays a list of the relevant classroom activities about 'earthquakes':

<b style="margin-left:4px">Classroom activities about earthquakes:</b>
<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   RenderSearchResults("earthquakes AND re:0c");
 -->
</SCRIPT>

Try it: view this example or explore this example

Example 2

The following displays a list of ocean science resources, with those resources containing 'florida' boosted in the search results:

<b style="margin-left:4px">Ocean science resources (with boosting for Florida):</b>
<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>
<SCRIPT TYPE="text/javascript">
 <!--	
   SearchBoost("florida");
   RenderSearchResults("su:02 OR su:04 OR su:0p");
 -->
</SCRIPT>

Try it: view this example or explore this example

 

serviceURL

The serviceURL is used to gain access to the service and available commands. To use the service, simply source the JavaScript serviceURL in your HTML page.

For example:

<SCRIPT TYPE="text/javascript"
   SRC="http://www.dlese.org/dds/services/jshtml1-1/javascript_search_service.js"></SCRIPT>

Once you have sourced the serviceURL in your page, you can begin to use the commands in inline script and in SmartLink HTML.

To change from using one service provider to another, simply edit the serviceURL to point to that of the desired service provider. For consistency, you should also change the URL you are using to reference the suggested CSS styles, if this applies.

Embedded search queries

A powerful feature of this service is the ability to embed pre-defined search queries when customizing the search options and the information that you highlight and make available from your page. Search queries are used in the following commands: CustomMenuItem, SearchConstraint, SearchBoost, RenderSearchResults, SmartLink, and SmartLinkDropList.

Simple queries are easy to define, however more complicated queries require familiarity with the query syntax and knowledge of the search fields that are available from the service. Many powerful queries are demonstrated in this documentation and may be used directly in your own pages. For a full discussion of the query syntax and search fields, see the section linked here entitled Available search fields.

Escaping reserved characters

When defining search queries, the quotation character ( " ) needs to be escaped both in the JavaScript commands and HTML that you use in your page. This applies to the JavaScript used in the following commands: CustomMenuItem, SearchConstraint, SearchBoost, RenderSearchResults, SmartLink. This also applies to the the HTML used in conjunction with the SmartLinkDropList command.

To escape the quotation character in the JavaScript commands, precede the character with a slash, for example:

SearchConstraint("\"Atmospheric science\"");

To escape the quotation character used in conjunction with the SmartLinkDropList command, replace the quotation with it's entity reference ("quot;), for example:

<select id="smartLinkDropList" onChange="JavaScript:SmartLinkDropList()">	
  <option value="">
    -- Select a subject --</option>		   
  <option value="&quot;Atmospheric science&quot;">
    Atmospheric science</option>
  <option value="biology">
    Biology</option>				   
</select>

What browsers are supported?

This service uses JavaScript in the web browser to render the search.

The following browsers are believed to be compatible with the service: Internet Explorer 5.5 and above (Windows), Internet Explorer 5.2 (Mac OS X), Firefox (all versions), Netscape 6 and above, Mozilla, Opera 7 and above, Safari 1.0+ and Konqueror versions 3.01 and above.

The following browsers are believed NOT to be compatible with the service: Internet Explorer 5.0 and earlier, Konqueror 2.x and earlier, and Opera 6.x and earlier.

Tips for developers

As you edit and develop your custom search pages, the following tips may be helpful:

  • You can see how the the dynamic content is displayed in your page by opening and viewing your HTML file in your web browser. As you make changes, you should perform some searches in your page to see how the search results and other elements are displayed.
  • As you edit the commands in your page, you will need to 'force' the browser to refresh itself in order to see the changes. This can be done by clicking the 'reload' button while holding the <shift> key or pressing the <F5> key on Windows. In some cases you may need to close all windows of your browser and then re-open the page to view your changes.
  • Issues with Internet Explorer: On some systems, you may receive a warning from Internet Explorer that 'active content' has been restricted. If this happens you will need to 'Click for more options' and choose 'Allow Blocked Content.' In addition, the browser's back and forward buttons do not work properly when viewing a local file from your computer. Note that these issues do not occur when the page is deployed and accessed from the Internet - the problems only occur when viewing a local file from your computer.
  • Be sure to use the JavaScript debugging features of your browser. If you see a JavaScript error, check to make sure you have spelled the command properly. Read your browser's JavaScript errors for help with debugging.
  • All of the text returned by the service resides in a table. To control the way fonts are displayed, assign CSS to the <td> element, for example:
    TD { font-family: Arial, sans-serif; font-size: 10pt; }
  • Each of the table HTML elements (<table>, <tr>, <td>) returned by the service are assigned the CSS class 'stdTable' . To control the way fonts and other elements are are displayed in the service response independently from the way your own HTML is displayed, use the 'stdTable' class specifier in your CSS, for example:
    TD.stdTable { font-family: Arial, sans-serif; font-size: 10pt; }
  • As you develop your page, you may find it useful to view the suggested CSS styles and the required CSS styles that are used by the service.
  • The JavaScript and CSS that is required to use this service are relatively simple to use, even if you are not familiar with these two web standards. In many cases, the templates and examples will provide all you need to be able to create and customize your own web page. If you would like to learn more about these standards, however, we recommend the W3C JavaScript Tutorial or CSS Tutorial. There are also many other resources available on the Internet or in print.

How the service works

The dynamic content is delivered to the web page through JavaScript using an architecture that is similar to a Representation State Transfer (REST) style web service. In REST style web service architectures, requests are typically encoded as a URL and responses are returned as XML. In the JSHTML architecture, requests are encoded as a URL and the response is returned to the web page as HTML wrapped inside a JavaScript write( ) statement. Developers use the suite of JavaScript commands to control the dynamic features of the page; the commands do the work of constructing the necessary http requests and inserting the JavaScript response into the page. CSS may then be applied to the page to customize the fonts, colors and sizes of the HTML elements that are returned by the service.

Author: John Weatherley <>
Last revised $Date: 2009/12/04 22:08:36 $

University Corporation for Atmospheric Research (UCAR) National Science Foundation (NSF) National Science Digital Library (NSDL)