Working with the Product Query Web Part
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
See Also
Other Resources
Developing with SharePoint Commerce Services