Business Administration Ribbon

The Commerce Server Business Administration Ribbon is a Silverlight application that utilizes the Silverlight Tab Control. The Commerce Server Business Administration Ribbon provides marketers and merchandisers the ability to perform business management functions on the site directly, so that they can see the changes instantaneously, in a what-you-see-is-what-you-get (WYSIWYG) experience. These changes are reflected back to the master catalog within Commerce Server 2009 R2.

Components

The Commerce Server Business Administration Ribbon consists of the following components:

1. Toolbar Shell

2. Toolbar XAML

3. Toolbar Plug-ins

4. Toolbar Plug-ins Configuration File

5. Toolbar PluginCSManagementResources File

Toolbar Shell

The toolbar shell is a Silverlight Tab Control application and acts as the controller. On initialization it downloads the toolbar configuration file, the toolbar plug-ins and their corresponding configuration file from the web server. It then launches the various toolbar plug-ins based on the configuration, permissions and context.

The following diagram demonstrates how the toolbar will render:

The following diagram identifies the different structures that make up the toolbar:

TabControl

The TabControl is the main container housing a list of toolbar tab items (TabItem). Each TabItem contains a list of toolbar modules (ToolbarModule). This component leverages the out-of-the-box TabControl. The following table lists the properties for the TabControl.

TabItem

The TabItem control represents a tab that groups the various toolbar plug-ins. It controls how the toolbar plug-ins are organized on the toolbar. The TabItem is the out-of-the-box TabItem control.

ToolbarModule

The ToolbarModule class is responsible for loading the toolbar plug-in. It retrieves the toolbar plug-in and adds the toolbar plug-in to its content.

The following table lists the properties for the ToolbarModule class.

The Toolbar calls the GetContext JavaScript function from CommerceManagement.js that passes the context keyword and receives a Boolean to determine the toolbar plug-in visibility. The following is a sample of the GetContext function:

function GetContext(context) {
    // The Commerce toolbar uses this function to find out if the page is in a certain "context"
    // When the context matches the context required by a module, that module is enabled.

    switch (context) {
        case "Product":
            if (document.getElementById("ProductContext") != null) {
                return true;
            }
            break;
        case "Category":
            if (document.getElementById("CategoryContext") != null) {
                return true;
            }
            break;
        case "CatalogRelationship":
            if ((document.getElementById("CategoryContext") != null) || (document.getElementById("ProductContext") != null)) {
                return true;
            }
            break;
    }

    return false;
}

For example, if you want a toolbar plug-in to be shown only on the Product Details page, you can define a context keyword labeled "Product", and have the IsInContext function return True if the Product Details Web Part is on the page. You can do this by searching for an element based on the ID generated by the Product Details Web Part.

The activation of the toolbar plug-in is also controlled by the list of permissions required for the user. This list of permissions is stored in the toolbar plug-in configuration file. The Commerce Server Business Administration Ribbon retrieves that list and calls the Commerce Foundation to check if the user is authorized to activate the toolbar plug-in. In the event that a malicious user tampers with this file and removes the list of permissions required of the toolbar plug-in, the malicious user will still be prevented from requesting data when making a call to the Commerce Foundation. The toolbar plug-in does not depend on this file when making calls to the Commerce Foundation.

The purpose of the configuration file is to increase performance by preventing the toolbar from loading the plug-in if the user does not have the required permissions.

Toolbar XAML

The toolbar XAML dictates the structure and appearance of the toolbar, including how the plug-ins are grouped into different tab items. The toolbar XAML lets you define the appearance of the toolbar components using Microsoft Silverlight styles:

• background color of the toolbar shell

• foreground color of the toolbar shell

• the Tab text color

• the Button text color

The Commerce Server Business Administration Ribbon retrieves the toolbar XAML during runtime and loads the XAML dynamically. This provides you with the ability to remove existing toolbar plug-ins and/or add your own toolbar plug-ins without having to recompile the toolbar shell.

The following code shows an XAML markup sample:

<basics:TabControl xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
                   xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
                   xmlns:basics="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls"
                   xmlns:basicsExtended="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls.Toolkit"
 xmlns:sys="clr-namespace:System;assembly=mscorlib"
                   xmlns:controls="clr-namespace:Microsoft.Commerce.BusinessManagement.CommerceManagementToolBarApplication.Controls;assembly=Microsoft.Commerce.BusinessManagement.CommerceManagementToolBarApplication"
 xmlns:mCore="clr-namespace:Microsoft.Commerce.BusinessManagement;assembly=Microsoft.Commerce.BusinessManagement">
  <basics:TabControl.Background>
    <LinearGradientBrush EndPoint="0.5,1" StartPoint="0.5,0">
      <GradientStop Color="#FFFFFFFF"/>
      <GradientStop Color="#FF818181" Offset="1"/>
    </LinearGradientBrush>
  </basics:TabControl.Background>

  <basics:TabItem Header="{Binding TabItemHeader, 
                Converter={StaticResource ExternalResourceConverter}, 
                ConverterParameter='Marketing'}"
                 ToolTipService.ToolTip="{Binding TabItemHeader, 
                Converter={StaticResource ExternalResourceConverter}, 
                ConverterParameter='MarketingToolTip'}"
                  x:Name="MgmtToolbarTab1" Foreground="Black">
    <Grid ShowGridLines="False">
      <Grid.ColumnDefinitions>
        <ColumnDefinition />
        <ColumnDefinition />
      </Grid.ColumnDefinitions>
      <Grid.RowDefinitions>
        <RowDefinition Height="Auto" />
      </Grid.RowDefinitions>
      <basicsExtended:WrapPanel Grid.Row="0" Grid.Column="0" HorizontalAlignment="Left">

        <controls:ToolBarModule ConfigFile="MicrosoftCommerceCatalogItemRelationship.xml" >
          <controls:ToolBarModule.InitResources>
            <ResourceDictionary>
              <sys:String x:Key="RelationshipToEdit">CrossSells</sys:String>
              <sys:String x:Key="OnClick">FloatSilverlight("CrossSellEditSilverlight", "/ClientBin/MicrosoftCommerceCatalogItemRelationship.xap", "CatalogItemRelationshipToEdit=CrossSells,ChannelName=,ResourceFileUris=CsManagementResources.xml MicrosoftCommerceCatalogItemRelationshipResources.xml", 10, 10, 800, 618, 800, 618, true, "App.RequestClose()")</sys:String>
              <mCore:LocalizedValueDictionary x:Key="Label">
                <sys:String x:Key="en-US">Cross-sell</sys:String>
                <sys:String x:Key="en-CA">Cross-sell</sys:String>
                <sys:String x:Key="fr-CA">Cross-sell</sys:String>
                <sys:String x:Key="ja-JP">クロス販売</sys:String>
              </mCore:LocalizedValueDictionary>
              <sys:String x:Key="LabelColor">Black</sys:String>
            </ResourceDictionary>
          </controls:ToolBarModule.InitResources>
        </controls:ToolBarModule>

        <controls:ToolBarModule ConfigFile="MicrosoftCommerceCatalogItemRelationship.xml">
          <controls:ToolBarModule.InitResources>
            <ResourceDictionary>
              <sys:String x:Key="RelationshipToEdit">UpSells</sys:String>
              <sys:String x:Key="OnClick">FloatSilverlight("UpSellEditSilverlight", "/ClientBin/MicrosoftCommerceCatalogItemRelationship.xap", "CatalogItemRelationshipToEdit=UpSells,ChannelName=,ResourceFileUris=CsManagementResources.xml MicrosoftCommerceCatalogItemRelationshipResources.xml", 10, 10, 800, 618, 800, 618, true, "App.RequestClose()")</sys:String>
              <mCore:LocalizedValueDictionary x:Key="Label">
                <sys:String x:Key="en-US">Up-sell</sys:String>
                <sys:String x:Key="en-CA">Up-sell</sys:String>
                <sys:String x:Key="fr-CA">Up-sell</sys:String>
                <sys:String x:Key="ja-JP">アップ販売</sys:String>
              </mCore:LocalizedValueDictionary>
              <sys:String x:Key="LabelColor">Black</sys:String>
            </ResourceDictionary>
          </controls:ToolBarModule.InitResources>
        </controls:ToolBarModule>

        <controls:ToolBarModule ConfigFile="MicrosoftCommerceProductImageEdit.xml" x:Name="moduleProductImageEdit">
          <controls:ToolBarModule.InitResources>
            <ResourceDictionary>
              <sys:String x:Key="OnClick">FloatSilverlight("ProductImageEditSilverlight", "/ClientBin/MicrosoftCommerceCatalogImagesManager.xap", "ChannelName=,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>
                <sys:String x:Key="ja-JP">商品イメージ</sys:String>
              </mCore:LocalizedValueDictionary>
              <sys:String x:Key="LabelColor">Black</sys:String>
            </ResourceDictionary>
          </controls:ToolBarModule.InitResources>
        </controls:ToolBarModule>

      </basicsExtended:WrapPanel>
      <basicsExtended:WrapPanel Grid.Row="0" Grid.Column="1" HorizontalAlignment="Right">

        <controls:ToolBarModule ConfigFile="MicrosoftCommerceCacheRefresh.xml" AutomationProperties.AutomationId="cacheRefreshMarketingTab">
          <controls:ToolBarModule.InitResources>
            <ResourceDictionary>
              <mCore:LocalizedValueDictionary x:Key="Label">
                <sys:String x:Key="en-US">Refresh Cache</sys:String>
                <sys:String x:Key="en-CA">Refresh Cache</sys:String>
                <sys:String x:Key="fr-CA">Actualizer le Cache</sys:String>
                <sys:String x:Key="ja-JP">キャッシュのリフレッシュ</sys:String>
              </mCore:LocalizedValueDictionary>
              <sys:String x:Key="LabelColor">Black</sys:String>
              <sys:String x:Key="CacheName">CatalogCache</sys:String>              
            </ResourceDictionary>
          </controls:ToolBarModule.InitResources>
        </controls:ToolBarModule>

      </basicsExtended:WrapPanel>
    </Grid>
  </basics:TabItem>

  <basics:TabItem Header="{Binding TabItemHeader, 
                Converter={StaticResource ExternalResourceConverter}, 
                ConverterParameter='Catalog'}"
                  ToolTipService.ToolTip="{Binding TabItemHeader, 
                Converter={StaticResource ExternalResourceConverter}, 
                ConverterParameter='CatalogToolTip'}"
                  x:Name="MgmtToolbarTab2" Foreground="Black">
    <Grid ShowGridLines="False">
      <Grid.ColumnDefinitions>
        <ColumnDefinition />
        <ColumnDefinition />
      </Grid.ColumnDefinitions>
      <Grid.RowDefinitions>
        <RowDefinition Height="Auto" />
      </Grid.RowDefinitions>
      <basicsExtended:WrapPanel Grid.Row="0" Grid.Column="0" HorizontalAlignment="Left">
        <controls:ToolBarModule ConfigFile="MicrosoftCommerceCatalogItemEditor.xml">
          <controls:ToolBarModule.InitResources>
            <ResourceDictionary>
              <sys:String x:Key="OnClick">FloatSilverlight("CatalogItemEditSilverlight", "/ClientBin/MicrosoftCommerceCatalogItemEditor.xap", "ChannelName=,ResourceFileUris=CsManagementResources.xml MicrosoftCommerceCatalogItemEditorResources.xml", 10, 10, 800, 640, 800, 640, true, "App.RequestClose()")</sys:String>
              <mCore:LocalizedValueDictionary x:Key="Label">
                <sys:String x:Key="en-US">Edit</sys:String>
                <sys:String x:Key="en-CA">Edit</sys:String>
                <sys:String x:Key="fr-CA">Changer</sys:String>
                <sys:String x:Key="ja-JP">編集</sys:String>
              </mCore:LocalizedValueDictionary>
              <sys:String x:Key="LabelColor">Black</sys:String>
            </ResourceDictionary>
          </controls:ToolBarModule.InitResources>
        </controls:ToolBarModule>
      </basicsExtended:WrapPanel>
      <basicsExtended:WrapPanel Grid.Row="0" Grid.Column="1" HorizontalAlignment="Right">
        <controls:ToolBarModule ConfigFile="MicrosoftCommerceCacheRefresh.xml" AutomationProperties.AutomationId="cacheRefreshCatalogTab" >
          <controls:ToolBarModule.InitResources>
            <ResourceDictionary>
              <mCore:LocalizedValueDictionary x:Key="Label">
                <sys:String x:Key="en-US">Refresh Cache</sys:String>
                <sys:String x:Key="en-CA">Refresh Cache</sys:String>
                <sys:String x:Key="fr-CA">Actualizer le Cache</sys:String>
                <sys:String x:Key="ja-JP">キャッシュのリフレッシュ</sys:String>
              </mCore:LocalizedValueDictionary>
              <sys:String x:Key="LabelColor">Black</sys:String>
              <sys:String x:Key="CacheName">CatalogCache</sys:String>             
            </ResourceDictionary>
          </controls:ToolBarModule.InitResources>
        </controls:ToolBarModule>
      </basicsExtended:WrapPanel>
    </Grid>

  </basics:TabItem>

  <basics:TabItem Header="{Binding TabItemHeader, 
                Converter={StaticResource ExternalResourceConverter}, 
                ConverterParameter='Management'}"
                  ToolTipService.ToolTip="{Binding TabItemHeader, 
                Converter={StaticResource ExternalResourceConverter}, 
                ConverterParameter='ManagementToolTip'}"
                  x:Name="MgmtToolbarTab3" Foreground="Black">
    <basicsExtended:WrapPanel>
      <controls:ToolBarModule ConfigFile="MicrosoftCommerceChannelConfiguration.xml">
        <controls:ToolBarModule.InitResources>
          <ResourceDictionary>
            <sys:String x:Key="OnClick">window.location= MSCS_GetParameter('HomeWeb') + "/Lists/Channel%20Configuration/Configuration%20View.aspx"</sys:String>
            <mCore:LocalizedValueDictionary x:Key="Label">
              <sys:String x:Key="en-US">Channel Configuration</sys:String>
              <sys:String x:Key="en-CA">Channel Configuration</sys:String>
              <sys:String x:Key="fr-CA">Canal de Configuration</sys:String>
              <sys:String x:Key="ja-JP">チャネル構成</sys:String>
            </mCore:LocalizedValueDictionary>
            <mCore:LocalizedValueDictionary x:Key="ToolTip">
              <sys:String x:Key="en-US">Configure the channel settings for the site</sys:String>
              <sys:String x:Key="en-CA">Configure the channel settings for the site</sys:String>
              <sys:String x:Key="fr-CA">Canal de Configuration settings for the site</sys:String>
              <sys:String x:Key="ja-JP">サイトためのチャネルの設定を構成</sys:String>
            </mCore:LocalizedValueDictionary>
            <sys:String x:Key="LabelColor">Black</sys:String>
          </ResourceDictionary>
        </controls:ToolBarModule.InitResources>
      </controls:ToolBarModule>
    </basicsExtended:WrapPanel>

  </basics:TabItem>

