Working with the Item Specifics XSL Stylesheet

The diagram below illustrates the overall process that you follow in order to render an Item Specifics form and handle the attributes and values that the user selects. Each step is described in the sections that follow. The sample classes in the Attributes Library provide methods that you can use to handle most of this functionality.

Figure 20-2 Rendering Item Specifics Using the XSL

This section is organized into the following subsections:

Item Specifics SYI XSL Stylesheet Documentation

Patching the XML to Customize the Look and Feel

Storing the XML for Use with the Stylesheet

Transforming the Item Specifics XML (XML-to-HTML)

Handling Attributes that the User Selects

Converting Selected Attributes to AttributeSetType

Item Specifics SYI XSL Stylesheet Documentation

The Item Specifics SYI XSL stylesheet documentation describes the keys, variables, and templates that are defined in the syi_attributes.xsl stylesheet returned from your XSL data-source provider or GetAttributesXSLCall.

Item Specifics SYI XSL Stylesheet Documentation

eBay, Inc.

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

Patching the XML to Customize the Look and Feel

eBay strongly recommends that you avoid modifying characteristic set XMLs document and the Item Specifics SYI XSL stylesheet directly. Direct changes to the files returned from the meta-data function calls are not supported.

Presentation instructions can vary for different categories. The Item Specifics SYI XSL stylesheet is designed to work with these variations. If you want to modify the general look and feel of the Item Specifics form to match that of your application, you should not modify the presentation instructions or the Item Specifics SYI XSL stylesheet directly. Instead, apply another stylesheet that generates a new XML document with customized presentation instructions. In this documentation, this kind of stylesheet is referred to as a meta-data patching stylesheet.

If you choose to use this approach, you should apply a patching stylesheet to the GetAttributesCSCall or GetProductSellingPagesCall response before making any other changes to the XML as described in this guide. If you use the AttributesXmlDownloader class as your XML data-source provider, its GetMultipleCSXmlText( ) methodcalls the FixAttributesXml( ) to apply a default patching stylesheet that is included with the Attributes Library. This method in turn calls the GetDefaultStyleXsl( ) method to retrieve the patching stylesheet. If you are using the XML returned from GetProductSellingPagesCall, the AttributesXmlDownloader class will use the same method to apply the patching stylesheet. You can specify a different stylesheet by replacing the XSL stylesheet in the eBay.Service.SDK.Attribute\Resources directory.

For your convenience, this documentation set includes two examples of meta-data patching stylesheets that demonstrate how to change or add the following data:

Fonts and colors used for labels
Fonts and colors used within text boxes and other controls
Background colors
Fonts and colors used for text messages (e.g., error messages and informational messages)
The image that is used to identify required fields (e.g., "*")
The spacer image (used to control the distance between fields)
The maroon arrow image (used by some characteristic sets)
JavaScript code that you would like to include in the output HTML
The form name

Some applications need to strip the Head, Body, and Form elements from the HTML, so that only the Item Specifics data is generated. The match="/eBay" template in the sample meta-data patching stylesheets demonstrate how you can add instructions to only show the Item Specifics information. The patching stylesheets also demonstrate how to override the name of the form, which may be a necessary step for some applications.

When you apply one of the patching stylesheets provided with this documentation, it will also copy an API.XSL.Overrides node into the patched XML document. See Transforming the Product Finder XML for more information about this addition. If you create your own version of one of these stylesheets, you can use the same functionality.

See Sample Patching Stylesheets for links to the sample meta-data patching stylesheets.

Storing the XML for Use with the Stylesheet

This section is included here for your reference only. Most users of the eBay SDK for .NET can skip this section. You should not need to follow these steps unless you are working directly with the core GetAttributesCS and GetProductSellingPages request and response objects.

If you are using the Item Specifics XSL to render the GetAttributesCS or GetProductSellingPages XML data, you need to make some changes to the original (or patched) XML before you can render a particular set of characteristics. Depending on how you design your application, it may be useful to store some sections of the XML separately. ExtractMultiCSFromXml( )method on the AttributesXmlDownloader class extracts the correct characteristic set data from the attribute or product selling page meta-data for a list of characteristic set IDs that you specify. If you are using the AttributesXmlDownloader class as your XML data-source provider, the GetMultipleCSXmlText( ) method will invoke this method for you.

Storing the GetAttributesCS XML

Storing the GetProductSellingPages XML

Storing the GetAttributesCS XML

Most users of the eBay SDK for .NET can skip this section. Use the ExtractMultiCSFromXml( ) method to extract the characteristic set data from the XML returned from GetAttributesCSCall or your XML data-source provider. This section is being provided in case you are making modifications that require you to understand the underlying implementation of the call.

If you are using the Item Specifics XSL to render the XML returned from GetAttributesCS requests, you will need to make some changes to the original (or patched) XML before you can render a particular set of characteristics. Essentially, you will create a new working XML document to work with each time you render a particular set of Item Specifics (see Patching the XML to Customize the Look and Feel).

