“When are they EVER going to revise the Excel Services JavaScript Object Model documentation for SharePoint Server 2010?"
Well, as a member of "they," I'm glad you asked!
The SharePoint Server 2010 Software Development Kit (SDK) online documentation was refreshed on June 28 and I'm happy to announce that as part of the refresh, the Excel Services JSOM documentation was also updated--in fact, it's been completely revised.
Now, the topics for each object and function in the JSOM have full documentation, including Parameter info, Return Types, and Remarks. We even tossed in Code Samples for good measure!
Note to aspiring developers reading this: you no longer have an excuse not to create amazing solutions using the Excel Services JSOM!
The Excel Services JSOM documentation is here. Make sure to leave feedback! You can do so using the feedback control at the top of each topic:
P.S. Why are you still reading this? Shouldn't you be looking at the revised Excel Services JSOM content?
Often I see customers on forums asking how to display custom user interface in the Office Fluent ribbon under some specific conditions. For example, how to display a custom ribbon only for mail inspectors, or, how would one tell the inspector is in compose mode and not read mode. Browsing just the titles and summaries of existing code samples, such as those under Office UI Customization and Extending the User Interface in Outlook 2010, may not yield those samples that actually answer to such scenarios as well. Because of length restrictions, titles and summaries typically focus only on the core scenarios. So I think it’s worthwhile to point out some useful techniques in one of my recently published Visual How To, that you can easily apply in other common scenarios as well - customizing the ribbon, starting one Office application from another (in C#), and extending the status report automation scenario.
The Visual How To, Automating Chart Importation from Excel to an Email Message in Outlook 2010, describes a simple, core scenario of programmatically copying a chart from an Excel worksheet to an email message that’s being composed in Outlook. The sample code uses the Outlook, Excel, and Word object models. The automation is useful if you have to regularly create status email messages that involve charts in Excel workbooks. You can have an add-in that creates an email message, opens the workbook in Excel, then copies and pastes a chart into the email message.
Aside from showing the core scenario, there are a few secondary aspects of the Visual How To that I would like to highlight.
Customizing the ribbon
The custom user interface is a button “Copy Exel Chart” in its own group “MyGroup” and own tab “MyTab” in the Office Fluent ribbon.
In this example, I want the custom tab to be displayed in the Outlook inspector ribbon, only when the user is composing an email message in an inspector.
To do that, first, implement a custom even handler for the NewInspector event of the Inspectors object, to refresh the inspector ribbon before a new inspector is opened, by calling the IRibbonUI.Invalidate method.
Second, implement the IRibbonExtensibility.GetCustomUI method so that Outlook loads the XML for the custom ribbon only when the context is the mail inspector in compose mode. The context is reflected by the ribbon identifier value Microsoft.Outlook.Mail.Compose. For more information about ribbon identifiers, see Extending the User Interface in Outlook 2010.
Third, in the XML that specifies the custom UI, set the getVisible attribute of the custom tab to a callback method, MyTabInspector_GetVisible.
MyTabInspector_GetVisible.
Lastly, implement the MyTabInspector_GetVisible callback method to make sure that the custom UI is indeed displayed in the following conditions:
MyTabInspector_GetVisible
Starting Excel from Outlook in C#
Before copying a chart from Excel, the sample code first checks if Excel is running. If Excel is running, the sample code uses that instance of Excel. If Excel is not already running, then the sample code starts Excel by creating an instance.
To check if Excel is running on the customer’s computer, the code uses the GetActiveObject method of the Marhsal class. If Excel is not already running, the code uses the C# new keyword to create a new instance of Excel. Note that in Visual Basic, you can call the CreateObject function to start one Office application from another; however, C# does not support a CreateObject function.
Extending the automation in Excel
If the core scenario of automating chart importation interests you, you might also want to read the “Practical Extensions” section of the Visual How To, to see how you can use the Excel object model to update PivotTable data from an OLAP or SQL data source, and then update a PivotChart in Excel before copying the chart to Outlook.
I recently chatted with our MAPI expert Stephen Griffin and would like to share what I learned about the Outlook nickname cache.
The nickname cache is the list of recipient names that is displayed when you insert names in the To, Cc, or Bcc field in an Outlook email or meeting request. The nickname cache expedites completing a recipient’s name, and is also known as the autocomplete stream.
In Outlook 2010, the autocomplete stream is stored as a MAPI property, PidTagRoamingBinary, of a hidden message in the Associated Contents table of the Inbox of the mail account’s delivery store. This hidden message has a message class and subject of IPM.Configuration.Autocomplete.
In an Outlook session, Outlook only loads and saves the autocomplete stream as a property of the hidden message at most once, and interacts with a copy in memory during the Outlook session. Outlook loads the autocomplete stream into memory when the user, for the first time in that Outlook session, attempts to insert recipients in an email or meeting request. Outlook reads all of the contents of the PidTagRoamingBinary property as a binary stream into a structure in memory. After loading the stream into memory, Outlook only accesses the copy in memory. If the copy is modified during that session, upon Outlook shutdown, Outlook saves the copy back to the hidden message in the Associated Contents table of the Inbox of the mail account’s delivery store.
During an Outlook session, the autocomplete stream in memory can be modified in various ways including the following:
Only if the in-memory copy of the autocomplete stream has been modified does Outlook save the copy back to that hidden message on the mail account’s delivery store on Outlook shutdown.
Follow the guidelines below if you want to programmatically access the autocomplete stream:
i. Read the whole stream into memory
ii. Modify the memory structure
iii. Write out the whole stream when the modifications are finished.
To access the PidTagRoamingBinary property, you can use MAPI or the PropertyAccessor of the Outlook object model. The binary format of the autocomplete stream in Outlook 2010 is the same as that of the .nk2 file in Outlook 2007. For details about the binary stream format, see the document Outlook 2003/2007 NK2 File Format and Developer Guidelines. Note that this document was originally written for Outlook 2007 and Outlook 2003, and in Outlook 2010, the nickname cache is no longer stored in a .nk2 file, but in the MAPI property PidTagRoamingBinary, so you should disregard discussions of the .nk2 file and refer to the part of the document starting from the section “File Visualization”.