ATG Auto-Complete & Type-Ahead

Pawan Modi
ATG is the worldwide leader in the E-commerce solutions. This document describes about ATG support for auto-complete / type-ahead.

ATG

Page 0

ATG Auto-Complete & Type-Ahead

Preface
This document is a quick handbook for ATG Auto-Complete feature. This document is based on my hands-on ATG experience. Document details out the ATG components involved in implementing the type-ahead feature. The target audience of this document is ATG application developers. Autocomplete involves the program predicting a word or phrase that the user wants to type in without the user actually typing it in completely. Today auto-complete is a very common feature supported by most of the available search engines. Having auto-complete on e-commerce web-site enhanced the customer experience. On e-commerce websites this feature is very useful for product search. In this document, I have covered Type-Ahead design, sample code and configuration for the same. This document is easy to understand and implementation guide for auto-complete feature. The sample code examples are based on ATG9 libraries and ATG9-Search.

ATG

ATG Auto-Complete & Type-Ahead

Table of Contents
ABBREVIATION ATG
Introduction Auto-Complete / Type-Ahead customer experience. ATG Support Auto-Complete Pre-Requisite

3 4
4 4 4 4 4

AUTO-COMPLETE ARCHITECTURE
Data XML Configuration Creating Search Environment Create New Search Project Add Content Post Index Customization Configuration Create New Environment Front-End UI Changes Type-Ahead Page Search Page Text Box

5
6 7 7 8 9 10 11 11 12

ATG

ATG Auto-Complete & Type-Ahead

Abbreviation
DAS DAF DSS DPS DRP GSS LM CM RMI DCC SBS UDP Dynamo Application Server Dynamo Application Framework Dynamo Scenario Server Dynamo Personalization Server Dynamo Request Protocol Server Global Scenario Server Load Manager Connection Module Remote Method Invocation Dynamo Control Center Session Backup Server User Datagram Protocol alternative protocol to TCP/IP, (usually used for broadcasting)

SNMP Simple Network Management Protocol, MIB packet services

ATG

ATG Auto-Complete & Type-Ahead

ATG
Introduction
ATG is the worldwide leader in the E-commerce solutions. ATG product suite has enabled the vendors to enable their e-commerce commercial capabilities.

Auto-Complete / Type-Ahead
Autocomplete involves the program predicting a word or phrase that the user wants to type in without the user actually typing it in completely. Autocomplete speeds up human-computer interactions & also enhance the customer experience.

Every computer user is not a typing expert and searching for product / information on internet where you have millions of websites and products is tedious. Typing long product names to get desired search results is time & effort consuming. Auto-complete ease the user by suggesting the phrases based on first few characters typed by user.

ATG Support Auto-Complete

ATG Search supports auto-complete feature like while entering the query text in search box user is provided with a list of options to choose from. These options are displayed as a dropdown menu, which contains the strings that matches the first few characters provided. For example if the user entered pro then the list will display all the matching options like product , program, promotion etc. User may then select from the dropdown or may also complete the search ignoring the dropdown.

Pre-Requisite
Going ahead with the setup, assuming following dependencies are in place. 1. ATG9.1 installed and working. 2. ATG9 Search Setup is done and working. 3. Java script library script.aculo.us. Refer http://script.aculo.us

ATG

ATG Auto-Complete & Type-Ahead

Auto-Complete Architecture
ATG recommendation is to have dedicated server / instance to support auto-complete functionality. This is important because every keystroke in search box sends Ajax request to server. Hence lots of request coming in to the server based on the number of active user on your website. Not providing the dedicated instance / server for auto-complete may impact the performance of your production server due to many request flowing in for every key stroke. We can have auto-complete data and catalog data indexed in the same index file or in separate index files. Dedicated index files are recommended because having separate search engine for actual query and auto-complete request is recommended. Hence performance of your query search engine will not be impacted by auto-complete queries. Also for this example, i have used AJAX.Autocompleter function from the script.aculo.us an open source javascript library. Refer http://script.aculo.us for more information.

Note: - The WAR file for queryconsole application includes script.aculo.us javascript files. This war file can be found under the following path. <ATG9dir>/DAF/Search/Base/QueryConsole/web-apps/queryconsole.war

Note:1. I have used AJAX.Autocompleter function from the script.aculo.us an open source javascript library. Refer http://script.aculo.us for more information. 2. If you are using Jquery javascript framework in your application then using scriptaculous may cause a conflict, because the function $ is defined in both the frameworks, and definition of one will be overridden by other.

3. The script file for scriptaculous must be included in the head and not anywhere else.

ATG

ATG Auto-Complete & Type-Ahead

Data XML Configuration

We need to prepare data xml for Auto-Complete feature. All auto-complete data resides in xml file. This data xml is input for search engine. Search engine index the data xml and send response back with the matching strings for every character entered by user in search box. Sample data xml is shown below. You can all relevant strings in this xml based on your catalog data. You must have better understanding of all product / services available in your catalog before preparing this xml. This data xml should be placed at the following path.
<ATG9dir>/home/localconfig/atg/searchadmin/customizations/auxiliary_data