(Optional) Store the eBay start and end tags. Depending on how you choose to build your working XML document, you can either store these tags or just create them as needed later.
Store the Attributes node in its entirety (including all AttributeSet nodes). In most cases, there is no need to store each AttributeSet node individually. If you use the XSL stylesheet, the scripts that render the data will ignore any AttributeSet nodes that are not relevant to the Item Specifics being rendered.
(Optional) If you retrieved multiple characteristic sets in a single call, store the parent Characteristics start and end tags (as an empty node). Then, store each CharacteristicsSet child node separately, in its entirety. As you should render only one full set of Item Specifics at a time, this makes it easier to retrieve and insert the appropriate CharacteristicsSet node based on the category the user selects for a particular listing.
Store the GlobalSettings node in its entirety. This node provides a localized list of strings that are used when rendering date information. For example, it specifies full names and short names of days and months in the site's language. Even if you are working with a set of Item Specifics that contains no dates, it is a good idea to always include this node when you work with Item Specifics, in case eBay adds dates to the Item Specifics or adds other types of data to the global settings in the future.
If you applied the meta-data patching stylesheet to the original XML document, it will automatically insert an API.XSL.Overrides node into the patched document. Store the API.XSL.Overrides node.

For some applications, it may be most convenient to store the Attributes node, Characteristics start and end tags, the GlobalSettings node, and the API.XSL.Overrides node as a single document, and then later parse that document to determine where to insert the CharacteristicsSet node and other elements.

For other applications, it may be easier to store each node separately, and then build the working XML document by concatenating the necessary nodes.

Storing the GetProductSellingPages XML

Most users of the eBay SDK for .NET can skip this section. Use the ExtractMultiCSFromXml( ) method to extract the characteristic set data from the XML returned from GetProductSellingPagesCall or your XML data-source provider. This section is being provided in case you are making modifications that require you to understand the underlying implementation of the call.

If you are using the Item Specifics XSL to render the GetProductSellingPages data, you will need to make some changes to the original (or patched) XML before you can render a particular set of characteristics. Essentially, you will create a new working XML document to work with each time you render a particular set of Item Specifics (see Patching the XML to Customize the Look and Feel).

(Optional) Store the eBay start and end tags. Depending on how you choose to build your working XML document, you can either store these tags or just create them as needed later.
Store the Attributes node in its entirety (including all AttributeSet nodes and CategoryMappingDetails nodes, if any). In most cases, there is no need to store each AttributeSet node individually. If you use the XSL stylesheet, the scripts that render the data will ignore any AttributeSet nodes that are not relevant to the Item Specifics being rendered.
If you retrieved multiple products in a single call, store each Product node separately, in its entirety. For each Product node, save the value of Product.id, as you will need it to list the item.

You can remove and discard the start and end ProductSellingPages and Products container tags, as you will not need them.

Store the GlobalSettings node in its entirety. This node provides a localized list of strings that are used when rendering date information. For example, it specifies full names and short names of days and months in the site's language. Even if you are working with a set of Item Specifics that contains no dates, it is a good idea to always include this node when you work with Item Specifics, in case eBay adds dates to the Item Specifics or adds other types of data to the global settings in the future.
If you applied the meta-data patching stylesheet to the original XML document, it will automatically insert an API.XSL.Overrides node into the patched document. Store the API.XSL.Overrides node.

For some applications, it may be most convenient to store the Attributes node, the GlobalSettings node, and the API.XSL.Overrides node as a single document, and then later parse that document to determine where to insert the contents of the Product node.

For other applications, it may be easier to store each node separately, and then build the working XML document by concatenating the necessary nodes.

Transforming the Item Specifics XML (XML-to-HTML)

You can use the same stylesheet for rendering the XML returned from GetAttributesCSCall, and GetProductSellingPagesCall, or your XML data-source provider.

Transforming the GetAttributesCS XML (XML-to-HTML)

Transforming the GetProductSellingPages XML (XML-to-HTML)

Transforming the GetAttributesCS XML (XML-to-HTML)

The AttributesMaster class demonstrates how to apply an XSL stylesheet to an HTML document. It also demonstrates other useful functionality.

If you are presenting the meta-data in a graphical user interface, and if the user selects two categories that are mapped to different characteristic sets, we recommend that you display the full set of characteristics for the primary category and secondary category on separate pages.

If a category is also mapped to site-wide characteristic sets, you can render those characteristic sets on the same page as the full characteristic set.

Note: If you notice that an attribute (such as Condition) appears on the eBay Web site but not in the corresponding CharacteristicsSet node returned from GetAttributesCS, check to determine whether the category is also mapped to any site-wide characteristic sets. In some cases, certain attributes that appear on a single page on the site are defined as site-wide attributes, and will therefore appear in separate CharacteristicsSet nodes.

