Working with the Product Finder XSL Stylesheet

The Product Finder XSL stylesheet helps you render product finders in an HTML page, which can be used both in Web-based applications and in desktop applications. To render the output in a Windows desktop application, you embed the HTML in an Internet Explorer control (see Handling Product Finder Attributes that the User Selects).

Currently GetProductFinderCall returns sell-side product finders that are used in the eBay Sell Your Item flow. On the eBay site, this type of product finder appears on the "Choose a Listing Option" page for categories that support Pre-filled Item Information and product finder-based searches.

Figure 20-5 A Sell-Side Product Finder on an eBay Web Site

If the user is searching for multiple products in similar categories, the stylesheet can render a page containing multiple identical product finders. This capability is useful for applications that support batch searching capabilities. For example, if a seller wants to list three cell phones by different manufacturers, your application could display three Cell Phone Finders to enable the seller to search the catalog for all three products at the same time. See Transforming the Product Finder XML below for more information about this use case.

Figure 20-6 Rendering Multiple Identical Product Finders

The Product Finder XSL Stylesheet is meant to be used for rendering product finders so that the user can specify attributes to include in a query. It does not support functionality related to constructing the query based on the user's selections, checking user input, or conducting the catalog product search.

To retrieve the Product Finder XSL stylesheet, use GetProductFinderXSLCall or a class that implements the IProductFinderXslProvider interface. As the library of attributes and values for product finders can change, you should retrieve the latest Product Finder XSL whenever you retrieve the latest Product Finder XML (typically once on each day that your application will render product finders). This is necessary in order to make sure you are always using the version of the XSL that corresponds to the latest version of the product finders.

eBay strongly recommends that you avoid modifying the Product Finder XML document (aside from the necessary changes outlined in this documentation) and the Product Finder XSL stylesheet directly. Direct changes to the files returned from these meta-data calls are not supported.

To render product finders, an application needs to perform these steps. The Attributes Library's sample data-source provider and master classes implement most of this functionality for you:

Execute GetProductFinderXSLCall to obtain the Product Finder XSL (see Retrieving the Product Finder XSL Stylesheet).
Call the renderHtml( ) method on ProductFinderMaster to render the product finder (see Transforming the Product Finder XML).
After the user selects the search criteria, use the nameValuesAttributeSets( ) method on ProductFinderMaster to determine the data they selected and convert the data to the GetProductSearchResultsCall input XML format (see Handling Product Finder Attributes that the User Selects).

Product Finder XSL Stylesheet Documentation

The Product Finder XSL stylesheet documentation describes the templates that are defined in the product_finder.xsl file returned from GetProductFinderXSLCall.

Product Finder XSL Stylesheet Documentation

eBay, Inc.

http://developer.ebay.com/DevZone/XML/docs/Support/pf-help-index.html

Transforming the Product Finder XML

The Product Finder XSL Stylesheet can render one or more identical product finders to search for similar kinds of products. For example, you can render three PDA product finders together. This capability is useful for sellers who specialize in a particular vertical market.

When you render multiple identical product finders on the same page, the set of attribute IDs are the same for each one. This means that when a user specifies values for the attributes, you need to be able to distinguish which product finder the attributes are associated with. To do this, you insert a ProductFinder.count XML attribute into the XML document before transforming the XML. The Javascript functions that the stylesheet inserts in the transformed HTML document will use the count value to determine the index of each product finder. When the form is submitted, it will generate POST data that identifies each product finder by its index.

The stylesheet does not support rendering multiple product finders in different meta-categories at the same time. For example, if you attempt to render a PDA product finder and a Digital Camera Finder on the same page, no automatic indexing is provided to help you distinguish their attributes in the POST data.

You need to write custom processing code to apply the Product Finder XSL Stylesheet to the Product Finder XML document or use the ProductFinderMaster provided with the eBay SDK for Java. If you want to render the output in a Windows desktop application instead of a Web-based application, you can embed the HTML in an Internet Explorer control.

To render one or more product finders:

If you have not already done so, retrieve the Product Finder XML and XSL by using data-source providers that implement the IProductFinderXmlProvider and IProductFinderXslProvider interfaces, and set the providers on the ProductFinderMaster object. Alternatively, execute GetProductFinderCall and GetProductFinderXSLCall to retrieve the latest version of the product finder meta-data and stylesheet.
When you are ready to render a product finder for a particular category, call the renderHtml( ) method on ProductFinderMaster and pass in the category ID associated with the product finder you want to render. This renders the specified product finder.

