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:
Toolbar Shell
Toolbar XAML
Toolbar Plug-ins
Toolbar Plug-ins Configuration File
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.
Property |
Type |
Description |
---|---|---|
IsExpanded |
Bool |
A Boolean stating whether or not the Commerce Server Business Administration Ribbon is in a minimized state. |
PluginLocation |
String |
The location on the web server housing the toolbar plug-ins. Represented by a URL. |
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.
Property |
Type |
Description |
---|---|---|
Context |
String |
Context name required to enable the toolbar plug-in. |
IsAllowed |
Bool |
Returns True if the toolbar plug-in has the correct context and all permissions of the user are met |
ControlName |
String |
Name of the control used to instantiate the plug-in control. |
AssemblyName |
String |
The name of the assembly containing the plug-in control. |
Xap |
String |
Name of the XAP file. |
ConfigFile |
String |
The name of the configuration file for the plug-in. |
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.