To transform the GetAttributesCSCall XML:

(Optional) If you want to customize the look and feel of the Item Specifics form, create a meta-data patching XSL stylesheet that overrides the presentation instructions in the characteristic set XML document. If you are using the AttributesXmlDownloader as your data-source provider, it uses a default patching stylesheet.

See Patching the XML to Customize the Look and Feel for examples of the kinds of changes you can make with patching stylesheets. Usually, you only perform this step once.

When your application needs to generate the Item Specifics form for a particular characteristic set, create an AttributeSet object and pass it in the RenderHtml( ) method defined on AttributesMaster to render the Item Specifics. Alternatively, use the RenderHtmlForCategories( ) method and pass in the category IDs.

If you are using the AttributesMaster class, you are done with the transformation. See Handling Attributes that the User Selects for next steps.

If you choose to implement your own version of the AttributesMaster class, you will need to modify the raw XML directly in order to render it using the Item Specifics XSL stylesheet. You can use the AttributesMaster 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 AttributesMaster class as part of your solution.

Determine the characteristic set ID for the Item Specifics you are rendering, and create a SelectedAttributes node that contains an AttributeSet node with the same ID.

Example 20-1shows a SelectedAttributes node for rendering a Cell Phone Accessories characteristic set, where the attribute set ID is 1786.

Example 20-1 A SelectedAttributes Node 

<SelectedAttributes> <AttributeSet id="1786"/> </SelectedAttributes>

 

Note: If you do not insert a SelectedAttributes node, the form will be rendered with a single drop-down list that lets the user select a category (actually, a characteristic set). If you choose to use this functionality, your application should intercept the submit action, determine the characteristic set that was selected, insert the correct SelectedAttributes node for that characteristic set, and then reapply the Item Specifics SYI XSL stylesheet (as described below) to render the Item Specifics form.

If you are rendering return policy options or auto-filling Item Specifics based on a listing's category, see these sections for additional changes to the SelectedAttributes node:
Rendering Return Policy Options
Auto-filling Attribute Values Based on a Listing's Category
Create a new XML document or modify your patched document such that your working XML document contains the following elements.
The eBay container (start and end) tags

Between the eBay start and end tags, insert the following nodes as siblings:

The SelectedAttributes node that you created above
The Attributes node (including all AttributeSet nodes it contains, and the CategoryMappingDetails node if any)
The Characteristics node, in which you should insert the CharacteristicsSet node that you want to render. Make sure the characteristic set ID matches the ID you specified in the SelectedAttributes.AttributeSet node.
The GlobalSettings node (including all its contents)
(If patched) The API.XSL.Overrides node

Some applications might be designed to retrieve each node string from a database or other storage mechanism and then concatenate the elements together to build the working document.

If the category supports site-wide characteristics, you can modify the Attributes Library to insert additional CharacteristicsSet nodes for each site-wide characteristic set in the same page location. The order in which you insert the site-wide CharacteristicsSet nodes controls the order in which they will be rendered. That is, if you insert the node before the full CharacteristicsSet node, the site-wide attribute will appear at the top of the page. If you insert the node after the full CharacteristicsSet node, the site-wide attribute will appear at the bottom of the page.

The example below shows the kinds of elements your working XML document should contain at this point.

Example 20-2 A GetAttributesCS XML Document 

<eBay>   <SelectedAttributes>     <AttributeSet id='1786' />     ... more empty AttributeSet elements for site-wide attributes ...   </SelectedAttributes>

<Attributes>     <AttributeSet id='1786'>       <DomainName><![CDATA[Cell Phone Accessories]]></DomainName>     </AttributeSet>     ... more AttributeSet nodes ...   </Attributes>

<Characteristics>     <CharacteristicsSet order='37' id='1786'>       ... all content for one full characteristic set...     </CharacteristicsSet>     ... more CharacteristicsSet nodes for site-wide characteristics ...   </Characteristics>

<GlobalSettings>     <MonthDescendingShort>Dec;Nov;Oct;Sep;Aug;Jul;Jun;May;Apr;Mar;Feb;Jan; </MonthDescendingShort>     <MonthAscendingLong>January;February;March;April;May;June;July;August;September;Octob er;November;December;</MonthAscendingLong>     <MonthAscendingShort>Jan;Feb;Mar;Apr;May;Jun;Jul;Aug;Sep;Oct;Nov;Dec;    </MonthAscendingShort>

<MonthDescendingLong>December;November;October;September;August;July;June;May;April;M arch;February;January;</MonthDescendingLong>   </GlobalSettings>   <API.XSL.Overrides>     <Styles>       ... patching content ...     </Styles>     <Use>       <Form name='YourFormName'/> // If used, specify your form name     </Use>   </API.XSL.Overrides> </eBay>

