Leveraging the Ribbon API and Dialog Framework

This is a developer oriented presentation that focuses on the new Ribbon and Dialog functionality, how it works and how to build solutions on top of these great features. The actual presentation involved some source code that will be included in an upcoming blog post.

Transcript

1. LEVERAGING THE RIBBON API AND DIALOG FRAMEWORK CORY PETERS Chief SharePoint Architect Eastridge Technology, Inc.
2. ABOUT ME • Chief SharePoint Architect at Eastridge Technology, Inc. • Microsoft Gold Partner focused on the south east and based out of North Carolina • Working with SharePoint since Portal Server 2003 • Worked with all aspects of SharePoint including • Branding • Development • Administration • Implementation • Architecture Blog • http://corypeters.net Twitter • @cory_peters
3. LEVERAGING THE DIALOG FRAMEWORK CREATING, DEPLOYING AND INTERACTING WITH DIALOGS
4. DIALOG GOALS • Understand how dialogs work • How to create a dialog • How to pass data to/from a dialog • What’s involved in deploying a custom dialog
5. HOW IT WORKS Page / Web Part Dialog OK Cancel showModalDialog url, callback callbackFunction dialogResult, returnVal Perform any OM or Client OM functionality Use returnVal for further processing or display result dialogResult (int) • 1 = OK • 0 = Cancel returnVal (string) Application Page
6. SP.UI.MODALDIALOG • SP.UI.ModalDialog.showModalDialog(options) • Options parameter • url • title • allowMaximize • showClose • width • height • dialogReturnValueCallback
7. CREATING A DIALOG var options = SP.UI.$create_DialogOptions(); options.url = "/_layouts/Ex/CustomPage.aspx"; options.width = 400; options.height = 400; options.dialogReturnValueCallback = Function.createDelegate(null, customCallback); SP.UI.ModalDialog.showModalDialog(options);
8. GETTING DATA INTO A DIALOG Creating the Dialog var options = SP.UI.$create_DialogOptions(); options.url = "/_layouts/Ex/CustomPage.aspx?p1=value&p2=v1;v2;v3"; … Within the ApplicationPage string param1 = Request.QueryString[“p1”]; string[] param2 = Request.QueryString[“p2”].Split(‘;’);
9. GETTING DATA FROM A DIALOG var form = document.forms.<%SPHttpUtility.NoEncode(Form.C lientID,Response.Output);%>; var itemTitle = form.<%SPHttpUtility.NoEncode(itemTitleTextbox .ClientID,Response.Output);%>.value;
10. CLOSING A DIALOG OK Button Clicked SP.UI.ModalDialog.commonModalDialogClose(SP.UI.Dialo gResult.OK, ‘Return Data’); Cancel Button Clicked SP.UI.ModalDialog.commonModalDialogClose(SP.UI.Dialo gResult.cancel, 'Canceled');
11. PROCESSING THE RESULT Callback receives two parameters: dialogResult and dialogData if (dialogResult === SP.UI.DialogResult.OK) { // use client OM for further processing } if (dialogResult === SP.UI.DialogResult.cancel) { SP.UI.Notify.addNotification(“Dialog was canceled. ", false); }
12. DIALOG DEMO
13. CUSTOMIZING THE RIBBON XML, XML AND SOME JAVASCRIPT!
14. RIBBON GOALS • Learn common terminology • Have a better understanding of the Ribbon XML • Know what’s involved in a ribbon customization • See how all the pieces play together
15. RIBBON OVERVIEW • Defined via XML within <CustomAction> and feature deployed • Tabs can be visible/hidden • Controls can be enabled/disabled * • No custom controls (.ascx) • Heavy JavaScript required / Client OM • Complex, nested, relational XML
16. RIBBON XML TERMINOLOGY • Ribbon • Tab • Contextual Tab • Group • Section • Row • Control
17. TARGETING RIBBONS Value Description CommandUI.Ribbon Customization appears everywhere for the specified RegistrationId. CommandUI.Ribbon.ListView Customization appears when the list view Web Part is present. CommandUI.Ribbon.EditForm Customization appears on the edit form. CommandUI.Ribbon.NewForm Customization appears on the new form. CommandUI.Ribbon.DisplayForm Customization appears on the display form. CustomAction Location
18. AVAILABLE CONTROLS CONTAINERS • Tab • Group CONTROLS • Button • CheckBox • Color Picker • Combo Box • Drop Down • Flyout Anchor • Insert Table • Label • Menu • Menu Section • MRU Split Menu • Spinner • Split Button • Textbox • Toggle Button
19. CONTROL DISPLAYS Value Description Small Renders as a 16 by 16 icon without label text. Medium Renders as a 16 by 16 icon with label text. Large Renders as a 32 by 32 icon with label text. Text Renders as text only. Display modes listed are not available for all controls. DisplayMode
20. WHAT MAKES UP A RIBBON? • Ribbon XML • Defines the tabs, groups, controls, rendering templates • JavaScript • CommandUIHandler or a custom Page Component • Handles populating Dropdowns, on click events, etc • Delegate Control • One approach to getting your custom JavaScript loaded into the page • Note: Any method of getting your JavaScript into the page is fine
21. RIBBON XML CommandUIExtension CommandUIDefinition CommandUIHandlers
22. RIBBON XML CommandUIExtension CommandUIDefinition
23. RIBBON XML CommandUIExtension CommandUIDefinition GroupTemplate Tab
24. RIBBON XML CommandUIExtension CommandUIDefinition Tab
25. RIBBON XML CommandUIExtension CommandUIDefinition Tab Scaling Groups MaxSize Scale MaxSize Scale Group Group Controls Controls Button DropDown Etc Button DropDown Etc GroupId GroupId
26. RIBBON XML CommandUIExtension CommandUIDefinition GroupTemplate Tab
27. RIBBON XML CommandUIExtension CommandUIDefinition GroupTemplate
28. RIBBON XML CommandUIExtension CommandUIDefinition GroupTemplate Layout Section Section Row ControlRef Row ControlRef ControlRef ControlRef
29. RIBBON XML CommandUIExtension CommandUIDefinition GroupTemplate Tab
30. RIBBON XML CommandUIExtension CommandUIDefinition GroupTemplate Tab Layout Section Row ControlRef ControlRef Groups Group Controls Button DropDown TemplateAlias Template Id Scaling MaxSize Scale Size
31. RIBBON XML CommandUIExtension CommandUIDefinition CommandUIHandlers
32. RIBBON XML CommandUIExtension CommandUIHandlers
33. RIBBON XML CommandUIExtension CommandUIHandlers CommandUIHandler CommandUIHandler CommandUIHandler CommandUIHandler CommandUIHandler Two attributes: Command, CommandAction Command is a unique identifier CommandAction is JavaScript, URL or anything that was previously used in an UrlAction
34. RIBBON XML CommandUIHandlers CommandUIExtension CommandUIDefinition
35. RIBBON XML CommandUIHandlers CommandUIExtension CommandUIDefinition CommandUIHandler Tab Groups Group Group Controls Controls Button DropDown Button DropDown CommandUIHandler CommandUIHandler Command Id
36. COMMAND UI HANDLER • Maps a control to set of JavaScript • Very powerful when coupled with the Client OM Example <Button Id=“ButtonId" Command=“ButtonCommand“ … /> <CommandUIHandler Command=“ButtonCommand“ CommandAction="javascript: SP.UI.Notify.addNotification(‘Button was clicked');"/>
37. PAGE COMPONENT • JavaScript class that serves as the middle man between the Ribbon and your customization • Uses a structured contract that the Ribbon understands Function Description Init Initialize the page component getFocusedCommands List of commands the page component will respond to when it has focus getGlobalCommands List of commands the page component will respond to anywhere on the page isFocusable Whether the page component can receive focus, if not focused commands won’t be used canHandleCommand List of commands the page component can handle handleCommand Logic for each of the commands the page component should handle yieldFocus Code runs when page component loses focus receiveFocus Code runs when page component gains focus
38. PAGE COMPONENT (CONT) • Create your custom page component class • Register your namespace • Register your class to inherit from CUI.Page.PageComponent • Initialize the page component CP.SharePoint.RibbonExample.PageComponent.initialize PageComponent = function () { var ribbonPageManager = SP.Ribbon.PageManager.get_instance(); if (null !== ribbonPageManager) { ribbonPageManager.addPageComponent(CP.SharePoint.Rib bonExample.PageComponent.instance); } }
39. DELEGATE CONTROL Load SharePoint Prerequisites <SharePoint:ScriptLink Name="SP.js" runat="server" LoadAfterUI="true” … /> <SharePoint:ScriptLink Name="CUI.js" runat="server" LoadAfterUI="true" … /> Load Custom JavaScript <SharePoint:ScriptLink Name="/_layouts/RibbonExample/sp.ui.RibbonExample.js" runat="server" LoadAfterUI="true“ … /> Initialize Our Page Component <script type="text/javascript"> //<![CDATA[ function initializeRibbonExample() { CP.SharePoint.RibbonExample.PageComponent.initialize(); } ExecuteOrDelayUntilScriptLoaded(initializeRibbonExample, 'sp.ui.RibbonExample.js'); //]]> </script>
40. GETTING CURRENT CONTEXT Get List of Selected Items // Returns a collection of item ids var ctx = SP.ClientContext.get_current(); var items = SP.ListOperation.Selection.getSelectedItems(ctx); Get Selected List // Returns a guid SP.ListOperation.Selection.getSelectedList()
41. RIBBON DEMOS
42. RESOURCES XML file defining all OOTB Ribbons • C:\program files\common files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\GLOBAL\XML\CMDUI.xml MSDN Resources • http://msdn.microsoft.com/en-us/library/ee540027.aspx • http://msdn.microsoft.com/en-us/library/ee539395.aspx • http://msdn.microsoft.com/en-us/library/ff407303.aspx Community Resources • http://www.sharepointnutsandbolts.com/2010/01/customizing-ribbon-part-1- creating-tabs.html • http://blogs.msdn.com/b/jfrost/archive/2009/11/08/how-to-display-a- sharepoint-dialog-from-ribbon-button-and-get-selected-item-context.aspx • http://blogs.msdn.com/b/vesku/archive/2010/02/25/how-to-sharepoint- 2010-js-client-object-model-and-ui-advancements.aspx