My last project had me do some SharePoint 2010 Ribbon customizations. I though I would blog about some of the things I learned! There are many ways to create a Ribbon component. You could use a custom action to a tab to an existing Ribbon or in the case that I will be discussing/demonstrating is creating a complete new tab for a SharePoint Application page. The steps developer should take :
- Work through the Hand-On Lab provided by Microsoft on Customizing the Ribbon. This is part of The SharePoint Developer Training Kit which can be downloaded here: Developer Training Kit
- Read Chris O'Brien blog series on customizing the Ribbon! Really Good!
- I found this gem by accident! Download this Visual Studio Add In for Customizing the Ribbon: SharePoint Ribbon Extensibility
A SharePoint Ribbon is non trivial there is a lot of work involved in just getting the ribbon and tabs to appear:
- The XML to get the tab/controls on the Ribbon
- Getting the Page Component set up
- Linking to custom JavaScript
- Communicating to the server/client from the Ribbon
There are plenty of blogs about the ribbon and they are very good. This post is not a rehash on how to create a Ribbon but on Client/Server communication via the Ribbon.
Client Server communications is the big one as the SharePoint 2010 Ribbon is mostly controlled via JavaScript. How to get the JavaScript methods to invoke server side code. I saw many blog posts which describe how to dynamically populate a drop down or fly out through a delegate, etc. However, they were related to this single instance and didn’t seem to be extendable to a general way to handle all the buttons in a Ribbon. The first thing I looked at was using was the IPostBackEventHandler Interface and I was successful in getting the ribbon button commands to call the server! However, a big gotcha was that they required a post back! In the modern web 2.0 era this is a big no no! I wound up using the ICallbackEventHandler Interface and this was the ticket! The application could respond to button clicks via JavaScript and call the server without Post Back!!!! I might add that the gist of the code required came from this blog post: Patrick Boom. Microsoft has a great article on how too use this Interface here: Call Back Event handler The interesting part of this is how the JavaScript call back is invoked:
ClientScriptManager cm = Page.ClientScript; String cbReference = cm.GetCallbackEventReference(this, "arg", "ReceiveServerData", ""); String callbackScript = "function CallServer(arg, context) {" + cbReference + "; }"; cm.RegisterClientScriptBlock(this.GetType(), "CallServer", callbackScript, true);
notice the CallServer method is built dynamically and has arg as a parameter this is what we need to make a general purpose method to get our client click buttons from JavaScript. The ICallbackEventHandler Interface requires two methods on the server:
public void RaiseCallbackEvent(String eventArgument) { } and public string GetCallbackResult() { return aStringValue; }
The one I am interested for this discussion is RaiseCallbackEvent it has eventArgument as a parameter. We can link these two items together via arg and eventArgument by using a JavaScript call on our Ribbon buttons. A Ribbon command might look like this for Save. Where the JavaScript Method is setSave().
commands.Add(new SPRibbonCommand("Ribbon.MyTab.MyFormGrp.Save.Click", "setSave();", "true"));
The setSave() JavaScript method:
function setSave() { //call server SP.UI.Notify.addNotification("You pressed Save, ", false); CallServer("Save", ""); }
Here is the major point: I can thank my friend [email protected] for helping me see this. Notice the CallServer(“Save”,””) this is how we can distinguish which button has been clicked on the Server Ribbon. Thus on the Server Side in RaiseCallbackEvent method we might have something like this:
public void RaiseCallbackEvent(string eventArgument) { if (eventArgument.Contains("Save")) { //handle the save event here } }
You can handle any Ribbon Button click by hooking here!
There is a piece missing here that I haven’t covered and that is the client callback! For this discussion I am not using it. I only wanted to be able to get server side processing on client click events for the Ribbon. I am not new to coding and I am sure there are other ways to solve this puzzle but this one offers a repeatable way to hook on the server side to the Ribbon Events!