Make sure you are using the latest Item Specifics SYI XSL stylesheet (see Retrieving the Item Specifics SYI XSL Stylesheet).
Apply the Item Specifics SYI XSL sylesheet to the customized XML document. This generates the form in an HTML page. Load this form into a browser to display it to a user.

As different applications may need to render the page in different contexts, the form does not include a Submit button. The client needs to force the submit event. For example, if your application presents the Item Specifics form in a dialog, you can force the submit event when the user clicks the dialog's OK button. To force a submit action, access the browser's Form object and invoke its submit() method to trigger the POST event.

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

Rendering Return Policy Options

In the API, predefined return policy options are also described using the Attributes API. See Offering a Clear Return Policy for more information about working with return policy data. If an eBay site supports predefined return policy options, the full GetAttributesCSCall response includes a return policy characteristic set.

On the eBay site, the return policy form is not part of the Item Specifics form. It is a separate form within the Sell Your Item pages. This means return policies and Item Specifics have different page locations. To indicate this distinction, the return policy characteristic set's presentation instructions contain a pageLocation XML attribute (e.g., pageLocation="ReturnPolicy").

To render return policy attributes using the XSL stylesheet, follow the steps described in Transforming the GetAttributesCS XML (XML-to-HTML), but add a pageId="ReturnPolicy" XML attribute to the SelectedAttributes element.

Example 20-3 A SelectedAttributes Node for Return Policy Details (US Site) 

<SelectedAttributes pageId="ReturnPolicy"> <AttributeSet id="2135"/> </SelectedAttributes>

You cannot use the same form to render return policy attributes and Item Specifics. If you specify multiple AttributeSet nodes within the SelectedAttributes node, the resulting HTML page will only render the attributes whose page locations match the specified page ID. If no page ID is included, the default page location is the Item Specifics page. (There is no page location for Item Specifics.)

Auto-filling Attribute Values Based on a Listing's Category

In some cases, you may be able to auto-fill certain attribute values based on the category the user specified for the listing. The data returned from GetAttributesCS indicates the categories that support this feature. Important: This is not available by default in the current version of the eBay SDK for .NET. See GetAttributesCS for information on adding this feature.

There are two use cases:

The listing's category ID is current. That is, the latest version of the GetCategoriesCall response returns the category ID.
The listing's category is outdated, and you are mapping the old category ID to a new category ID on the client side (instead of allowing eBay to do it for you by using Item.CategoryBasedAttributesPrefill in your listing request).

See CategoryMappingDetails Elements for the logic behind these use cases.

The figure below shows an Item Specifics form with auto-filled attribute values.

Figure 20-3 Item Specifics Form With and Without Auto-Filled Attribute Values

Once you have rendered an auto-filled value for an attribute, the seller can still change the value if they want to. Once the seller changes the value or accepts the auto-filled value, you handle the attribute just as you would handle any other attribute the seller selects (see Handling Attributes that the User Selects). The auto-fill behavior is a just a convenient way to help the seller choose attributes that make sense for the specified category.

To auto-fill attribute values based on a category:

When you call GetAttributesCS, specify IncludeCategoryMappingDetails in the request object. (This is not available by default in the current version of the eBay SDK for .NET. See GetAttributesCS for information on adding this feature.) The response includes a CategoryMappingDetails node. See CategoryMappingDetails Elements for information about this data.
Follow the steps described in Transforming the GetAttributesCS XML (XML-to-HTML), but make the following additional changes:
If the listing's category ID is current (i.e., GetCategoriesCall currently returns it), add a categoryId="yourCategoryId" XML attribute to the SelectedAttributes.AttributeSet node (where yourCategoryId is the category ID used in the listing). Example 20-4 shows a SelectedAttributes node where Cell Phones : Accessories : Software : RIM Blackberry (115049) is specified as the category.

Example 20-4 A SelectedAttributes Node With a Category ID 

<SelectedAttributes> <AttributeSet id="1786" categoryId="115049"/> </SelectedAttributes>

If the listing's category is outdated and you are auto-filling attributes based on a mapping from an old category to a new one, add both the old and new category IDs to the SelectedAttributes.AttributeSet node. In the example below, yourOldCategoryId is the category ID used in the listing, and newCategoryId is the current category ID.

Example 20-5 A SelectedAttributes Node With a Category Mapping 

<SelectedAttributes> <AttributeSet id="value" categoryOldId="yourOldCategoryId" categoryId="newCategoryId"/> </SelectedAttributes>

If the CategoryMappingDetails node is present in your working XML document and it includes a CategoryMapping node for the category ID (or IDs) you specify, the data in the CategoryMapping node will be used to auto-fill some if your attribute values. Otherwise, the category ID you specify will be ignored.

The example below shows the kinds of elements your working XML document should contain at this point if you are auto-filling attribute values based on a current category.

Example 20-6 A GetAttributesCS XML Document With a Category ID 

