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.