Leveraging the Ribbon API and Dialog Framework

Leveraging the Ribbon API and Dialog Framework
Cory Peters
Chief SharePoint Architect
Eastridge Technology, Inc.

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

Leveraging the dialog framework
Creating, deploying and interacting with dialogs

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

how it works
Use returnVal for further processing or display result
Perform any OM or Client OM functionality
Page / Web Part
Dialog
showModalDialog
url, callback
callbackFunction
dialogResult, returnVal
OK
Cancel
dialogResult (int)
1 = OK
0 = Cancel
returnVal (string)
Application Page

SP.UI.ModalDialog
SP.UI.ModalDialog.showModalDialog(options)
Options parameter
url
title
allowMaximize
showClose
width
height
dialogReturnValueCallback

creating a dialog
varoptions = 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);

Getting data into a dialog
Creating the Dialog
varoptions = 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(‘;’);

Getting data from a dialog
var form = document.forms.<%SPHttpUtility.NoEncode(Form.ClientID,Response.Output);%>;
varitemTitle = form.<%SPHttpUtility.NoEncode(itemTitleTextbox .ClientID,Response.Output);%>.value;

closing a dialog
OK Button Clicked
SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.OK, ‘Return Data’);
Cancel Button Clicked
SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.cancel, 'Canceled');

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);
}

dialog demo

Customizing the ribbon
XML, XML and some JavaScript!

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

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

RIBBON XML TERMINOLOGY
Ribbon
Tab
Contextual Tab
Group
Section
Row
Control

Targeting ribbons
CustomAction Location

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

control displays
DisplayMode
Display modes listed are not available for all controls.

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

RIBBON XML
CommandUIExtension
CommandUIDefinition
CommandUIHandlers

RIBBON XML
CommandUIExtension
CommandUIDefinition

RIBBON XML
CommandUIExtension
CommandUIDefinition
GroupTemplate
Tab

RIBBON XML
CommandUIExtension
CommandUIDefinition
Tab

RIBBON XML
CommandUIExtension
GroupId
CommandUIDefinition
Tab
Scaling
Groups
MaxSize
Group
Controls
Scale
Etc
Button
DropDown
MaxSize
Scale
Group
Controls
Etc
Button
DropDown
GroupId

RIBBON XML
CommandUIExtension
CommandUIDefinition
GroupTemplate
Tab

RIBBON XML
CommandUIExtension
CommandUIDefinition
GroupTemplate

RIBBON XML
CommandUIExtension
CommandUIDefinition
GroupTemplate
Layout
Section
Row
ControlRef
ControlRef
Row
ControlRef
ControlRef
Section

RIBBON XML
CommandUIExtension
CommandUIDefinition
GroupTemplate
Tab

RIBBON XML
CommandUIExtension
Template Id
CommandUIDefinition
GroupTemplate
Tab
Layout
Groups
Section
Group
Row
Controls
ControlRef
ControlRef
Button
DropDown
TemplateAlias
Scaling
MaxSize
Scale
Size

RIBBON XML
CommandUIExtension
CommandUIDefinition
CommandUIHandlers

RIBBON XML
CommandUIExtension
CommandUIHandlers

RIBBON XML
CommandUIExtension
CommandUIHandlers
Two attributes: Command, CommandAction
Command is a unique identifier
CommandAction is JavaScript, URL or anything that was previously used in an UrlAction
CommandUIHandler
CommandUIHandler
CommandUIHandler
CommandUIHandler
CommandUIHandler

RIBBON XML
CommandUIExtension
CommandUIHandlers
CommandUIDefinition

RIBBON XML
CommandUIExtension
CommandUIHandlers
CommandUIDefinition
CommandUIHandler
Tab
Groups
CommandUIHandler
Group
CommandUIHandler
Controls
Button
DropDown
Group
Command Id
Controls
Button
DropDown

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');"/>

Page Component
JavaScript class that serves as the middle man between the Ribbon and your customization
Uses a structured contract that the Ribbon understands

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.initializePageComponent = function () {
varribbonPageManager= SP.Ribbon.PageManager.get_instance();
if (null !== ribbonPageManager) {
ribbonPageManager.addPageComponent(CP.SharePoint.RibbonExample.PageComponent.instance);
}
}

Delegate Control
Load SharePoint Prerequisites
<SharePoint:ScriptLinkName="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>

Getting current Context
Get List of Selected Items
// Returns a collection of item ids
varctx = SP.ClientContext.get_current();
varitems = SP.ListOperation.Selection.getSelectedItems(ctx);
Get Selected List
// Returns a guid
SP.ListOperation.Selection.getSelectedList()

ribbon demos

resources
XML file defining all OOTB Ribbons
C:program filescommon filesMicrosoft SharedWeb Server Extensions14TEMPLATEGLOBALXMLCMDUI.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

Leveraging the Ribbon API and Dialog Framework

by Cory Peters on Jul 01, 2010

Accessibility

Categories

Tags

Upload Details

Usage Rights

Statistics

Leveraging the Ribbon API and Dialog Framework — Presentation Transcript