<eBay>   <SelectedAttributes>     <AttributeSet id="1786" categoryId="115049" />     ... more empty AttributeSet elements for site-wide attributes ...   </SelectedAttributes>

<Attributes>     <CategoryMappingDetails>       <CategoryMapping id='115049'>         <AttributeSet id='1786'>           ... content, if category-based auto-fills are present ...         </AttributeSet>       </CategoryMapping>       ... more CategoryMapping nodes ...     </CategoryMappingDetails>     <AttributeSet id='1786'>       <DomainName><![CDATA[Cell Phone Accessories]]></DomainName>     </AttributeSet>     ... more AttributeSet nodes ...   </Attributes>

<Characteristics>     <CharacteristicsSet id='1786' order='37' >       ... all content for one full characteristic set...     </CharacteristicsSet>     ... more CharacteristicsSet nodes for site-wide characteristics ...   </Characteristics>

<GlobalSettings>     <MonthDescendingShort>Dec;Nov;Oct;Sep;Aug;Jul;Jun;May;Apr;Mar;Feb;Jan; </MonthDescendingShort>     <MonthAscendingLong>January;February;March;April;May;June;July;August;September;Octob er;November;December;</MonthAscendingLong>     <MonthAscendingShort>Jan;Feb;Mar;Apr;May;Jun;Jul;Aug;Sep;Oct;Nov;Dec;    </MonthAscendingShort>

<MonthDescendingLong>December;November;October;September;August;July;June;May;April;M arch;February;January;</MonthDescendingLong>   </GlobalSettings>   <API.XSL.Overrides>     <Styles>       ... patching content ...     </Styles>     <Use>       <Form name="YourFormName"/> // If used, specify your form name     </Use>   </API.XSL.Overrides> </eBay>

Transforming the GetProductSellingPages XML (XML-to-HTML)

You can use the same stylesheet for rendering the XML returned from GetAttributesCSCall, and GetProductSellingPagesCall, or your XML data-source provider. The intent of the XSL is to help you render the equivalent of the Item Specifics portion of the Title & Description page on the eBay site.

When using the syi_attributes.xsl stylesheet to render the XML returned from GetProductSellingPagesCall, you need to remove certain tags prior to the XML-to-HTML transformation. You can use the ExtractCSFromXml( ) method or the ExtractMultiCSFromXml( ) to do this.

To transform the GetProductSellingPagesCall XML:

(Optional) If you want to customize the look and feel of the Item Specifics form, create a meta- data patching XSL stylesheet that overrides the presentation instructions in the GetProductSellingPages XML document. If you are using the AttributesXmlDownloader as your data-source provider, it uses a default patching stylesheet.

See Patching the XML to Customize the Look and Feel for examples of the kinds of changes you can make with patching stylesheets. Usually, you only perform this step once.

When your application needs to generate the Item Specifics form for a particular product, set the ProductID property, and then pass the AttributeSet object in the RenderHtml( ) method defined on AttributesMaster to render the product selling page. The AttributeSet class is included in the Attributes Library and extends AttributeSetType.

If you are using the AttributesMaster class, you are done with the transformation. See Handling Attributes that the User Selects for next steps.

If you choose to implement your own version of the AttributesMaster class, it may be helpful to understand how to modify the raw XML directly in order to render it using the Item Specifics XSL stylesheet. You can use the AttributesMaster 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 AttributesMaster class as part of your solution.

Create a SelectedAttributes node that contains an AttributeSet node with an ID that matches the product's characteristic set ID.

Example 20-1shows a SelectedAttributes node for rendering a book characteristic set, where the ID is 1388.

Example 20-7 A SelectedAttributes Node 

<SelectedAttributes> <AttributeSet id="1388"/> </SelectedAttributes>

Create a new XML document or modify your patched document such that your working XML document contains the following elements.
The eBay container (start and end) tags

Between the eBay start and end tags, insert the following nodes as siblings (without the Product parent node):

The SelectedAttributes node that you created above
The DataElements node (including all its contents)
The ProductInfo node
The Attributes node (including all AttributeSet nodes it contains)
The Characteristics node, in which you should insert the CharacteristicsSet node that you want to render. Make sure the characteristic set ID matches the ID you specified in the SelectedAttributes.AttributeSet node.
The GlobalSettings node (including all its contents)
(If patched) The API.XSL.Overrides node

Do not insert the Product start and end tags into the working XML document. That is, make sure only the DataElements, ProductInfo, Attributes, Characteristics, and GlobalSettings nodes (and the API.XSL.Overrides node, if used) are all children of the eBay node. However, keep track of the current product's ID, as you will need it to list the item.

Some applications might be designed to retrieve each node string from a database or other storage mechanism and then concatenate the elements together to build the working document.

If the category supports site-wide characteristics, you can insert additional CharacteristicsSet nodes for each site-wide characteristic set. The order in which you insert the site-wide CharacteristicsSet nodes controls the order in which they will be rendered. That is, if you insert the node before the full CharacteristicsSet node, the site-wide attribute will appear at the top of the page. If you insert the node after the full CharacteristicsSet node, the site-wide attribute will appear at the bottom of the page.