If you are using the ProductFinderMaster class that is included in the eBay SDK for Java, you are done with the transformation. See Handling Product Finder Attributes that the User Selects for next steps.

If you choose to implement your own version of the ProductFinderMaster class, it may be helpful to understand how to modify the raw XML directly in order to render it using the Product Finder XSL stylesheet. You can use the ProductFinderMaster class as a reference when creating your own implementation.

The following steps describe the changes you would need to make to the raw XML if you do not use the ProductFinderMaster class as part of your solution, or if you want to render multiple instances of the same product finder on the same page (this is useful for batch searches).

Create a new Product Finder XML document or modify the original document as follows:
If you want to render one particular product finder, create a new Product Finder XML document or modify the original document such that it contains only one ProductFinder node for the type of product finder you want to display.
If you are rendering multiple copies of the product finder together (or if you are rendering one product finder but you do not want the Submit button to appear), insert a ProductFinder.count XML attribute that specifies the quantity of product finders you want to render.

The example below shows the elements that your working XML document should contain if you are rendering only one product finder (with a Submit button).

Example 20-13 XML for One Product Finder with a Submit Button 

<?xml version="1.0" encoding="utf-8" ?> <eBay> <EBayTime>2004-04-30 04:52:57</EBayTime> <Version>3540</Version> <ProductFinders> <ProductFinder mode="ADVANCE" id="1838">      // One ProductFinder node (no count) <Title><![CDATA[PDAs]]></Title> <PresentationInstruction> <DomainName>PDAs Finder</DomainName> ... ROW nodes ... </PresentationInstruction> <AttributeList> ... Attribute nodes ... </AttributeList> </ProductFinder> </ProductFinders> </eBay>

The example below shows the elements that your working XML document should contain if you are rendering multiple product finders (or one product finder with no Submit button). In this example, three product finders will be rendered, so the count value is "3". (In the HTML output, the value of count controls the number of form elements that will be generated. In this example, three form elements will be created when the stylesheet is applied.)

Example 20-14 XML for Multiple Product Finders with No Submit Button 

<?xml version="1.0" encoding="utf-8" ?> <eBay> <EBayTime>2004-04-30 04:52:57</EBayTime> <Version>3540</Version> <ProductFinders> <ProductFinder mode="ADVANCE" id="1838" count="3"> // count inserted <Title><![CDATA[PDAs]]></Title> <PresentationInstruction> <DomainName>PDAs Finder</DomainName> ... ROW nodes ... </PresentationInstruction> <AttributeList> ... Attribute nodes ... </AttributeList> </ProductFinder> </ProductFinders> </eBay>

Apply the Product Finder XSL stylesheet to your working XSL document.
If no count attribute was specified, the stylesheet generates an HTML form that contains one product finder and a Submit button. Load this form into a browser to display it to a user.
Figure 20-7 A Form with a Single Product Finder and a Submit Button


If a count attribute was specified, the stylesheet generates an HTML page that contains the specified quantity of product finder forms and no Submit button (even if the count value was "1"). Load this page into a browser to display it to a user.
Figure 20-8 A Form with a Single Product Finder and No Submit Button


Figure 20-9 Three Forms with Identical Product Finders

For information about how to handle data that the user selects or submits, see Handling Product Finder Attributes that the User Selects.

Handling Product Finder Attributes that the User Selects

After the user selects attributes in the rendered product finder and submits the form, the browser generates POST data associated with the event. The POST data is a map (a set of name-value pairs) containing attributes and values that the user selected. You use the POST data to create a ProductSearch object to pass into GetProductSearchResultsCall.

Note: The Product Finder XSL stylesheet does not support the kind of SelectedAttributes node that the Item Specfics SYI XSL stylesheet supports.

To handle the user's selections:

If necessary, force the submit event once the user has made their selections.

If you specified the count XML attribute, the page is rendered without a Submit button. In this case, the client needs to be able to force the submit event. See Forcing the Product Finder Form Submit Event.

Use the nameValuesToAttributeSets( ) method on ProductFinderMaster to convert the selected attributes and values to a ProductSearch object that you can pass in GetProductSearchResultsCall input format. See Searching for Catalog Products.

Forcing the Product Finder Form Submit Event

If you render multiple identical product finders on the same page, you need to insert a count XML attribute in the ProductFinder node. The XSL uses the count attribute to determine how many HTML form elements to create (see Transforming the Product Finder XML). The resulting HTML document will contain separate form elements for each product finder.