In above xml there are many elements and attributes. Let me brief it. lang is the supporting language by search engine. Default is English. If you want to have localization or internationalization support then you needs to create that many xml file in relevant languages with relevant data. min The minimum number of input characters required to fire auto-complete query. Example if this is set to 3 then unless user types-in 3 characters, request will not go to server. From 3 characters and above, request will be fired for every keystroke. max The maximum size of key. Requesting results with a longer key will simply truncate the key. top The maximum text results to store under each key. Element t This contain actual text data which is shown to user in front end. Attribute v is the priority or order in which strings are returned to user. Example if there are 5 options matching the input characters then they will be shown in the order defined by the attribute v.

ATG

ATG Auto-Complete & Type-Ahead

Creating Search Environment

We need to create a separate search environment for type-ahead (auto-complete) feature as mentioned earlier. Unlike normal indexing where we index repository data but here indexing happens on the typeahead data xml file.

Create New Search Project

ATG

ATG Auto-Complete & Type-Ahead

Add Content

ATG

ATG Auto-Complete & Type-Ahead

Post Index Customization Configuration

In post-index customization, we have to add auxiliary data.

ATG

10

ATG Auto-Complete & Type-Ahead

Create New Environment

Save and start this environment and do full indexing.

ATG

10

11

ATG Auto-Complete & Type-Ahead

Front-End UI Changes
Implementing auto-complete feature involves coding of 2 JSP pages.

Type-Ahead Page
The type-ahead page is for sending the auto-complete queries to server and rendering the responses (suggested strings). This JSP is rendered repeatedly as the user types text in the search box on the search page. The type-ahead page is rendered as a dropdown of strings matching the current value in the text box. The frequency of rendering the page is controlled by the JavaScript autocompleter function, but typically it polls for changes several times a second so the autocomplete dropdown is updated frequently as the user types. Sample code for type-ahead page is shown below.

Above droplet, input and output parameters are explained following sections.

TypeAheadDroplet
This droplet takes as input several search query attributes, constructs a TypeAheadRequest based on these inputs, and submits the query to ATG Search. The droplet then receives the results as a list of autocomplete strings matching the query text and renders them on the page. For detail information on this droplet kindly refer the Oracle API document here. Following are some input parameters for this droplet. context The session-scoped component of class atg.search.formhandlers.SearchContext that maintains information about the connection to ATG Search. Typically this is set to /atg/search/formhandlers/SearchContext. text The search query text to return autocomplete strings for. environment The name of the ATG Search environment (created through Search Administration) whose index contains the type-ahead data.

ATG

11

12

ATG Auto-Complete & Type-Ahead

language The language of the type-ahead data. This should match the query language. Setting this attribute you are telling search engine to refer language specific data xml for appropriate result. Refer Data XML section for more detail. This attribute is useful to have support for internationalization and localization. sort The type of sorting to perform on the list of matching autocomplete strings. Options are as follow. alpha -- Sort in alphabetical order. length -- Sort by the length of the strings. value (default) -- Sort by the rankings provided with the type-ahead data. match -- Sort using the search engines metric that takes into account both the rankings provided with the type-ahead data and the lengths of the matching strings (with shorter strings ranked higher because the search substring represents a greater proportion of the matching string).

sortOrder The ordering to apply to the sorted results. Can be either ascending or descending (default).

Following is the open paramenter itemFormat This open parameter is rendered once for each matching autocomplete string. Following is the output parameter match This parameter is set iteratively to each matching autocomplete string.

Search Page Text Box

This page / text box is to submit search queries to QueryFormHandler. This page is use to construct the search form and fire a query against the catalog data. In order to support auto-complete, we need following addition in this jsp. A <script> tag that import the JavaScript libraries. A <div> tag that enables you to associate the type-ahead dropdown with the search text input field. JavaScript that calls the autocompleter function.

ATG

12

13

ATG Auto-Complete & Type-Ahead

In coming section we will see this in details. 1. Import JavaScript Library in search text box jsp.

2. Using a <div> element with search text input field. The div is placed just below the search box to render the typeAhead.jsp with auto-completed strings.

3. Calling auto-complete function. The example below creates a JavaScript function i.e. buildQueryCallback, which constructs the URL (including query parameters) for rendering the typeahead page. It also creates a JavaScript function i.e. AutoComp. This function is executed when the page loads and calls the Ajax.Autocompleter function with arguments that associate it with the text field and <div> element in the search form shown above. Ajax.Autocompleter renders the typeahead page using the URL constructed by the buildQueryCallback function, adding a query parameter q whose value is the string currently in the text box.

For example, if the user types nok, the URL constructed by the JavaScript is shown below. typeAhead.jsp?q=nok&environment=commerce&language=English The query parameters are used to set the input parameters of the TypeAheadDroplet on the type-ahead page. For more information about the Ajax.Autocompleter function, including additional options that can be specified in the function call, visit here.

ATG

13