sharepoint ribbon deep dive
DESCRIPTION
Customizing the SharePoint 2010 ribbon - adding new tabs/groups/buttons, how to implement commands, advanced ribbon controls, FlyoutAnchor controls.TRANSCRIPT
Deep Dive on SharePoint Ribbon Development & Extensibility Chris O’Brien, MVP SharePoint ServerIndependent(with credit to Andrew Connell)
Independent SharePoint consultant
Blog: www.sharepointnutsandbolts.com
Twitter: @ChrisO_Brien
Book: Real World SharePoint 2010 (20 MVPs)
LinkedIn: http://uk.linkedin.com/in/chrisobrienmvp
Introduction
Ribbon Architecture Customizing the Ribbon Ribbon Commands
Command UI Handler Page Component
Sandbox Considerations Advanced Ribbon Controls Ribbon Development Tips & Tricks
Agenda
Powered by XML and JavaScript XML defines visual components JavaScript for logic – commands, disabling etc. Create a Feature to put customization in the ribbon
Actions implemented using commands Command name specified in XML JavaScript ‘listens’ for command
Standard ribbon mainly defined in CMDUI.xml file:{SharePoint Root}\TEMPLATE\GLOBAL\XML\CMDUI.xml
Ribbon Architecture How Does it Work?
Ribbon User Experience / UI
tab
ribbon
group{template}
control
contextual tab group
contextual tab
Ribbon.Read Ribbon.BDCAdmin Ribbon.DocLibListF
ormEdit Ribbon.ListForm.Dis
play Ribbon.ListForm.Edi
t Ribbon.PostListForm.E
dit Ribbon.SvcApp Ribbon.Solution
Ribbon Architecture Key ribbon locations
Ribbon.UsageReport Ribbon.WikiPageTab Ribbon.PublishTab Ribbon.WebPartPage Ribbon.WebApp Ribbon.SiteCollections Ribbon.CustomComma
nds
Customizing the SharePoint Ribbon
demo
Demo – adding a new tab/group/button
Demo – adding a contextual tab
Do not remove OOTB controls from the Ribbon Bad user experience & inconsistent from rest of SharePoint
Group templates: *ALWAYS* create your own Copy-paste instead of reusing those included with SharePoint
Provide multiple layouts & scaling options for best UX
Be selective - only add customizations to pages that need it
Do *NOT* modify ribbon controls with jQuery
Ribbon UI Best Practices
Ribbon Command: a named object that performs an action
Each user interface (UI) control assigned a command Similar to XAML command framework Allows a loose coupling of logic with UI components Commands have three characteristics:
Name: easy way to associate with a control Execute: what they do CanExecute: logic defining when it is available
Example: Paste in Microsoft Office Word
Ribbon Commands
Define command declaratively within the Feature Defined with XML Execute & CanExecute portions defined with JavaScript
Option 1 - Command UI Handler
Define command entirely in a JavaScript object Resides in custom JavaScript file (*.js) No XML components
JS object provides certain functions init, canHandleCommand, handleCommand
Option 2 - Page Component
Command Handler Analyzed
Advantages•Easy to create•Easy to manage •Great for simple commands
Disadvantages
•If complex, hard to manage•Lots of JavaScript can be hard to manage•Not cached on the client•Not reusable outside of the definition
Page Component Analyzed
Advantages•External JS library•Easier to manage & debug•Can be minified•Allows for greater control over commands•Enable/disable command•Block loss of focus•Reusable across customizations
Disadvantages
•Poor JavaScript dev tools•Must be added to the page•More work (build, register & initialize on page)•All OO JavaScript
Global Commands
•Always available when on a page•(if CanExecute says it is available)
Focused Command
•Only available at specific times, e.g. when web part has focus•Example: Content Editor Web Part controls
Global vs. Focused Commands
Used when page has multiple web parts (e.g.) of same type Which one does pressing your ribbon button refer to?
Ribbon commands
demo
Command UI Handler Good for very small commands Good for isolated commands (one-time use)
Page Component Ideal for complex commands Ideal for performance considerations with page weight Easier to debug
Ribbon Command Best Practices
Most advanced ribbon customizations work well in sandbox
Typically only 2 changes required: Files provisioned in a Module must be published in code (draft
by default) Page components must be initialized via
CustomAction/ScriptOnDemand
Exception: Contextual tab - SPRibbon[.MakeTabAvailable] not in sandbox
Sandbox Considerations
SplitButton• Easy default
plus sub-menu
ToggleButton• Off or on
Spinner• Select within a
range
Going Beyond Buttons
‘Menu’ selection controls: DropDown, SplitButton, FlyoutAnchor
etc.
Two presentation options: Controls Gallery (provide InnerHTML or image) –
powerful! Two data options:
Declarative - static XML Imperative/dynamic (e.g. from SP list) -
build XML in JavaScript
Going Beyond Buttons
Advanced Ribbon Customizations
demo
Demo – beyond buttons
Pseudo “change-tracking” in publishing site:
Demo – flyout anchor
Before:
After:
Add social networking widgets to page (1 of 2):
Demo – flyout anchor
Before:
Add social networking widgets to page (2 of 2):
Demo – flyout anchor
After:
Although share same XML schema, beware differences: Do NOT specify TemplateAlias for controls in menu controls. Do NOT specify DisplayMode on MenuSection Do NOT specify Image16x16/Image32x32 on Button controls in
DropDowns
Unlike Buttons, DO specify same Command for all DropDown/menu items
Menus *require* page component - object passed to handleCommand used to determine selected item
Menu Control Gotchas
Search in CMDUI.xml (and others) for examples Identify associated JavaScript/page component
Find command names and search in {SharePointRoot} files (.js)
To see execution: Ensure app in debug mode (so that non-minified JS files used)
<compilation debug="true"> Add breakpoint in JavaScript debugger, then step-through Note the properties of JavaScript objects passed to
handleCommand
Working with a new control - cheatsheet
Code you need to know
Server side:
SPRibbon.MakeTabAvailable For contextual tab
SPList.UserCustomActions Target an individual list
JavaScript:
RefreshCommandUI() Refresh ribbon, e.g. in async callback
SP.SOD.ExecuteOrDelayUntilScriptLoaded()
Deal with JS dependencies
Avoiding Cached JS & CSS: Development: aggressively clear client & server cache Deployment: *ALWAYS* reference files with version number
to avoid end-user browser caching e.g: …/MyScript.js?Rev=2011.10.05
Find your favorite JavaScript debugging tool – you’ll need it
CKS:Dev contextual tab project item – great sample
Chris’ Tips & Tricks
COB’s ribbon samples - http://bit.ly/utr2g8 (adding a tab/group/button, cool controls [SplitButton,
ToggleButton, Spinner], static/dynamic FlyoutAnchor samples)
AC’s ribbon samples - http://bit.ly/uVKABO (contextual tabs, commands explained, async processing,
dialogs)
Helpful References
Ribbon Architecture Customizing the Ribbon Ribbon Commands
Command UI Handler Page Component
Sandbox Considerations Advanced Ribbon Controls Ribbon Development Tips & Tricks
Summary
© 2011 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted
to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.