When the page contains multiple form elements, the generated HTML page does not include a Submit button. Instead, the submit functionality is handled by means of a JavaScript function called attr_submit_multi(). When invoked, this function dynamically creates a temporary form element, collects the data from all the product finder forms on the page, appends the form index to each attribute and product finder identifier (e.g., "_2" for data on the second form), and then submits the data.

To get the current set of attributes and values for all the forms, the client needs to invoke the attr_submit_multi() JavaScript function. For example, a desktop client application could render the HTML page in a dialog and invoke the attr_submit_multi() function when the user clicks the dialog's OK button.

Several resources on the internet provide information about working with forms. See HTML Forms.

To force the submit action, access the document object (for Internet Explorer, see the IHTMLDocument2 interface), traverse the document's element collection (IHTMLElementCollection) to find the JavaScript function named attr_submit_multi(), and then invoke the function to submit the data.

Parsing the Product Finder Form POST Data

The Attributes Library includes a ProductFinderParamParser class that demonstrates how to parse the POST data generated from a product finder form. The ProductFinderMaster class uses this class (see the private nameValuesToAttributeSets( ) method).

If you choose to create your own implementation of IProductFinderMaster and the parser class, it may be helpful to understand the format of the POST data. The following information is mainly intended for developers who choose not to use the sample parser class.

When the user submits the product finder form (see Forcing the Product Finder Form Submit Event), the browser generates POST data associated with the event. The POST data contains the attributes and values the user selected. This section describes naming conventions that the scripts in the Product Finder XSL Stylesheet use to identify attributes and values in the POST data.

To identify attribute values selected by the user, the product finder form generates names by concatenating the following information (as applicable).

"a"|"t" + attributeID + meta-characters (if any) + "_" + formIndex

The underscore and form index (e.g., ("_3") are only generated if the ProductFinder.count XML attribute was specified. The index starts at 1 (not 0).

For the attrbute names, the following naming conventions are used, where the values in bold are literal and the values in italics are placeholders. The plus ("+") symbols are included here for readability only and do not appear in the actual POST data.

Table 20-3 Product Finder POST Data Naming Conventions 

Convention	Meaning
a+attributeId+_formIndex	This format (e.g., a25664_1) is generated for all attributes except those that represent date subcomponents, the low or high end of a range, or data-entry fields (input text boxes).
t+attributeId+_formIndex	This format (e.g., t12345_1) is generated for free-text attributes (i.e., attributes that are rendered as input text boxes). For example, "t3801_1" indicates that attribute 3801 is a simple text-entry field.
t+AttributeId+v+rangeIndex+_formIndex t+specifiers+_formIndex	This format (e.g., t72v1_1) is generated for free-text attributes that represent low and high ranges. For example, "t72v1_1" (or in some cases "taprclo_1") indicates that the attribute represents the low end in a range (also indicated by the rangeType xml attribute in the meta-data). Possible values of the range index: v1 = low value (e.g., t72v1_1) v2 = high value (e.g., t72v2_1)
a+attributeId+v+rangeIndex+_formIndex	This format is not used in current product finders (as of May 2004). In the future, this format will be generated for a numeric attribute in a range. Possible values of the range index: v1 = low value (e.g., a12v1_1) v2 = high value (e.g., a23v2_1)
a+attributeId+d|m|y+v+rangeIndex+_formIndex	This format is not used in current product finders (as of May 2004). In the future, this format will be generated for attributes that describe date subcomponents. Possible values of the date meta-character: d = day m = month y = year Possible values of the range index v1 = low value (e.g., a345yv1_1) v2 = high value (e.g., a456yv2_1)

Please note that value IDs are not unique across the site. Multiple values may be associated with the same value ID.

In addition, product finder IDs are identified by pfid in the POST data (e.g., "pfid=1833"). If multiple product finders were rendered, the submit function adds the form index as a suffix (e.g., "pfid_1=1833"). This is necessary because all the product finders have the same ID.

For example, suppose three Cell Phone Finders (all with ID = 1833) are rendered and the user selects attributes and values for one of them. In a Web-based application, the following query string would be generated (shown here with line breaks to make it more readable). Each query parameter specifies an attribute and a value or a product finder and its ID as a name=value pair. If the value is "-24", it means no value was selected.

Example 20-15 Query String for a Set of Product Finders 

?a25664_1=25633 // An attribute for product finder 1 &a25662_1=25624 &a34_1=1773 &pfid_1=1833 // ID of product finder 1 &a25664_2=-24 &a25662_2=-24 // No value selected for product finder 2 &a34_2=-24 &pfid_2=1833 // ID of product finder 2 &a25664_3=-24 &a25662_3=-24 &a34_3=-24 &pfid_3=1833 // ID of product finder 3