Extending the Project backstage… Extending the GUI
By blurg64
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”
[sourcecode language=”xml” wraplines=”true”]
<tab id="TabHello” label=”Hello World”>
[/sourcecode]
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:
[sourcecode language=”xml” wraplines=”false”]
<tab id=”TabHello” label=”Hello World”>
[/sourcecode]
could be replaced with
[sourcecode language=”xml” wraplines=”false”]
[/sourcecode]
to add the Hello World group and button the out of the box Info tab.
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.
[sourcecode language=”vb” wraplines=”no”]
Private Sub AddBackstageTab()
Dim backstageXML As String
backstageXML = “<customUI xmlns="“http://schemas.microsoft.com/office/2009/07/customui"">”
backstageXML = backstageXML + "
backstageXML = backstageXML + " <tab idMso="“TabInfo"“>”
backstageXML = backstageXML + "
backstageXML = backstageXML + " <group id="“grpOne”” label="“Hello World Example”” helperText="“Click here for some Hello World Action"“>”
backstageXML = backstageXML + "
backstageXML = backstageXML + " <button id="“firstButton”” label="“Hello World”” onAction="“HelloWorld”"/>”
backstageXML = backstageXML + " ”
backstageXML = backstageXML + " ”
backstageXML = backstageXML + " ”
backstageXML = backstageXML + "
backstageXML = backstageXML + " ”
backstageXML = backstageXML + “”
ActiveProject.SetCustomUI (backstageXML)
End Sub
Private Sub Project_Open(ByVal pj As Project)
AddBackstageTab
End Sub
Private Sub HelloWorld()
‘ Do something
End Sub
[/sourcecode]
In the next post, I will cover off how to incorporate the workflow data into the backstage.