The example below shows the kinds of elements your working XML document should contain at this point.

Example 20-8 A GetProductSellingPages XML Document 

<eBay>   <SelectedAttributes>     <AttributeSet id="1388"/>     ... more empty AttributeSet elements for site-wide attributes (DE/AT/CH only) ...     </SelectedAttributes>   <DataElements>     ... DataElement nodes ...   </DataElements>   <ProductInfo>     <Title><![CDATA[Harry Potter and the Chamber of Secrets (2003)]]></Title>     ... product flags and copyrights ...   </ProductInfo>

<Attributes>     <AttributeSet id="1388">       ... content ...     </AttributeSet>     more AttributeSet nodes ...   </Attributes>   <Characteristics>     <CharacteristicsSet order="1" id="1388">       ... presentation instructions, domain, characteristics list ...     </CharacteristicsSet>     ... more CharacteristicsSet nodes for site-wide attributes (DE/AT/CH only) ...   </Characteristics>

<GlobalSettings>     <MonthDescendingShort>Dec;Nov;Oct;Sep;Aug;Jul;Jun;May;Apr;Mar;Feb;Jan; </MonthDescendingShort>     <MonthAscendingLong>January;February;March;April;May;June;July;August;September;Octob er;November;December;</MonthAscendingLong>     <MonthAscendingShort>Jan;Feb;Mar;Apr;May;Jun;Jul;Aug;Sep;Oct;Nov;Dec; </MonthAscendingShort>     <MonthDescendingLong>December;November;October;September;August;July;June;May;April;M arch;February;January;</MonthDescendingLong>   </GlobalSettings>   <API.XSL.Overrides>     <Styles>       ... patching content ...     </Styles>     <Use>       <Form name="YourFormName"/> // If used, specify your form name     </Use>   </API.XSL.Overrides> </eBay>

Make sure you are using the latest Item Specifics SYI XSL stylesheet (see Retrieving the Item Specifics SYI XSL Stylesheet).
Apply the Item Specifics SYI XSL sylesheet to the customized XML document. This generates the form in an HTML page. Load this form into a browser to display it to a user. If you are using the AttributesMaster class, the RenderHtml( ) method makes all the changes described above and renders data for you.
Figure 20-4 Product Item Specifics Form (with Patching Stylesheet Applied)

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

Handling Attributes that the User Selects

After the user selects Item Specifics 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 this data to validate the user's selections and, if necessary, present error messages if to the user. You also use the final set of POST data to create an AttributeSet object to set on the item's attribute set array.

If you just want to refresh the page without performing any validations, convert the POST data to a an IKeyValueCollection object (in a Web-based application, just get the parameter map from the HTTP request object) and pass it as an argument to the RenderHtmlForPostback( ) method on AttributesMaster. This method has two parameters. In this case, just pass null as the errorList argument.

The Item Specifics SYI XSL stylesheet includes JavaScript code. The resulting HTML form also contains this JavaScript code. When the user selects values from a drop-down list, the JavaScript may submit the form. This form submission is not intended to submit data to eBay; it is intended to retrieve dependent attributes and values and update the form. Your application's server-side logic needs to handle the submit event. Use the Attributes Library to handle this functionality.

Here is one way to handle submit events that are fired by the JavaScript:

Add a Form tag to the HTML page.
When the form submits, parse the POST data to determine the attribute and value IDs that were selected (see Parsing the Item Specifics Form POST Data).
Patch the XML document by placing the attribute values that the user has selected into the SelectedAttributes node (see Parsing the Item Specifics Form POST Data).
Transform the XML document again by using the Item Specifics SYI XSL stylesheet. See Transforming the Item Specifics XML (XML-to-HTML).

This renders the form with the updated Item Specifics fields.

When the user is ready to submit the listing and you want to validate their selections, you can use a process like this to handle the attributes the user selects:

Convert the POST data (i.e., the query string) to a Map object (in a Web-based application, just get the parameter map from the HTTP request object) and pass it as an argument to the NameValuesToAttributeSets( ) method on AttributesMaster. This returns the data as an array of AttributeSet objects.
(Optional) Validate the input data by using the Validate( ) method on AttributesMaster. This returns a collection of ErrorSet objects (if any errors were found). and, if necessary, add Error nodes to the new XML document (see Generating Error Messages in the Item Specifics Form).
Call the RenderHtmlForPostback( ) method on AttributesMaster and pass in AttributeSet object and the ErrorSet collection to render the Item Specifics information again with any errors that were found.
When the user is satisfied with their selections and submits the form again, collect the new POST data and use theNameValuesToAttributeSets( ) method to create an AttributeSet object. You then set this object on Item.AttributeSetArray and set the item on AddItemCall (see Listing an Item with Attribute and/or Product Data).

