Saturday, January 16, 2010

SharePoint 2010 Ribbon Customization Part IV: How to add PostBack commands to ribbon?


In this article I will cover how we can add commands to the ribbon which raises PostBack events.
I have add a new Button "New" within group "Console" on Items Tab. Below is the XML declaration for it,
If you observe above XML carefully, then you will find that I haven't declared the CommandUIHandler element. So events will not be raised for this Control. If you deploy it as it is then you will see the Button is disable.
What we want to do is, we want a command for this button which will raise the events and that will PostBack the page. So let's add the Command Handler for that. To add Custom ECMA Script we have two options,
  • Override the delegate control on the page: AdditionPageHead delegate control can be used to insert custom ECMA script on page. This is the best customizable options we have. Wherein you can choose the desired list for which you want to apply this customization.
  • Put a web part on the page: This option is good when we have new/display and edit page for list or library or a web part page.
We will go with Delegate Control.
So let's add a user control "RibbonDelegate" to Solution and insert XML declaration. Note the Control element in above xml declaration, we have instructed the "AdditionalPageHead" to host our Control.
In "RibbonDelegate" control, We have four types of command for ribbon SPRibbonPopulateQueryCommand, SPRibbonQueryCommand, SPRibbonCommand, SPRibbonPostBackCommand . We will use only SPRibbonCommand and SPRibbonPostbackCommand rest we will see in my next article where using this commands we will populate controls on fly.
  • As usual for Group we need command with no action. So I have taken SPRibbonCommand with second parameter empty. In case if you interested to fire any JavaScript function then second parameter of this object will be name of that JavaScript function.
  • For New button we need to PostBack, so we will use SPRibbonPostBackCommand. When we use this object at the same time we also need to implement IPostBackEventHandler interface. So we can handle the post back event and rout the system flow to post backed method. Note that "NewScorecard" is the Post back command which we will use while handling PostBack event.
  • SPRibbonScriptManager registers the JavaScript delegate functions for PageComponent. Second parameters of its methods are the name of JavaScript functions which we have mentioned in its Page Component. Later on we will see PageComponent in detail.
Now we are done with command declarations and Page Components. Now we need a PageComponent which will establish communication between Ribbon and Page. So let's go and declare the PageComponent.
Refer the SP.Ribbon.Custom.UI.js file in sample code.
Is PageComponent making you more confuse? So let's see how Ribbon communicates with page.
  • There is always a single instance of a PageManager for every page. It is defined in CUI.js file you can inspect the CUI.js file for CUI.Page.PageManager. Who holds the FocuManager(CUI.Page.FocusManager) , CommandDispatcher (CUI.Page.CommandDispatcher), UndoManager(CUI.Page.UndoManager) and other supporting objects.
  • CommandDispatcher registers all commands for ribbon and keeps the track of PageComponent. When command receive to PageManager, PageManager handovers the command to CommandDispatcher then CommandDispatcher routs the command to appropriate PageComponent.
  • PageComponent is the one who has actual implementation of commands. This is inherited by CUI.PageComponent. So Custom PageComponent should always follow the same class structure as CUI.PageComponent has.
Let's see the system flow of Button/command click,
First of all our PageComponent is registered with PageManager. PageManager has two methods addPageComponent() and removePageComponent() which takes care of registration of page component. All OOB page components you can find into SP.Ribbon.js file.

Button we used is of type "CUI.Controls.Button" and its base class is "CUI.Control". You can find declaration for all Ribbon controls into CUI.js file. This file has all classes used to construct the Ribbon.
  • User clicks on New Button.
  • OnClick event Button access its parent component, in this case it is a Group which is a type of "CUI.Component"
  • Then it calls the components raiseCommandEvent() method and then this method propagate the event to Tab and finally tab handovers this command with all required command information to PageManager.
  • Once PageManager receives the command, he passes that to CommandDispatcher along with registered PageComponents
  • CommandDispatcher then pick up appropriate PageComponent using sequence number and pass that command to PageComponent
  • PageComponent then calls method attached to command.
If everything sounds confusing then leave it. Just keep in mind that we always need a PageComponent whenever we declare commands using code behind.
So now we have defined the PageComponent for us lets register it. Click event of New Button causes page to postback, when page gets postback our delegate controls gets loaded and there we handle the post back event. Handling post back event in user control is the same as we are doing with plain vanilla asp.net pages.

Once you define a PageComponent, then you don't need to define it every time you create a new ribbon tab or control. You can use the same PageComponent across your application. All this looks very complicated at first time but once you become familiar with it you will feel very easy to have custom actions into ribbon for your application.

Few Important JS files: SP.Ribbon.js, SP.Core.js, CUI.js, Core.js

I hope this will help you all.

6 comments:

  1. Where source code for this example can be downloaded?

    ReplyDelete
  2. Is the source code available anywhere? Best wishes, Volker

    ReplyDelete
  3. the 'How To Add PostBack commands to ribbon' link at the bottom of this post (and throughout the series) seems to be obsolete. Thanks again for sharing your SharePoint expertise in such detail.

    ReplyDelete
  4. hi how to add tab in ribbon ,,,
    in main site,,,
    not in list or document...

    ReplyDelete