There are several ways customers might arrive at the ProductList server control, such as

• when a list of products appears on the side of a page
• through a link in a master page
• when they click Continue Shopping on the Cart or Checkout server control.

Inserting the ProductList server control onto a page

Prerequisite

You must have installed the server controls. See Installing server controls into Visual Studio Toolbox.

1. In Visual Studio, choose View > Toolbox.
2. Click the Ektron server control tab to display the server controls.
3. Drag the ProductList server control and drop it into the desired location on the page.

   NOTE: You also can place the cursor on the page where you want the server control, then double click the server control that you want.

   <CMS:ProductList ID="ProductList1" runat="server" />

4. Click on ProductList in the code to display and modify the control’s properties using the Properties window of Visual Studio. The page is updated as you modify the property values.
   —Image—

   

ProductList properties

The following are Ektron-specific server controla server control uses API language to interact with the CMS and Framework UI to display the output. A server control can be dragged and dropped onto a Web form and then modified. properties. For information about native .NET properties such as font, height, width and border style, use Visual Studio^® help.

• CacheInterval (Double)

  The number of seconds that a server controla server control uses API language to interact with the CMS and Framework UI to display the output. A server control can be dragged and dropped onto a Web form and then modified.’s data is cached. The default is 0 (zero). For example, if you want to cache the data for 5 minutes, set to 300. See also: Caching with server controls.

• CustomXml (Code-behind Only) (String)

  Lets you inject custom XML into the generated XML before being processed by the XSLTExtensible Stylesheet Language Transformations. Enter a string of XML that you want to make available to the XSLT as follows:

  <root><customXml>custom-xml-inserted-here</customXml></root>

  See also: Displaying custom XML in Ektron’s server controls.

• DisplayXslt (String)

  If desired, enter a relative or absolute path to an Xslt that determines the display of the page. By default, the control uses ProductList.xsl. This file is located in
  siteroot\Workarea\Xslt\Commerce.

  WARNING! Files stored in the siteroot\Workarea folder are overwritten (or deleted) when you upgrade Ektron. To avoid problems, copy the default file to a folder outside the siteroot\workarea folder then edit it. If there is no default file, create the file outside the siteroot\workarea folder. Next, in this property, enter the path to that file relative to the site root folder.

• DoInitFill (Boolean)

  By default, Fill occurs during the Page_Init event. Set to false if you want to postpone the fill-action until later. In this case, Fill is automatically called during the Page Render event. You might do this if you need to set or change a property on the control in code-behind and have it render with your changes shown.

• DynamicParameter (String)

  Sets the QueryString parameter to read a source’s ID dynamically. For example, if your QueryString parameter for a source ID is SID, enter that.

• GetAnalyticsData (Boolean)

  Set to true if you want the average rating for this product to appear with the product display, as shown below.

  

  Below the rating, a number indicates how many customers have rated the product. For information on customer product ratings, see ContentReview.

  IMPORTANT: This property provides reliable data only when the Business Analytics feature is on.

• Hide (Boolean)

  Hides or displays the output of the control in design time and run time.

  • True. Hide the control output.
  • False. Display the control output.
• IdList (String)

  Enter a comma-separated list of IDs if the SourceType property is set to IdList, TaxonomyList or CatalogList.

• Language (Integer)

  Set a language for viewing content; shows results in design-time (in Visual Studio) and at run-time (in a browser).

• LoadingImage (String)

  The image to display while the Product List is loading. The default is siteroot\Workarea\images\application\ajaxloader_circle_lg.gif.

  WARNING! Files stored in the siteroot\Workarea folder are overwritten (or deleted) when you upgrade Ektron. To avoid problems, copy the default file to a folder outside the siteroot\workarea folder then edit it. If there is no default file, create the file outside the siteroot\workarea folder. Next, in this property, enter the path to that file relative to the site root folder.

• OrderBy

  (SortMode property must be set to None)

  For further definition of the values shown here, see the entryPropertyenumeration in the API documentation.

  • AverageRating
  • CatalogId
  • CollItemsDisplayOrder (only available if SourceType property = Collection)
  • ContentStatus
  • CurrencyId
  • EndDate
  • EntryType
  • GoLIve
  • Html
  • Id
  • IsArchived
  • IsBuyable
  • IsPublished
  • LanguageId
  • LastEditDate
  • LastEditorFirstName
  • LastEditorLastName
  • ListPrice
  • Media
  • NumberRated
  • ProductTypeId
  • SalesPrice
  • Sku
  • Status
  • Summary
  • TaxClassId
  • TaxItemsDisplayOrder (only available if SourceType property = Taxonomy)
  • Title
  • ViewCount