Forcing the Item Specifics Form Submit Event

Some user actions within the browser window cause an event to be sent to the client. The POST data associated with the event contains the attributes and values the user selected. See Parsing the Item Specifics Form POST Data for the naming conventions that are used to identify attributes and values in the POST data.

Some user actions do not cause any event to be sent to the client. In this case, to get the current set of values the client needs to force the submit event. For example, if your application presents the Item Specifics form in a dialog, you can force the submit event when the user clicks the dialog's OK button. To force a submit action, access the browser's Form object and invoke its submit() method to trigger the POST event.

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

Parsing the Item Specifics Form POST Data

The Attributes Library includes an AttrParamParser class that demonstrates how to parse the POST data generated from an Item Specifics form. The AttributesMaster class uses this class (see the private extractOneCat( ) method).

If you choose to create your own implementation of IAttributesMaster 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 selects values or submits the Item Specifics form, 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 Item Specifics SYI XSL stylesheet uses to identify attributes and values in the POST data.

To identify attribute values selected by the user, the match="Input" template in the Item Specifics SYI XSL stylesheet generates names by concatenating this information:

"attr" + "_" + metacharacter + characteristic set ID + "_" + attribute ID + "_" + metacharacter

The following naming conventions are used, where the values in bold are literal and the values in italics are placeholders.

Table 20-1 Attribute POST Data Naming Conventions 

Convention	Meaning
attr_tCSId_attributeId	This format is generated for attributes that are to be displayed in text boxes, including other-value attributes (id="-6").
attr_dCSId_attributeId_metacharacter	The ending metacharacter is either m (month), d (day), or y (year). This format is generated for date drop-down lists if the format of the attribute matches the format char_char_char (e.g., "m_d_y") and the widget is a date (type="date"). For example, for a Year attribute with id = 2 in the characteristic set whose id = 10, a drop-down list is generated with the name "attr_d10_2_y".
attr_dCSId_attributeId_c	This format is generated for attributes that should be displayed as text boxes containing a full calendar date (e.g., "05/10/06") .
attr_required_CSId_attributeId=true:	This format is generated to identify attributes that become required according to Type 5, Value-to-Meta-data (VM) dependencies. See Child Required-Status Dependencies (Type 5: Value-to-Meta-data).
attrCSId_attributeId	This format is generated for all other attributes.

For other-value text boxes, multi-select lists, and check boxes, multiple values can be associated with the same ID.

For example, suppose a user submits Item Specifics for a characteristic set with ID = 10110. In a Web-based application, the following query string might be generated (shown here with line breaks to make it more readable).

Example 20-9 Query String for a Characteristic Set 

http://localhost:9080/AttrPrototype/AttrPage? vcsid=10110&attr_d10110_8050_c=&attr_d10110_8051_c=&attr10110_8052=6000 &attr10110_8053=-6                         // "Other" selected &attr_t10110_8055=Some+test+value &attr_t10110_8056=555-555-5555            // Literal entered in normal text box &attr10110_8057=22754&attr10110_8057=22755&attr10110_8057=22756    // Multi-select list &attr_t10110_8062=&attr_t10110_8063=&attr_t10110_8065=&attr_t10110_8064= aus_form_changed=1&ButtonLoad=1

In this case, the application would generate a SelectedAttributes node that looks like the one shown in Example 20-10. RenderHtml( ) method on the AttributesMaster class demonstrates how to generate this node.

Important: If you pass a literal value (instead of a value ID) for an attribute in the SelectedAttributes node, you need to use the Name tag (consistent with the GetAttributesCSCall response). The stylesheet does not support the ValueLiteral field that is used in AddItemCall.

Example 20-10 A SelectedAttributes Node 

<SelectedAttributes> <AttributeSet id="10110"> <Attribute id="8057"> // Multi-select list <Value id="22754"/> <Value id="22755"/> <Value id="22756"/> </Attribute>

<Attribute id="8053"> <Value id="-6"/> // "Other" selected </Attribute> <Attribute id="8052"> <Value id="6000"/> </Attribute> <Attribute id="8065"> <Value> <Name/> </Value> </Attribute>

<Attribute id="8064"> <Value> <Name/> </Value> </Attribute> <Attribute id="8063"> <Value> <Name/> </Value> </Attribute>

<Attribute id="8062"> <Value> <Name/> </Value> </Attribute> <Attribute id="8056"> <Value> <Name>555-555-5555</Name> // Literal entered in normal text box </Value> </Attribute>

<Attribute id="8055"> <Value> <Name>Some test value</Name> </Value> </Attribute> <Attribute id="8050"> <Value> <Name/> </Value> </Attribute>

<Attribute id="8051"> <Value> <Name/> </Value> </Attribute> </AttributeSet> </SelectedAttributes>

Generating Error Messages in the Item Specifics Form

