Share via

  • Article

Exercise 1: Customizing Office with Ribbons and Backstage

Backstage is a perfect place to put UI elements that take up space but are not necessary when actively editing the document. In this case you will be using Backstage and a Ribbon together to create multiple parts of a complete add-in.

Task 1 – Add Export Backstage tab

In this first task, you will create a new Backstage tab named Export to manage the quick export functionality.

  1. Add a new XML Ribbon item to the existing ExportAddIn project
    1. Open VisualStudio 2010 and open the starter lab at %Office2010DeveloperTrainingKitPath%\Labs\OfficeUI\Source\[language]\Starter\ExportAddIn\ExportAddIn.sln
    2. Right click ExportAddIn in the Solution Explorer and choose Add -> New Item.
    3. In the Add New Item dialog, select the Office category.
    4. Choose the Ribbon (XML) item type and enter a name of Ribbon.vb(in case of VB) & Ribbon.cs(in case of C#)

    5. Click Add to create the new ribbon

      Figure 1(a)-In case of C#

      Add Ribbon (XML) Item

      Figure 1(b)-In case of VB

      Add Ribbon (XML) Item

    6. Open the Ribbon.xml file located in the Solution Explorer
  2. Add XML Markup to the Ribbon.xml file to define the Export Backstage tab
    1. Remove the current ribbon node from the Ribbon.xml file

    2. Add the following markup to define the Backstage tab and the first column of information

      XML

      <backstage> <tab id="tabExport" label="Export" insertAfterMso="TabInfo"> <firstColumn> </firstColumn> </tab> </backstage>

    3. Inside the firstColumn element, add the following markup to define the group containing the XPS export controls

      XML

      <group id="grpExportXPS" label="Export as XPS" helperText="Exports the current document as XPS."> <primaryItem> <button id="btnBackStageXPS" label="To XPS" getImage="GetButtonImage" /> </primaryItem> <topItems> <checkBox id="chkEnableXPS" label="Allow XPS Export" /> <editBox id="txtXPSPath" label="Export Path" sizeString="WWWWWWWWWWWWWWWWWWWWWWWWWWWWWW" /> </topItems> </group>
      Note:
      The XPS output controls are made up of a button to perform the export, a check box to enable or disable exporting to XPS and a edit box to define the filename of the exported file.

    4. Immediately following the previous group, add the following markup to define the PDF export controls

      XML

      <group id="grpExportPDF" label="Export as PDF" helperText="Exports the current document as PDF."> <primaryItem> <button id="btnBackStagePDF" label="To PDF" getImage="GetButtonImage" /> </primaryItem> <topItems> <checkBox id="chkEnablePDF" label="Allow PDF Export" /> <editBox id="txtPDFPath" label="Export Path" sizeString="WWWWWWWWWWWWWWWWWWWWWWWWWWWWWW" /> </topItems> </group>

  3. Define the code that will load images for the export buttons
    1. Open Ribbon.vb(in case of VB) & Ribbon.cs(in case of C#) by double clicking it in the Solution Explorer

    2. Add the following GetButtonImage method to the Ribbon class

      C#

      public System.Drawing.Bitmap GetButtonImage( Office.IRibbonControl control) { switch (control.Id) { case "btnBackStageXPS": return Properties.Resources.XPS; case "btnBackStagePDF": return Properties.Resources.PDF; default: return null; } }

      Visual Basic

      Public Function GetButtonImage(ByVal control As Office.IRibbonControl) As System.Drawing.Bitmap Select Case control.Id Case "btnBackStageXPS" Return My.Resources.XPS Case "btnBackStagePDF" Return My.Resources.PDF Case Else Return Nothing End Select End Function
      Note:
      The getImage attribute in the button elements define a public method Office will call any time a button loads. This method uses a switch command to differentiate between the different buttons.

  4. Override the CreateRibbonExtensibilityObject method in the add-in to define the ribbon to load
    1. Open the ThisAddIn class by double clicking it in the Solution Explorer

    2. In the ThisAddIn class, override the CreateRibbonExtensibilityObject method and return a new Ribbon object

      C#

      protected override Office.IRibbonExtensibility CreateRibbonExtensibilityObject() { return new Ribbon(); }

      Visual Basic

      Protected Overrides Function CreateRibbonExtensibilityObject() As Office.IRibbonExtensibility Return New Ribbon() End Function

  5. Run the add-in and verify the Backstage tab looks correct
    1. In the Debug menu, click Start Without Debugging
    2. Once Word 2010 loads, click the Backstage button (labeled as File)

    3. In Backstage switch to the Export tab and verify it looks like the image below

      Figure 2

      Custom Backstage Export tab

Task 2 – Connect Backstage tab to document properties

In this task, you will connect the controls in the Export tab to the CustomDocumentProperties object in the active document. This will allow the state of the controls to be persisted in the document and loaded when the document is loaded later.

  1. Define the code behind that will determine when the button and editBox controls are enabled
    1. Open Ribbon.xml by double clicking it in the SolutionExplorer

    2. Add a getEnabled attribute to the button and editBox controls

      XML

      <button id="btnBackStageXPS"
      getEnabled="GetEnable"FakePre-336bd624635248e3a0251e42c5d9ced8-256b8f04f547484b8800c5d32b5093a7
      Note:
      You should find 2 button controls and 2 editBox controls

    3. Open Ribbon.vb(in case of VB) & Ribbon.cs(in case of C#) by double clicking it in the Solution Explorer

    4. Add the following private field to the class

      C#

      private ExportProperties m_properties = new ExportProperties();

      Visual Basic

      Private m_properties As New ExportProperties()
      Note:
      The ExportProperties class is a wrapper provided for you that wraps the CustomDocumentProperties collection of the current ActiveDocument.

    5. Create a GetEnable method to determine the enable state of other controls.

      C#

      public bool GetEnable(Office.IRibbonControl control) { switch (control.Id) { case "btnBackStageXPS": case "txtXPSPath": return m_properties.XpsEnabled; case "btnBackStagePDF": case "txtPDFPath": return m_properties.PdfEnabled; default: return false; } }

      Visual Basic

      Public Function GetEnable(ByVal control As Office.IRibbonControl) As Boolean Select Case control.Id Case "btnBackStageXPS", "txtXPSPath" Return m_properties.XpsEnabled Case "btnBackStagePDF", "txtPDFPath" Return m_properties.PdfEnabled Case Else Return False End Select End Function

  2. Add code to populate and respond to events from the enabled checkboxes
    1. Open Ribbon.xml by double clicking it in the SolutionExplorer

    2. Add a getPressed and onAction attribute to every checkBox element in the Backstage markup

      XML

      <checkBox id="chkEnablePDF"
      getPressed="IsEnableChecked" onAction="EnableChecked" FakePre-94e68a479a9e490fb248f453bdc02522-c590aef6d1e8403583c9b7341289c5fb
      Note:
      You should find 2 checkBox controls

    3. Open Ribbon.vb(in case of VB) & Ribbon.cs(in case of C#) by double clicking it in the Solution Explorer

    4. Create an IsEnableChecked method that will respond to requests from check box controls to get their current state

      C#

      public bool IsEnableChecked(Office.IRibbonControl control) { if (control.Id == "chkEnableXPS") return m_properties.XpsEnabled; else if (control.Id == "chkEnablePDF") return m_properties.PdfEnabled; else return false; }

      Visual Basic

      Public Function IsEnableChecked(ByVal control As Office.IRibbonControl) As Boolean If control.Id = "chkEnableXPS" Then Return m_properties.XpsEnabled ElseIf control.Id = "chkEnablePDF" Then Return m_properties.PdfEnabled Else Return False End If End Function

    5. Create an EnableChecked method that will respond to the checking of a check box

      C#

      public void EnableChecked(Office.IRibbonControl control, bool value) { if (control.Id == "chkEnableXPS") { m_properties.XpsEnabled = value; ribbon.InvalidateControl("btnBackStageXPS"); ribbon.InvalidateControl("txtXPSPath"); } else if (control.Id == "chkEnablePDF") { m_properties.PdfEnabled = value; ribbon.InvalidateControl("btnBackStagePDF"); ribbon.InvalidateControl("txtPDFPath"); } }

      Visual Basic

      Public Sub EnableChecked(ByVal control As Office.IRibbonControl, ByVal value As Boolean) If control.Id = "chkEnableXPS" Then m_properties.XpsEnabled = value ribbon.InvalidateControl("btnBackStageXPS") ribbon.InvalidateControl("txtXPSPath") ElseIf control.Id = "chkEnablePDF" Then m_properties.PdfEnabled = value ribbon.InvalidateControl("btnBackStagePDF") ribbon.InvalidateControl("txtPDFPath") End If End Sub
      Note:
      The calls to ribbon.InvalidateControl force those controls to reevaluate their state. This will lead to another call to GetEnabled that will now have a different result.

  3. Add code to populate and respond to events from the path edit boxes
    1. Open Ribbon.xml by double clicking it in the SolutionExplorer

    2. Add a getText and onChange attribute to every editBox element

      XML

      <editBox id="txtPDFPath"
      getText="GetExportPath" onChange="SetExportPath" FakePre-b89f22b57b4549e1836a3d941e01716c-18af16b6378c4ef7925bc773960f6462
      Note:
      You should find 2 editBox controls

    3. Open Ribbon.vb(in case of VB) & Ribbon.cs(in case of C#) by double clicking it in the Solution Explorer

    4. Create a GetExportPath method that will retrieve the current export path for the editBox controls

      C#

      public string GetExportPath(Office.IRibbonControl control) { if (control.Id == "txtXPSPath") return m_properties.XpsExportPath; else if (control.Id == "txtPDFPath") return m_properties.PdfExportPath; else return string.Empty; }

      Visual Basic

      Public Function GetExportPath(ByVal control As Office.IRibbonControl) As String If control.Id = "txtXPSPath" Then Return m_properties.XpsExportPath ElseIf control.Id = "txtPDFPath" Then Return m_properties.PdfExportPath Else Return String.Empty End If End Function

    5. Create a SetExportPath method that will respond to the change event of the editBox control

      C#

      public void SetExportPath(Office.IRibbonControl control, string value) { if (control.Id == "txtXPSPath") m_properties.XpsExportPath = value; else if (control.Id == "txtPDFPath") m_properties.PdfExportPath = value; }

      Visual Basic

      Public Sub SetExportPath(ByVal control As Office.IRibbonControl, ByVal value As String) If control.Id = "txtXPSPath" Then m_properties.XpsExportPath = value ElseIf control.Id = "txtPDFPath" Then m_properties.PdfExportPath = value End If End Sub

  4. Run the add-in and verify the enable checkboxes work
    1. In the Debug menu, click Start Without Debugging
    2. Once Word 2010 loads, click the Backstage button (labeled as File)
    3. In Backstage switch to the Export tab

    4. Check and uncheck the enabled checkboxes and verify the related controls are enabled and disabled

      Figure 1

      Enable check box in Backstage tab

Task 3 – Add quick export buttons to the Home ribbon tab

In this task, you will add a Quick Export ribbon button to the Home ribbon tab. It will tie into the same functionality as the buttons on Backstage.

  1. Add the ribbon markup to the Ribbon.xml file
    1. Open Ribbon.xml by double clicking it in the SolutionExplorer

    2. Add the markup that will create a new Quick Export group in the Home tab

      1. Make sure the ribbon xml element is added before the backstage xml element

        XML

        <ribbon> <tabs> <tab idMso="TabHome"> <group id="grpQuickExport" autoScale="true"> </group> </tab> </tabs> </ribbon>
      Note:
      The use of the idMso attribute tells Office to put the following group in the existing tab.

    3. Inside the grpQuickExport group element, add a menu control using an existing image within Office

      XML

      <menu id="btnQuickExport" size="large" itemSize="large" label="Quick Export" imageMso="PageMenu" > </menu>
      Note:
      The use of imageMso tells Office to use an built in Office image

    4. Inside the menu element, add the two button controls to perform the export as XPS or PDF

      XML

      <button id="btnRibbonXPS" label="XPS" getEnabled="GetEnable" getImage="GetButtonImage" /> <button id="btnRibbonPDF" label="PDF" getEnabled="GetEnable" getImage="GetButtonImage" />

  2. Update the code behind to update the Ribbon buttons as well as the Backstage buttons
    1. Open Ribbon.vb(in case of VB) & Ribbon.cs(in case of C#) by double clicking it in the Solution Explorer

    2. Locate the GetButtonImage method and add cases for the ribbon buttons

      C#

      case "btnRibbonXPS": case "btnRibbonPDF":
      case "btnBackStageXPS":
      FakePre-8da2c6d6f0cf49c9a4e00fd41786e1ac-733e025b16e64d7f828d6f6fe13106ddcase "btnRibbonXPS": case "btnRibbonPDF":FakePre-e0843d32d70142be81ffff40e098cb96-ef1a01ade7b44cf0bbefe90342b46ed3FakePre-936671b274624fc19e9a1a99cedf95a0-a7457b4d6cc2430d99cf4b9e338f539b

      Visual Basic

      Case "btnRibbonXPS", "btnBackStageXPS" Case "btnRibbonPDF", "btnBackStagePDF"
      Return My.Resources.XPS
      Case "btnRibbonXPS", "btnBackStageXPS" Case "btnRibbonPDF", "btnBackStagePDF"FakePre-e7f3c2008cf14f83957202b50f6b5f97-6ae09b1a806c42988f68a795cde4c09b

    3. Locate the GetEnable method and add cases for the ribbon buttons

      C#

      case "btnRibbonXPS": case "btnRibbonPDF":
      case "btnBackStageXPS":
      FakePre-1c215621248a48b9abf3ca0510d505be-5ab1ac86d6bb49cb89d4509a0d8b2efdFakePre-e7d35849af6a414b8f04f4000ab6009e-5f21534260a142079b76b9b6f971bb6acase "btnRibbonXPS": case "btnRibbonPDF":FakePre-8a9cdd3453924a79ac40d09f7687c034-1ee788bafa674bd98d5a0c2a002aef4fFakePre-18bbd3b8e6b44fc6824c49f8444d85ef-920c53207bc54448bc4e46629a108acdFakePre-a2e58407820f4d4dabdb86d2bec73fc4-c196d89b4d834d09b0e007e4ff9dee3d

      Visual Basic

      Case "btnRibbonXPS", "btnBackStageXPS", "txtXPSPath" Case "btnRibbonPDF", "btnBackStagePDF", "txtPDFPath"
      Return m_properties.XpsEnabled
      Case "btnRibbonXPS", "btnBackStageXPS", "txtXPSPath" Case "btnRibbonPDF", "btnBackStagePDF", "txtPDFPath"FakePre-9f99dad124b84b38ac969d4ac69f84d6-41885204774145219c40db3ca42975a3

    4. Locate the EnableChecked method and add InvalidateControl calls for the ribbon buttons

      C#

      if (control.Id == "chkEnableXPS")
      FakePre-16163af1231f4a20b4292157cf984114-1e1370787d4d40fead85b891ac07087cFakePre-a58422b53fbe4bf2997f614991c20b0a-854d78af4320433983f4bde7d81fd2f0ribbon.InvalidateControl("btnRibbonXPS"); ribbon.InvalidateControl("btnRibbonPDF"); FakePre-87681b381a6d4176a4473045c7149537-c1ad4e0545304477b40f7068205225f9FakePre-15abed51c69d43eeb6ebe6542dc25971-b26c97beec884bc0af56387286508e39FakePre-057fc432ffce4444acdb91210661fe8d-5160f4f0957346fcad2dfb35ca903d11FakePre-6ff564c12d9a4288a116d0f8daeb741a-884e98d930024b83863ea150918077c5FakePre-a3b9466fbbe44f7cb2f2ec0d38141961-b83ffb3099dd4240b2156d4a4ff9c441FakePre-c0aab149fa404555acd833df10a1bab4-77a7b44ab4e441c39891f08ffdf21699ribbon.InvalidateControl("btnRibbonXPS"); ribbon.InvalidateControl("btnRibbonPDF"); FakePre-5dd615782a8a4bb1bb35e3eeb15064ed-9412f7f0a5c741a3af800000d27848a0FakePre-d630ee657c0546f28de5885e9c235cd2-203c82940e044c42a0174a729d53d800FakePre-f18c5dee833c461b9f68203c5b88ca83-5519d41a62e942b8b3372b131871a721

      Visual Basic

      If control.Id = "chkEnableXPS" Then
      FakePre-346a361dc79749ea997b955c67f94fbd-2fc3f389a5f44d98b2b8813eef99d88aribbon.InvalidateControl("btnRibbonXPS") ribbon.InvalidateControl("btnRibbonPDF")FakePre-5af6302f70774d1d981dd8f524579420-8cdd27efa33e43b196bc9371ebdcb4ffFakePre-de910aef772e42e3a269d4d27c9da68b-5989502765614d1fb18c18710cef8aebFakePre-7285fd6e61174227a6d3c13092a6964f-f3412b3b903e4792a296727621a89810FakePre-225ec478841d45d9b8108b3aa86acb9d-9b68a8bbf5334d00bc4c6f6effaa202eribbon.InvalidateControl("btnRibbonXPS") ribbon.InvalidateControl("btnRibbonPDF")FakePre-96ed9b6c03e04870abe14cbe91414475-572de819292148edb2280a09b2d99c45FakePre-5445b33c984843ad9853539267fab0c6-677874f6985d4e9e89f052a7a2c7b519FakePre-ebf90ad368fa4dbe84e32a06b436b846-e3930f3841174a9abb46f1eccae9cff3

  3. Create the method that will perform the export when the buttons are clicked
    1. Open Ribbon.vb(in case of VB) & Ribbon.cs(in case of C#) by double clicking it in the Solution Explorer

    2. Add the following using statements to the file

      C#

      using Microsoft.Office.Interop.Word;

      Visual Basic

      Imports Microsoft.Office.Interop.Word

    3. Create a new method named ExportDocument that will use the ExportAsFixedFormat document method to export the current document

      C#

      public void ExportDocument(Office.IRibbonControl control) { switch (control.Id) { case "btnRibbonXPS": case "btnBackStageXPS": Globals.ThisAddIn.Application.ActiveDocument. ExportAsFixedFormat( m_properties.XpsExportPath, WdExportFormat.wdExportFormatXPS); break; case "btnRibbonPDF": case "btnBackStagePDF": Globals.ThisAddIn.Application.ActiveDocument. ExportAsFixedFormat( m_properties.PdfExportPath, WdExportFormat.wdExportFormatPDF); break; } }

      Visual Basic

      Public Sub ExportDocument(ByVal control As Office.IRibbonControl) Select Case control.Id Case "btnRibbonXPS", "btnBackStageXPS" Globals.ThisAddIn.Application.ActiveDocument.ExportAsFixedFormat(m_properties.XpsExportPath, WdExportFormat.wdExportFormatXPS) Case "btnRibbonPDF", "btnBackStagePDF" Globals.ThisAddIn.Application.ActiveDocument.ExportAsFixedFormat(m_properties.PdfExportPath, WdExportFormat.wdExportFormatPDF) End Select End Sub

  4. Add the onAction attributes to all of the buttons in the Ribbon and Backstage
    1. Open Ribbon.xml by double clicking it in the Solution Explorer
    2. Add a onAction attribute to every button element

      XML

      <button id="btnRibbonXPS"
      onAction="ExportDocument" FakePre-6cc699e23baa45a9a6f9206ab4a59765-c532f4c72ea848e1960ae9d9f0a694d5
      Note:
      You should find 4 button controls

Exercise 1 Verification

In order to verify that you have correctly performed all steps in the above exercise, proceed as follows:

Test the Add-in

Test your add-in to confirm that the export ribbon and backstage buttons work as expected.

  1. Run the add-in and verify the enable checkboxes work
    1. In the Debug menu, click Start Without Debugging
    2. Once Word 2010 loads, type a phrase in the document and click the Backstage button (labeled as File)
    3. In Backstage switch to the Export tab
    4. Check the Allow XPS Export check box

    5. Enter an Export Path of %Office2010DeveloperTrainingKitPath%\Labs\OfficeUI\Source\[language]\Starter\Export.xps

      Figure 4

      Export as XPS

  2. Click the To XPS button and using Windows Explorer navigate to the folder and open the Export.xps document. Close the .xps file.
  3. Verify the Home ribbon contains a new Quick Format button
    1. Switch to the Home ribbon tab and type an additional phrase into the document

    2. Click the Quick Export button and click the XPS button. Navigate to the .xps document and view it again to see your changes.

      Figure 5

      Quick Export Ribbon Button

  4. When you are done cleanup and remove the add-in
    1. Close Word 2010
    2. In the Solution Explorer, right click Word2010AddIn and click Clean

< previous | next >

Downloads

Download The Offline Training Kit
Download Hands-on Lab Document (DOCX)
Download Hands-on Lab Source Files

Contents