Integrating the Product Image Management Tool

The Product Image Management tool is an application that you use to create relationships between products or variants and images. You open the Product Image Management tool from the Commerce Server Business Administration Ribbon.

This document contains the following topics:

• Properties

• Product Image Association Storage

• Considerations for Working with the Service Catalog

• Migrating From a Single Image Site to a Multi-Image Site

• Localization

• Integrating the Product Image Management tool

Properties

The following table lists and describes the properties for the Product Image Management tool.

You configure the IsMultipleMode property in the ChannelConfiguration.xml file located in the root of the server (c:\inetpub\wss\VirtualDirectories\[your admin site's port]\).

<ComponentConfigurations>
    <Configuration customElementName="CommerceImageCatalogConfiguration" customElementType="Microsoft.Commerce.SequenceComponents.Components.CommerceImageCatalogConfiguration, Microsoft.Commerce.SequenceComponents, Version=9.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35">
      <CommerceImageCatalogConfiguration IsMultipleMode="true" ImageCatalogName="Service Catalog" ImageCategoryName="Image Associations" CategoryDefinition="ImageCategory" ImageProductDefinition="Image" ImageFileNameProperty="Image_filename"  LineItemImageProperty="_product_Image_FileName"/>
   </Configuration>                                                    
</ComponentConfigurations>

Product Image Association Storage

Images relationships are stored differently for single image mode and multiple image mode. In single image mode a product property, Image_filename, is used to set/store the Primary image path.

In multiple image mode, the Service catalog will be used to store multi-image information for a product and a variant. Each image can have two versions: a full size image and a thumbnail one.

All image associations are stored under the Image Associations category of the Service Catalog. The Image Associations category has a child category for each product that has associated images. Product image associations are stored in the product category, and each variant has a child category under the product category.

Considerations for Working with the Service Catalog

In cases where the Service Catalog is used for multi-image associations support, the product catalog (such as the Adventure Works Catalog) has a dependency on the Service Catalog. As a result, the Service Catalog, upon which product catalogs rely for storing images, must always be the first catalog imported in the Commerce Server 2009 R2 database. This import order (Service Catalog first, then dependent product catalogs) also applies when new product images are added to the service catalog.

Migrating From a Single Image Site to a Multi-Image Site

Use the following procedure to migrate from an existing single image site to a multi-image site.

To migrate from a single image site to a multi-image site

1. Import the CS2009_ServicecatalogNoData.xml file that will be used to store the product image and variant image associations.

2. Modify the ChannelConfiguration.config file to change IsMultipleMode from false to true. Specify the Service Catalog name, product definition, and category definition to use for the images.

   <ComponentConfigurations>
       <Configuration customElementName="CommerceImageCatalogConfiguration" customElementType="Microsoft.Commerce.SequenceComponents.Components.CommerceImageCatalogConfiguration, Microsoft.Commerce.SequenceComponents, Version=9.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35">
         <CommerceImageCatalogConfiguration IsMultipleMode="true" ImageCatalogName="Service Catalog" ImageCategoryName="Image Associations" CategoryDefinition="ImageCategory" ImageProductDefinition="Image" ImageFileNameProperty="Image_filename"  LineItemImageProperty="_product_Image_FileName"/>
   </ComponentConfigurations>
   

3. Modify the Silverlight configuration on the server to specify the Service Catalog name and URL path to the Image Gallery (SPList URL or the URL to the top images folder). For the Microsoft Internet Information Services (IIS) stored Image Gallery, the ImageGalleryProcessor component must specify the file path to the folder that maps the images folder URL.

   <MessageHandler name="CommerceQueryOperation_SharepointListItem" responseType="Microsoft.Commerce.Contracts.Messages.CommerceQueryOperationResponse, Microsoft.Commerce.Contracts, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
           <OperationSequence>
             <Component name="Authorization" type="Microsoft.Commerce.SequenceComponents.Components.AuthorizationSequenceComponent, Microsoft.Commerce. SequenceComponents, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35" />
             <Component name="SharepointListItem_Processor" type="Microsoft.Commerce.SequenceComponents.Components.SharepointListItemProcessor, Microsoft.Commerce. SequenceComponents, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
               <Configuration customElementName="SharepointImageGalleryListConfiguration" customElementType="Microsoft.Commerce. SequenceComponents.Components.SharepointListItemConfiguration, Microsoft.Commerce. SequenceComponents, Version=1.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
                 <SharepointImageGalleryListConfiguration SPSiteUrl="http://machine_name:1111" ListId="Images" ActiveView="" MaxReceivedMessageSize="" />
               </Configuration>
             </Component>
           </OperationSequence>
         </MessageHandler>
         <MessageHandler name="CommerceQueryOperation_ImageGallery" responseType="Microsoft.Commerce.CommerceQueryOperationResponse, Microsoft.Commerce, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
           <OperationSequence>
             <Component name="Authorization" type="Microsoft.Commerce.SequenceComponents.Components.AuthorizationSequenceComponent, Microsoft.Commerce.SequenceComponents, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35" />
             <Component name="Sharepoint Image Gallery Processor" type="Microsoft.Commerce.SequenceComponents.Components.SharepointImageGalleryProcessor, Microsoft.Commerce.SequenceComponents, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
               <Configuration customElementName="SharepointImageGalleryProcessorConfiguration" customElementType="Microsoft.Commerce.SequenceComponents.Components.SharepointImageGalleryProcessorConfiguration, Microsoft.Commerce.SequenceComponents, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
                 <SharepointImageGalleryProcessorConfiguration listUrl="/PublishingImages" />
               </Configuration>
             </Component>
           </OperationSequence>
         </MessageHandler>
   

4. Replace the existing Image Viewer Web Part on the site with the Multi-Image Viewer Web Part.

Localization

There are two localizable image properties: Name and Description. You access these properties from the Manage Fields In drop-down list in the Product Image Management application. After you select the languages that you want, the Name and Description fields display in all languages at the same time. Click Save to save the changes to the server.

Integrating the Product Image Management tool

The following sections describe how to integrate the Product Image Management tool into a web page and into the Commerce Server Business Administration Ribbon.

Html environment

The Product Image Management tool requires certain Silverlight initialization parameters and JavaScript functions to gather information about the product that is being edited. You can have the system pass the initialization parameters directly to the component by using the InitParams property on the Silverlight component. If the InitParams property does not specify a value, the Product Image Management tool calls the function MSCS_GetParameter.

Script functions

The Product Image Management tool depends on the following script functions. Add these either directly or via a script tag link (using the "src" attribute) on any page that uses the Product Image Management tool.

Parameters Used with the MSCS_GetParameter Function

The following table contains the parameter names and a description of the values returned by the MSCS_GetParameter function.

Expected resources

The following is an example of the various resources expected by the application. These lines should be in one or more resource files on the server and marked for downloading by the application by putting the resource file names in the ResourceFileUrisinit parameter.

<ResourceDictionary
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:mCore="clr-namespace:Microsoft.Commerce.BusinessManagement;assembly=Microsoft.Commerce.BusinessManagement"
    xmlns:services="clr-namespace:Microsoft.Commerce.Services;assembly=Microsoft.Commerce.Services.Silverlight"
>
    
<!-- The following converter is used by the UI to convert file names into image sources.
The path value should represent the root folder on the Web site where the images can be found.
Note that the ~ gets replaced by the name of the folder containing the ClientBin folder. This replacement is handled by the default StringToUriConverter.
 -->
    <mCore:PathToImageSourceConverter x:Key="CatalogImageNameToImageSourceConverter" Path="~/PublishingImages/" StringToUriConverter="{StaticResource StringToUriConverter}" />
<!-- The following settings represent the service connection settings.
Note that the ~ gets replaced by the name of the folder containing the ClientBin folder. This replacement is handled by the default StringToUriConverter.
-->
    <services:CommerceServiceSettings
        x:Key="CommerceServiceSettings"
        EndpointAddress="~/Router/RouterService.svc"
        DefaultChannel="Default"
        MaxReceivedMessageSize="2000000"
        BasicHttpSecurityMode="Transport"
       UriConverter="{StaticResource StringToUriConverter}" />
<!-- The following restricts the number of images for products to 4. You can change this to any value
that you want. Note, however, that anything below 1 will prevent images from being added. --> 
       <sys:Int32 x:Key="MaximumNumberOfProductImages">4</sys:Int32>
<!-- The following restricts the number of images for each product variant to 4. You can change this to any value
that you want. Note, however, that anything below 1 will prevent images from being added. -->
       <sys:Int32 x:Key="MaximumNumberOfVariantImages">4</sys:Int32>
</ResourceDictionary> 

Integration in a Web Site

You can use the Product Image Management tool on any Web site. The details about how the application will be triggered and displayed are up to the implementer as this can be done in a variety of ways. For example, the site may use another Silverlight application to trigger the display, or simply add buttons embedded in appropriate places in the page mark-up. The Silverlight application may then "pop-up" or "pop-in", or be displayed in a frameset, and so on. You must remember to consider authentication to prevent unauthorized users from accessing this functionality.

Use the HTML Object tag to integrate a Silverlight application (see the Silverlight documentation for more information). The only requirements are to provide correct initParameters (see Parameters Used with the MSCS-GetParameters Function for the list of valid parameter names and values), and to set up at least one resource file on the server containing the appropriate settings.

Integration in a Toolbar

To use the Product Image Management tool in the Commerce Server Business Administration Ribbon, you must create a toolbar module configuration file, and you must reference this file in the Commerce Server Toolbar configuration.

To integrate the Product Image Management tool into the Business Administration Ribbon

1. Create a toolbar module configuration file called MicrosoftCommerceCatalogImageManager.xml and add the following code (See Business Administration Ribbon for details):

   <?xml version="1.0" encoding="utf-8" ?>
   <Plugin>
     <Context>Product</Context>
     <ControlName> Microsoft.Commerce.BusinessManagement.CatalogImagesManager.Controls.PlugIn</ControlName>
     <Assembly> Microsoft.Commerce.BusinessManagement.CatalogImagesManager.Application.dll</Assembly>
     <Xap> MicrosoftCommerceCatalogImagesManager.xap</Xap>
   </Plugin>
   

2. Create the server-side resources file needed by this module. The recommended name is MicrosoftCommerceCatalogImageManagerResources.xaml. The file must contain the following:

   <ResourceDictionary
   xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation" 
   xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
     xmlns:sys="clr-namespace:System;assembly=mscorlib"
   >
   
   <!-- The following restricts the number of images for products to 4. You can change this to any value that you want. Note, however, that anything below 1 will prevent images from being added. -->
       <sys:Int32 x:Key="MaximumNumberOfProductImages">4</sys:Int32>
   
   <!-- The following restricts the number of images for each product variant to 4. You can change this to any value that you want. Note, however, that anything below 1 will prevent images from being added. -->
       <sys:Int32 x:Key="MaximumNumberOfVariantImages">4</sys:Int32>
   
   </ResourceDictionary>
   

   Note

   This file identifies fewer resources than described for the simple ASP.NET integration. This is because it is assumed the other configuration is specified in the shared configuration file for the Commerce Server Business Administration Ribbon (CsManagementResources.xml).

3. Copy these three files to the virtual directory of the business user web application: c:\inetpub\wwwroot\wss\virtualdirectories\[port of the business user web application or host header]

   • MicrosoftCommerceCatalogImagesManager.xap

   • MicrosoftCommerceCatalogImagesManager.xml

   • MicrosoftCommerceCatalogImageManagerResources.xaml

4. Make changes to the MSCS_GetParameter function in the file CommerceManagement.js to return values for the following parameter keys:

   • Catalog

   • CatalogItemType

   • CatalogItemId

5. You should prepare your site to make these values available in the HTML mark-up so that when the Silverlight application calls the script function, the latter is able to produce a value.

   Note

   Expecting values to be in the URL (such as query-string parameters) may not be sufficient if that information cannot be guaranteed to always be present.

6. Make changes to the Toolbar.xml configuration file to add this component to its display. In the toolbar configuration file, find the TabItem in which you want this module to display, and add the following:

   <controls:ToolBarModule ConfigFile="MicrosoftCommerceProductImageEdit.xml" x:Name="moduleProductImageEdit">
           <controls:ToolBarModule.InitResources>
             <ResourceDictionary>
               <sys:String x:Key="OnClick">FloatSilverlight("ProductImageEditSilverlight", "/ClientBin/MicrosoftCommerceCatalogImagesManager.xap", "ResourceFileUris=CsManagementResources.xml MicrosoftCommerceCatalogImageManagerResources.xml", 100, 10, 800, 650, 525, 630, true, "App.RequestClose()")</sys:String>
               <mCore:LocalizedValueDictionary x:Key="Label">
                 <sys:String x:Key="en-US">Product Images</sys:String>
                 <sys:String x:Key="en-CA">Product Images</sys:String>
                 <sys:String x:Key="fr-CA">Images du Produit</sys:String>
               </mCore:LocalizedValueDictionary>
             </ResourceDictionary>
           </controls:ToolBarModule.InitResources>
         </controls:ToolBarModule>
   

See Also

Other Resources

Business Administration Ribbon