The Item Specifics SYI XSL stylesheet contains an AttributeError XSL template that will render an Errors node that adheres to a particular structure in the XML document. If you decide to use a different error structure or different error messages in your form, override the AttributeError XSL template by creating a higher-level XSL stylesheet. The stylesheet should import the main Item Specifics SYI XSL and define the AttributeError template.

If you want to validate the user's input and to display error messages inline on the Item Specifics page, you can use the Validate( ) method defined on AttributesMaster and pass in a collection of AttributeSet objects that contain the data the user selected.

If you are creating your own implementation of AttributesMaster, these are the basic steps you would need to perform:

Parse the XML that you built after the user posted their selections. This is the file that contains the SelectedAttributes node. One way to do this is to create a another new XSL stylesheet that validates the selected values against the validation rules of the corresponding attributes. Alternatively, parse the input values in the code. The output should be an Errors node. If you use the AttributeError template provided in the XSL stylesheet, you will need to place error messages inside the Errors node, in a manner consistent with its structure. See Displaying Input Error Messages for more information about the Errors node.
Add the generated XML (with the Errors node) to the previous XML that contains the SelectedAttributes node (the XML that was used as an input XML to generate the Errors node in step 1).
Apply the main Item Specifics SYI XSL stylesheet (or, if you created one, your higher level template as described above) to the result to generate the final HTML page with the errors.

Note: You can provide the error messages based on eBay error codes, or you can generate them in step 1 along with other error data. Displaying error messages (and displaying them inline) is optional. You are not required to display validation errors prior to executing AddItemCall. However, AddItemCall (and related calls) may fail if the user selects invalid combinations of values or enters invalid data.

Converting Selected Attributes to AttributeSetType

The Attributes Library and sample classes handle the following functionality for you. This section is being provided for developers who determine that they have a need to extend the capabilities of the Attributes Library.

After the user has finalized their attribute selections, you will need to set the AttributeSetArray.AttributeSet property on your Item object.

The NameValuesToAttributeSets( ) method on AttributesMaster converts the query string to an AttributeSet object. It is possible that some applications will need to modify this behavior. You can build the AttributeSet object based on the query string (see Handling Attributes that the User Selects), the SelectedAttributes node, or from data stored in a database. The examples below show you the relationship between the query string and an AttributeSet object.

Suppose a user submits Item Specifics for a Ticket (characteristic set ID = 1). Table 20-2 shows examples of the attributes and values a user might select. In this case, only a few attributes were specified. Other attributes were left blank.

Table 20-2 Item Specifics Selected for a Ticket 

Attribute Name	Attribute ID	Value	Value ID
Event Type	40	Concerts	1001
Event Type 2	37	Rock/Pop/Altern.	1024
Number of Tickets	1	2	1026
Venue State/Province	9	California	1039

In a Web-based application, a query string like the one shown in Example 20-11 would be generated (shown here with line breaks to make it more readable). Values of "-10" indicate that no value was selected for the attribute.

Example 20-11 POST Data Generated from Tickets Item Specifics 

vcsid=1 &attr1_40=1001 &attr1_37=1024 &attr1_1=1026 &attr1_9=1039 &attr1_10=-10 &attr_t1_10400= &attr_t1_10399= &attr1_2=-10 &attr1_3=-10 &attr1_4=-10 &ActionAttributeLoad=&aus_form_changed=default&ButtonLoad=default

See the AttrParamParser code sample in the Attributes Library for a detailed example of how to parse the query string. The Attributes Library includes an AttributeSet class that extends AttributeSetType

The NameValuesToAttributeSets( )method on the Attributes Master calls the AttrParamParser class to parse the query string.

Example 20-12 shows an example of a corresponding AttributeSetArray node that would be created for AddItemCall. )

Example 20-12 An AttributeSetArray Node in AddItemCall 

<Item> <AttributeSetArray> <AttributeSet attributeSetID="1"> <!-- Event Type --> <Attribute attributeID="40"> <Value>             <!-- Concerts --> <ValueID>1001</ValueID> </Value> </Attribute> <!-- Event Subtype (depends on Event Type) --> <Attribute attributeID="37"> <Value> <!-- Rock/Pop/Altern. --> <ValueID>1024</ValueID> </Value> </Attribute>

<!-- Venue State/Province (required) For some Venue State/Provinces, you may also be required to add attribute 62 and specify a Face Value. --> <Attribute attributeID="9"> <Value> <!-- California --> <ValueID>1039</ValueID> </Value> </Attribute> <!-- Venue City (depends on Venue State/Province) --> <Attribute attributeID="10"> <Value>              <ValueID>-10</ValueID> </Value> </Attribute>         <!-- Number of tickets (required) --> <Attribute attributeID="1"> <Value> <!-- 2 --> <ValueID>1026</ValueID> </Value> </Attribute>       </AttributeSet> </AttributeSetArray>