</basics:TabControl>

Toolbar Plug-ins

Toolbar plug-ins are the various business management applications that are launched by the toolbar, such as the Cross-Sell/Up-Sell Relationship Manager tool. The toolbar plug-ins are contained in their own assembly and packaged in their own XAP file, which reside at a known location on the Web server. Each toolbar plug-in is configured on the Commerce Server Business Administration Ribbon based on its configuration file which is configured by setting the property ConfigFile in the ToolbarModule element.

Toolbar Plug-in Configuration File

The toolbar plug-in configuration file contains the settings and configuration information for each toolbar plug-in. The file is an XML Document that defines configuration information regarding the Silverlight plug-in. The configuration file contains the following:

• A list of permissions required to render the toolbar plug-in

• The context

• The control name

• The assembly name

• The name of the XAP file

The configuration file must reside at the same location as the XAP file.

The following code sample shows markup of what the configuration file may look like:

<Plugin>
  <Context>Product</Context>  
  <ControlName>Microsoft.Commerce.BusinessManagement.EditCrossSell</ControlName>
  <Assembly>Microsoft.Commerce.BusinessManagement.EditCrossSell</Assembly>
  <Xap>CrossSell.xap</Xap>  
</Plugin>

Toolbar CsManagementResources.xml File

The CsManagementResources.xml file contains Commerce Service settings elements such Endpoint Address, Channel, and the type of security. The plug-ins use this file to make service calls to a Commerce Service Proxy. Below is a sample of the file contents:

  <services:CommerceServiceSettings
        x:Key="CommerceServiceSettings"
        EndpointAddress="CommerceServiceProxy.svc"
        MaxReceivedMessageSize="2000000"
        BasicHttpSecurityMode="None"
  UriConverter="{StaticResource StringToUriConverter}" />

Customization

You can customize the Commerce Server Business Administration Ribbon by modifying the toolbar XAML file, and adding plug-ins. The XAML file resides outside of the main toolbar application; therefore it does not require a rebuild of the Commerce Server Business Administration Ribbon. You can extend the Commerce Server Business Administration Ribbon through the configuration file.