 |
|
 |
JavaScript Search Service DocumentationService 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 pageA 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 pageAfter 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 conceptsThe 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:
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.
Example use in HTMLThe 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:
Try it: view this page CommandsThis 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 commandsWith 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:
Try it: view this example or explore this example Summary of available commandsCommands 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 commandsThese commands are used to control what search options are available to your users and how the search results are displayed in your page. ShowElementSample 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:
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:
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:
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:
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:
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. HideElementSample 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:
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':
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:
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. CustomMenuItemSample 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:
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:
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:
Try it: view this example or explore this example MaxResultsPerPageSample 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.
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:
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.
Try it: view this example or explore this example MaxLinkLengthSample 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.
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. MaxDescriptionLengthSample 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.
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 commandsThe 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. SmartLinkSample 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:
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:
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:
Try it: view this example or explore this example SmartLinkDropListSample 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:
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:
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':
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:
Try it: view this example or explore this example
Logic commandsLogic 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. SearchConstraintSample 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.
Errors and exceptions This command returns an error if a syntax error is found in the search query. Examples See the templates and examples. SearchBoostSample 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.
Errors and exceptions This command returns an error if a syntax error is found in the search query. Examples See the templates and examples. SortBySample 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
Errors and exceptions This command returns an error if an incorrect value is supplied. Examples See the templates and examples. RedirectSearchToSample 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. SuppressErrorsSample 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 commandsIn 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. RenderPageSample 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. RenderSearchResultsSample 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.
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':
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:
Try it: view this example or explore this example
serviceURLThe 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 queriesA 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 charactersWhen 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=""Atmospheric science"">
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 developersAs you edit and develop your custom search pages, the following tips may be helpful:
How the service worksThe 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
<> 
|
