Step 8 (Optional): Define the Ribbon and Actions (Ribbon.xml)

Now that you have added a task pane layout to an intermediate declarative Outlook solution, you can also add a custom ribbon file definition. The ribbon file specifies actions that are called from the ribbon.

Applies to: SharePoint Server 2010

For example, many solutions have a button on the ribbon that opens the task pane. The behavior for opening the task pane would be an action. The ribbon file uses the standard ribbon schema that all Microsoft Office applications use.

Actions in Business Connectivity Services can be URL-based or code-based. URL-based actions navigate to a specified URL when the action is executed (for example, when a ribbon button is clicked). URL-based actions can be defined declaratively in the Ribbon.xml file. Code actions execute code when a ribbon button is clicked and must be created by a developer before they can be used.

The Code Sample: AdventureWorks2008 Declarative Outlook Solution has a custom ribbon menu, Contoso Sales Manager. When you click Contoso Sales Manager, two ribbon buttons are displayed, as follows:

• Related Orders When clicked, displays the task pane with order history.

• Phone Lookup When clicked, opens a browser window to the MSN phone lookup page and searches for the customer's phone number.

To create a ribbon file

1. You can use the BCS Artifact Generator Tool to create the form region manifest file based on the BDC model.

   Alternately, you can author the form region manifest manually, as follows.

   1. Locate the Template: Ribbon.xml provided in the SDK, and copy it, and then save it to the Solution Artifacts folder as OutlookContactRibbon.xml.

   2. Open the OutlookContactRibbon.xml file for editing in an XML editor. If you are opening the XML file in Visual Studio, attach the Office ribbon schema (Office 2010 Reference: Office Fluent User Interface XML Schema). This gives you IntelliSense functionality and helps you create valid entries.

   3. Replace the values marked with EnterX in the XML with valid values. The following XML example shows how it might look after editing.

      <customUI xmlns="https://schemas.microsoft.com/office/2006/01/customui" 
                onLoad="OnLoad" loadImage="GetImage">
        <ribbon>
          <tabs>
            <tab id="tabID" label="Contoso Sales Manager" 
                 getVisible="GetVisible" tag="Solution">
              <group id="CustomerSalesGroupID" label="Customer Sales" 
                     getVisible="GetVisible" 
                     tag="Context[OutlookContactCustomer.CustomerSalesGroupID]">
                <button id="relatedOrderHeaderButton"
                            size="large"
                            label="Customer Orders"
                            onAction="OnAction"
                            image="Arrow.jpg"
                          getEnabled ="GetEnabled"
                          tag="Action[OutlookContactCustomer.RelatedOrderHeaderAction]"
                        />
              </group>
              <group id="CustomerActionsGroupID" label="Customer Actions" 
                     getVisible="GetVisible" 
                     tag="Context[OutlookContactCustomer.CustomerActionsGroupID]">
                <button id="SearchCustomerByPhoneButton"
                           size="large"
                           label="Phone Lookup"
                           onAction="OnAction"
                           image="MagGlass.png"
                         getEnabled ="GetEnabled"
                         tag="Action[OutlookContactCustomer.SearchCustomerByPhoneAction]"
                        />
              </group>
            </tab>
          </tabs>
        </ribbon>
      </customUI>
      

   4. Save the file and then close it.

2. Open the OIR.config file for editing. Update OIR.config to specify which ribbon file to load, by adding the RibbonFileName attribute, as shown in the following example.

   <ContextDefinitionGroup 
     xsl:type="Declarative:DeclarativeContextDefinitionGroup" 
     ItemType="OutlookContact" RibbonFileName="OutlookContactRibbon.xml">
   

3. Add a ContextDefinitionGroup for the Order association to specify how to get Order external items, as shown in the following example. This is an optional step and is required only if you want to surface actions in the Rich List Part.

   <ContextDefinitionGroup ItemType="EntityView">
     <!-- The content type has to be in the format: -->
     <!-- length_of_entity_namespace="" length_of_entity_name="" 
     length_of_view_name="" entity_namespace="" entity_name="" 
     view_name="" position_of_entity_namespace="" -->
     <ContextDefinition 
       ContentType="12 12 24 AWWSExample OrderHeader GetSalesOrderHeaderById 9" 
       xsl:type="Declarative:DeclarativeContextDefinition">
       <Entities>
         <Entity Name="OrderHeader" EntityTypeName="OrderHeader" 
                 EntityTypeNamespace="AWWSExample">
           <View Name="PrimaryEntityNameInContext" 
                 ViewName="GetSalesOrderHeaderById" 
                 Description="GetSalesOrderHeaderById" IsPrimary="true" />
         </Entity>
       </Entities>
       <Declarative:Layouts>
         <Declarative:Layout Name="Edit" LayoutFileName="EditOrderHeader">
           <Declarative:Properties>
             <Declarative:Property Name="AssociatedActionType" Value="Edit" />
           </Declarative:Properties>
         </Declarative:Layout>
       </Declarative:Layouts>
       <Declarative:Actions>
         <Declarative:CodeMethodAction MethodType="EditEntity" Name="Edit" 
                                       Caption="Edit Order" 
                                       DisplayLocations="ItemContextMenu" 
                                       DisplayOrder="2" Scope="ItemContext" />
       </Declarative:Actions>
     </ContextDefinition>
   </ContextDefinitionGroup>
   

4. Update the OIR.config file to give the BCS Client Runtime the information about the ribbon buttons you want and the associated actions for the Customer ContextDefinition. Add the following code below the <Declarative:Layouts> tag in the Customer ContextDefinition.

   <Declarative:Actions>
     <Declarative:CodeMethodAction Name ="RelatedOrderHeaderAction" 
                                   MethodType ="ShowTaskpaneLayout">
       <Declarative:Parameters>
         <Declarative:ConstantParameter Name="Para1" 
                                        Value="RelatedOrderHeader" 
                                        ValueType="System.String"/>
       </Declarative:Parameters>
     </Declarative:CodeMethodAction>
     <Declarative:UrlAction 
       Name="SearchCustomerByPhoneAction" 
       Url="http://msn.whitepages.com/search/ReversePhone?full_phone={0}">
       <Declarative:Parameters>
         <Declarative:ExpressionParameter 
           Name="Para1" 
           EntityViewInstanceReference="PrimaryEntityNameInContext" 
           Expression="Phone"/>
       </Declarative:Parameters>
     </Declarative:UrlAction>
   </Declarative:Actions>
   <Declarative:ContextEventHandlers>
     <Declarative:ContextActivated ActionName="RelatedOrderHeaderAction" />
   </Declarative:ContextEventHandlers>
   

5. Save the file and then close it.

6. Package the solution, deploy it, and then test it to ensure that it works as expected.

You have now successfully created an intermediate declarative Outlook solution.