Extending the Project backstage… Extending the GUI

Hello World In this second post covering my proof of concept to expose workflow status information in the Project backstage I will cover off some of the basics on how to extend the backstage.

Like all of the Office 2010 clients, Project’s backstage can be customised by defining the various interface elements and their associated behaviours using an XML schema that has been published by Microsoft and is available for download here.

Perhaps the easiest way to understand the XML is to view an example. The XML below defines a new tab in the backstage called “Hello World” which consists of a single group called “Hello World Example” and has a single button that when clicked will call some arbitrary code called, yes you’ve guessed it, “HelloWorld”

    <customUI xmlns="http://schemas.microsoft.com/office/2009/07/customui">
     <backstage>
      <tab id="TabHello" label=”Hello World”>
        <firstColumn>
          <group id="grpOne" label="Hello World Example" helperText="Click here for some Hello World Action">
            <primaryItem>
              <button id="firstButton" label="Hello World" onAction="HelloWorld" />
            </primaryItem>
           </group>
        </firstColumn>
      </tab>
     </backstage>
    </customUI>

image

The backstage also allows out of the box tabs to be extended such as the ‘Info’ or ‘Save & Send’ tabs. It is also possible to insert and position customisations within the out of the box tabs. To do so, there are a couple of special XML elements you need to be across. In the example above, the line:

<tab id=”TabHello” label=”Hello World”>

could be replaced with

<tab idMso=”TabInfo”>

to add the Hello World group and button the out of the box Info tab.

image

The idMso element tells the backstage that a Microsoft Office Control Id should be used, in this case the Info tab. Similarly through the addition of the insertAfterMso element in the group section, it is possible to define where our new group is inserted in the tab in relation to the other groups on the tab. Like idMso, insertAfterMso uses a ControlId to ‘navigate’ it’s way around. Microsoft have published a list of these Control Id’s for all of the Office 2010 clients that you can download here.

Thinking Binary…

In most of the Office 2010 clients, the custom XML used to define the backstage enhancements can simply be added into the document assembly and would be automatically picked up when the document was loaded. Unfortunately, as Project is still using a binary file format, this is not possible and the XML backstage definition needs to be added via code using a method called setCustomUI.

Using setCustomUI is relatively simple to implement, once the XML has been defined, all that needs to be done is to transfer the XML into a variable and to call setCustomUI to implement it.  There are a couple of things you need to be careful of when encoding the XML:

  • Make sure you change all single quotes to double quotes
  • The backstage will fail to render if any of the elements have the incorrect name, check them all.
  • Double check that there are no empty strings, e.g. label=”””” as this will cause the backstage to fail to render.
    Finally, all that is required to do is wrap all of the code up in a couple of methods so that it will added automatically when the project is opened and to wire up the button.
Private Sub AddBackstageTab()

    Dim backstageXML As String

    backstageXML = "<customUI xmlns=""http://schemas.microsoft.com/office/2009/07/customui"">"
    backstageXML = backstageXML + " <backstage>"
    backstageXML = backstageXML + "  <tab idMso=""TabInfo"">"
    backstageXML = backstageXML + "    <firstColumn>"
    backstageXML = backstageXML + "      <group id=""grpOne"" label=""Hello World Example"" helperText=""Click here for some Hello World Action"">"
    backstageXML = backstageXML + "        <primaryItem>"
    backstageXML = backstageXML + "          <button id=""firstButton"" label=""Hello World"" onAction=""HelloWorld""/>"
    backstageXML = backstageXML + "        </primaryItem>"
    backstageXML = backstageXML + "       </group>"
    backstageXML = backstageXML + "    </firstColumn>"
    backstageXML = backstageXML + "  </tab>"
    backstageXML = backstageXML + " </backstage>"
    backstageXML = backstageXML + "</customUI>"

    ActiveProject.SetCustomUI (backstageXML)

End Sub

Private Sub Project_Open(ByVal pj As Project)
        AddBackstageTab
End Sub

Private Sub HelloWorld()
    ' Do something
End Sub

In the next post, I will cover off how to incorporate the workflow data into the backstage.

Advertisements

2 thoughts on “Extending the Project backstage… Extending the GUI

  1. Pingback: Extending the backstage… Integrating data and the UI « EPMSource

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s