Working with the Product Query Web Part

Article
11/17/2011

The Product Query Web Part provides flexible delivery of search results. You can use the result list to produce a full list of products in a category complete with paging, or a view of featured products. In addition, it may act as a master Web Part that feeds the list of products to other Web Parts through Web Part connections, such as a product editing Web Part. The Product Query Web Part supports the following URL parameters:

The category name or ID
The current page of product results

Architecture

The Product Query Web Part is an XSLT driven Web Part responsible for rendering a list of products within a category. In addition, the Product Query Web Part can expose its list of products to consuming Web Parts by acting as a provider Web Part through Web Part connections.

The sequence of actions of how this Web Part works is:

The category is provided by the SharePoint 2010 site through a configurable query parameter and is consumed by the Product Query Web Part.
The Product Query Web Part retrieves a list of products from Commerce Server 2009 R2, passing the category and the list of properties to retrieve.
After the Product Query Web Part retrieves the product list, it generates XML and then calls the XSLT provided by the user to produce HTML output.
The output HTML is rendered by the Product Query Web Part to the SharePoint 2010 site.

The list of products can be consumed by any other Web Part through Web Part connections if you configure it to do so.

Properties

The following table lists the properties that you can define for the Product Query Web Part.

Property	Type	Description	Default value
Template to Display	String	Template that displays the product’s details	Empty
Template Details	String	XSL style sheet	Empty
Save Current Template to Library	String	The name of the library in which to save the template	Empty

In addition, the following table lists the mapping of the properties for the Product Query Web Part.

Property	Map To	Type	Description	Default value
Channel	Channel	String	Sales channel.	"WebChannel"
Catalog	Catalog	String	Name of the Commerce Server 2009 R2 catalog from which products are retrieved.	Blank
Category	Category	String	Name of the category.	Blank
"Category Id" URL Parameter	CategoryIdUrlKey	String	URL Query string parameter to specify the category from which this web part will obtain Commerce products.	catalog
"Page Number" URL parameter	PageNumberUrlKey	String	URL query string parameter which may be used to specify the index of the page to display from a list of paged results.	page
"Sort By" URL parameter	OrderByUrlKey	String	URL query string parameter which may be used to specify the property to "sort by" when ordering displayed results.	orderby
"Sort Direction" URL parameter	OrderByDirectionUrlKey	String	URL query string parameter which may be used to specify the "sort direction" to be used when ordering displayed results.	dir
"Catalog" URL Parameter	CatalogUrlKey	String	URL query string parameter which may be used to specify the catalog from which this Web Part will obtain Commerce products.	catalog
Include "Cross Sells"	IncludeCrossSells	Boolean	Indicates whether to return cross-sell products for the products that are returned.	False
Include "Relationships"	IncludeRelationships	Boolean	Indicates whether to return relationships for the products that are returned.	False
Include "Up Sells"	IncludeUpSells	Boolean	Indicates whether to return up-sell products for the products that are returned.	False
Include "Variants"	IncludeVariants	Boolean	Indicates whether to return variants for the products that are returned.	False
Maximum # results per page	MaxResultsPerPage	Integer	Maximum number of products that you want to return per page.	10
"Sort By" options	SortingPropertiesTemplate	String	Specifies the available sorting options using a custom Xml-based configuration.	<SortOptionItems> <SortOption Name="ListPriceDesc" DataItem="ListPrice" AscOrder="false" DisplayText="List Price (Highest to lowest)"/>
Page title format	PageTitle	String	Sets the text format this Web Part will use to alter the web page title. The part of this value that contains "%Category%" will be replaced by the current category's display name at run-time.	"%Category%" to indicate that this is the value of the current catalog.

Customization

You can do customization through XSL transformations and Web Part parameters.

XSLT actions need to pass in two parameters when being instantiated. The first is a [ProductContext] that contains strongly typed properties that the XSLT action can query. The collection of products that the Product Query Web Part retrieves is made available to an XSLT action control through this [ProductContext]. The second is a collection of configuration settings that are defined in the markup of the XSLT action and that you use to configure the XSLT action. For instance, the pager XSLT action requires a value for the string to use to display as the text for a "Previous" button or for the "Next" button.

Configuration can be done through the Web Part's custom editor, called XsltTemplateEditorPart. This part is accessed through the Modify Web Part selection in the Edit menu of the Web Part when logged in as administrator to the site.

Clicking the ellipsis button (…) for the Template Details displays an editor where you can edit the XSL transform directly.

The following table lists the XSLT parameters that you can use to create your template.

XSLT Parameter	Description
_category	Name of the current category
_url	URL of the site (SPWeb.Url)
_userIsSiteAdmin	A value indicating whether the user has administrative rights on the Web site including Manage SubWebs, Manage Permissions and, and Manage Web Permissions
_catalog	Name of the current catalog
_channel	Name of the current channel
_userIsWebAdmin	A value indicating whether the user is a member of the administrators site group for this site
CurrencyCode	The currency code for the current catalog

To add custom XSLT parameters, use the Extensibility Kit to modify the Web Part.

When working with the Product Query Web Part you may want to view the raw XML that is rendered before the XSL transform is applied in order to optimize your XSLT code. The code below lets you view the raw XML:

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 <xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"/>
 <xsl:template match="/">
  <xmp><xsl:copy-of select="*"/></xmp>
 </xsl:template>
</xsl:stylesheet>

Note

When selecting the template properties by using the Select Properties Webpage dialog box, only the selected properties will be displayed by the Product Query Web Part.

Note

If you create a custom transform, you must select the property you want to display from both the Selected Properties and the Selected Variant Properties group in the Select Properties Webpage dialog box.

The following table details the configuration properties for each supported XSLT action:

XSLT Action	Configuration Property
PagerXsltAction
	ItemsPerPage
	TotalItems
	PageParameter
	NextButtonText
	PreviousButtonText
	CssClassDisabledControl
	CssClassEnabledButton
	CssClassPageSelected
	CssClassPageUnselected
VariantAddToCartXsltAction
	ProductId
	CatalogName
	DisplayAddToShopperList
	AddToShopperListDefault
	ImageButtonUrl

Error Handling

There is no design-time error handing required for this Web Part.

Design Time Validation

The following table lists the fields that the Product Query Web Part validates at design time.

Field	Description	Occurs	System response
XslTransform	Validates that the XSL transform is correctly formed.	When saving an XSLT template.	Displays an error indicating that the XSL transform is not valid.

Run Time Validation

The following table lists the fields that the Product Query Web Part validates at run time.

Field	Description	Occurs	System response
Category	Validates if the category is passed in as a query string URL parameter.	When rendering the Product Query Web Part.	Displays an error indicating that the category query string URL parameter is required.
MaxResultsPerPage	Validates if MaxResultsPerPage has been set.	When rendering the Product Query Web Part.	Displays an error indicating that the MaxResultsPerPage field is required.

API Dependencies

The dependencies on the API are:

Performing a full text query
Returning a list products for a specific category
Returning a list of products filtered by additional properties
Returning a subset of the list of products defined by the number of results to return (use for paging)
Must be able to sort the list of products by ascending or descending order by a given property
Must be able to support grandparent/grandchild relationships
Must be able to return up sells of products
Must be able to return cross sells of products
Must be able to return custom relationships of products
Must be able to return variants of products