• OrderByDirection (String)

  Select the direction of the OrderBy property. Choose Ascending or Descending.

• PageSize (Integer)

  Specify the number of items to show per page when a customer views the product list. If the number of items exceeds the quantity defined in this property, the list is paged and the customer can use the paging navigation system to move through the list.

• PageSpan (Integer)

  The number of pages to show before and after the current page. Enter zero to show all pages. For example, if you set this property to 2 and you are on page four of the product list, you see:

  

• SortMode (SortModes)

  Select the default way the product list is sorted when a customer first views the page. When the page is loaded, a customer can change the sort via a drop-down list. Choices are:

  • Title. Sorts in alphabetical order.

    

  • SKU. Sorts by the product number. This number is typically a unique number supplied by the producer of the product.
  • Price Descending. Sorts by price from highest to lowest.
  • Price Ascending. Sorts by price from lowest to highest.
  • Highest Rated. Sorts by rating from highest to lowest.
  • Lowest Rated. Sorts by rating from lowest to highest.
  • Most Rated. Sorts by products that have most ratings from highest to lowest.
  • None. Use this setting to use OrderBy property.

  See also: Sorting the product List.

• SourceId (Integer)

  The ID of the catalog, collectiona list of Ektron content links for display on a Web page. or taxonomya content-level categorization system that uses one-to-many relationships (such as Ronald Reagan is to Actor, Governor, and President) to create a scalable organization of content. A taxonomy lets your site visitors navigate content independent of the folder structure. that is being used as a product list. This property is used when the SourceType property is set to Catalog, Collection or Taxonomy.

• SourceType (SourceObjectType)

  The type of source being used to create the list. Choices are:

  • Catalog. Use the SourceId property to specify the ID of a single catalog when this source type is selected.
  • CatalogList. Use the IdList property to specify a list of catalog IDs when this source type is selected.
  • Taxonomy. Use the SourceId property to specify the ID of the single taxonomya content-level categorization system that uses one-to-many relationships (such as Ronald Reagan is to Actor, Governor, and President) to create a scalable organization of content. A taxonomy lets your site visitors navigate content independent of the folder structure. when this source type is selected.
  • TaxonomyList. Use IdList property to specify a list of taxonomy IDs when this type is selected.
  • IdList. Use the IdList property to specify a list of product IDs when this source type is selected.
  • Collection. Use the SourceId property to specify the ID of a collectiona list of Ektron content links for display on a Web page. when this source type is selected.
• Stylesheet (String)

  Specify the path to a style sheet for use with this server control. Leave blank to use the default style sheet. To use a custom style sheet, place it in a folder outside the siteroot\workarea folder then edit it. Next, in this property, enter the path to the custom style sheet relative to the site root folder.

• SuppressWrapperTags (Boolean)

  Suppresses the output of the span/div tags around the control.

  • True. Suppress wrap tags.
  • False (default). Allow wrap tags.
• TaxonomyDepth (Integer)

  Enter the number of taxonomya content-level categorization system that uses one-to-many relationships (such as Ronald Reagan is to Actor, Governor, and President) to create a scalable organization of content. A taxonomy lets your site visitors navigate content independent of the folder structure. levels to retrieve below each taxonomy/category. Only the top level appears in the control. The rest of the levels are available through XML in Code-behind. For example, if the taxonomy is DVDs > Movies > Comedies, and you set Taxonomy Depth to 2, only DVDs and Movies are available in Code-behind.

  To retrieve all categories for a taxonomy recursively, enter -1. A depth greater than 1 or using -1 is only useful if you create a custom output using the Taxonomy’s XML. The default value is 1.

  For a live site, Ektron strongly recommends leaving this value at 1. Increasing this value can slow down your live Web server. However, for testing on a staging server, you can increase the depth.

• TemplateProduct (String)

  Specify the URL that contains the Product server control. This allows a customer to see the details of the product when the product link is clicked.

Sorting the product List

The ProductList server control lets a customer sort by:

• Title
• SKU
• Price High to Low
• Price Low to High
• Highest Rated
• Lowest Rated and Most Ratings

You can set the default sort order by setting the SortMode property.

For the Highest Rated, Lowest Rated and Most Ratings sorting options to work as intended, a ContentReview server control should be associated with each product. This lets customers rate your products.

For example, place a ContentReview control on the Master page of the template that display products, and set its DynamicParameter property to ID. Then, when customers view the product, they can rate and comment on it.