Customizing SharePoint 2010 Ribbon UI: Lessons Learned

One of the SharePoint 2010 solutions we at MetroStar have been developing has involved some customizations of the Ribbon UI.  After several days learning (and fighting) the Ribbon I’ve learned a few things which may be of some use to other SharePoint developers out there:

• Adding elements to the Ribbon involves a pretty straight forward process  of writing some XML and putting it in a CustomAction
• Wiring up the commands which Ribbon controls use (such as buttons) can be done in one of two ways
  • The command handlers can be defined in the CustomAction‘s XML using a CommandUIHandler
    • These are the simplest to setup but offer the least flexibility
    • Certain commands do not work properly with commands defined this way (such as a ToggleButton‘s QueryCommand)
  • The more flexible/complicated approach is to use PageComponents which let you define JavaScript ‘classes’ to handle the various actions that a Ribbon control may need
• SharePoint’s built-in commands can be overridden by creating a handler for a command with the same name as the built-in command
• Finding out what a built-in command is doing behind the scenes can be very difficult to do
  • The JavaScript can be run through a debugger to see what is going on but the code is neither commented or documented
• When loading PageComponents the order of operations is very important
  • Make use of SharePoint’s scriptLink control to load JS after the UI has loaded
  • Use ExecuteOrDelayUntilScriptLoaded and NotifyScriptLoadedAndExecuteWaitingJobs to make sure dependencies are loaded before trying to use them
• The documentation (as of 2/11/2011) on MSDN is severely lacking so be prepared to do a lot Googling and Guess/Checking.

For those delving into the Ribbon here are some links which helped me out greatly:

http://msdn.microsoft.com/en-us/library/ff630938.aspx

http://www.wictorwilen.se/Post/Creating-a-SharePoint-2010-Ribbon-extension-part-1.aspx

http://www.sharepointnutsandbolts.com/2010/02/ribbon-customizations-dropdown-controls.html

http://blog.dennus.net/2010/07/20/ribbon-buttons-with-postback-in-sp2010/

To see the fruits of these labor’s be sure to check out our StarLabs site to see our latest a greatest (Free!) SharePoint solutions.