Microsoft SharePoint Developer Documentation Team Blog : Samples

How to Add a Tab to the Ribbon in SharePoint Foundation

Andrew May — Tue, 08 Dec 2009 03:07:00 GMT

(Before he left for a week of laying on various tropical beaches with drinks in his hand, Dallas asked me to post this for him. Since I'm stuck in the rainy Northwest and had nothing better to do, I was happy to oblige him.)

The ribbon has unified the command surface inside of SharePoint. It is now the primary point of entry for working with items inside of SharePoint. As such the ribbon is extensible through the use of declarative XML in a Feature.

This post will cover how to add a new tab to the ribbon in Microsoft SharePoint Foundation 2010. It will also, by necessity, cover how to create a group, controls, template, and scaling behavior. I will build this solution in Visual Studio 2010 Beta 2 and as a sandboxed solution for the ease of deployment.

The following will appear in a future version of the SDK. It is preliminary documentation and subject to change.

First, you will want to create a new project. Click on File, New, and then Project.

Under Visual C#, choose Empty SharePoint Project and enter AddARibbonTab for the Name. Click OK.

In the SharePoint Customization Wizard, choose Deploy as a sandboxed solution. Click Finish.

In the Solution Explorer, right click on Features and choose Add Feature.

Change the Title of the Feature to Custom Ribbon Tab. Also, rename Feature1 in the Solution Explorer to CustomRibbonTab.

Right click on the AddARibbonTab project in the Solution Explorer and choose Add, New Item…

In the Add New Item dialog, choose the Empty Element template. Enter CustomRibbonTab as the Name.

In the Elements.xml file, insert the following CustomAction element. The Location attribute tells the CustomAction where to apply the customization. The following list explains the acceptable values.

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.

<?xml version="1.0" encoding="utf-8"?>

<CustomAction

Id="MyCustomRibbonTab"

Location="CommandUI.Ribbon.ListView"

RegistrationId="101"

RegistrationType="List">

</CustomAction>

</Elements>

Add the following elements to define the ribbon extension and tab. The Location on the CommandUIDefinition element defines where the controls inside of it will render. In this example, you reference the Tabs collection of the ribbon. The _children convention tells the ribbon to insert the following XML, whether it is a tab, group, or control, into the collection of tabs. The Sequence attribute on the Tab element defines where the tab will render in regards to other tabs. The default tabs use multiples of 100, so the Sequence attribute should not be a multiple of 100 to prevent collisions.

<CommandUIDefinition

Location="Ribbon.Tabs._children">

<Tab

Id="Ribbon.CustomTabExample"

Title="My Custom Tab"

Description="This holds my custom commands!"

Sequence="501">

When creating a custom tab, you must define how the tab will scale when controls are added. This is handled through the use of the Scaling element along with a GroupTemplate. The MaxSize element defines the maximum size of the controls in the group. The Scale element defines how the group will scale in different situations. The GroupId attribute associates a group with the scale size. The Size attribute is defined by the Layout element, which is defined later in this topic.

<Scaling

Id="Ribbon.CustomTabExample.Scaling">

<MaxSize

Id="Ribbon.CustomTabExample.MaxSize"

GroupId="Ribbon.CustomTabExample.CustomGroupExample"

Size="OneLargeTwoMedium"/>

<Scale

Id="Ribbon.CustomTabExample.Scaling.CustomTabScaling"

GroupId="Ribbon.CustomTabExample.CustomGroupExample"

Size="OneLargeTwoMedium" />

</Scaling>

Now, you will define the groups of controls that will appear on the tab. The Group element contains the usual attributes along with a Template attribute. The Template attribute references the GroupTemplate that is defined later in this topic. The Controls element contains the controls that will render in the group. These can be buttons, dropdowns, and other control types. You can find a list in the SDK at this address: http://msdn.microsoft.com/en-us/library/ee537017(office.14).aspx. The controls inside the group must define the TemplateAlias and Command attributes. Like tabs, each control has a Sequence attribute that defines where they will render in the group. The default controls are based on multiples of 10, so any custom controls should not use a multiple of 10 to avoid collisions. The Command attribute is used by the CommandUIHandler defined later in this topic but is required even if the CommandUIHandler is not specified. The TemplateAlias attribute defines where the control will render in relationship to the GroupTemplate.

<Group

Id="Ribbon.CustomTabExample.CustomGroupExample"

Description="This is a custom group!"

Title="Custom Group"

Sequence="52"

Template="Ribbon.Templates.CustomTemplateExample">

<Button

Id="Ribbon.CustomTabExample.CustomGroupExample.HelloWorld"

Command="CustomTabExample.HelloWorldCommand"

Sequence="15"

Description="Says Hello to the World!"

LabelText="Hello, World!"

TemplateAlias="cust1"/>

<Button

Id="Ribbon.CustomTabExample.CustomGroupExample.GoodbyeWorld"

Command="CustomTabExample.GoodbyeWorldCommand"

Sequence="17"

Description="Says Good-bye to the World!"

LabelText="Good-bye, World!"

TemplateAlias="cust2"/>

<Button

Id="Ribbon.CustomTabExample.CustomGroupExample.LoveWorld"

Command="CustomTabExample.LoveWorldCommand"

Sequence="19"

Description="Says I <3 the World!"

LabelText="I <3 you, World!"

TemplateAlias="cust3"/>

</Controls>

</Group>

</Groups>

</Tab>

</CommandUIDefinition>

With that code in place, you have finished the first CommandUIDefinition that includes the tab, groups, and controls. You need to define how the controls will render inside of the group. You do this using a GroupTemplate element in another CommandUIDefinition. The CommandUIDefinition will have a Location of Ribbon.Templates._children. This follows the pattern for Groups and Tabs.

The GroupTemplate element contains a Layout element with Section and Row elements. The Layout element has a LayoutTitle that is used for the Size attribute on the MaxSize and Scale elements. The Section elements define the position of the controls as well as how many rows will render inside that section. The Row element contains one or more ControlRef elements. ControlRef elements define how your controls will display. The DisplayMode attribute can have the following values:

Value	Description
Small	Renders as a small icon without label text.
Medium	Renders as a 16x16 icon with label text.
Large	Renders as a 32x32 icon with label text.
Text	Renders as text only.

The ControlRef elements also define the TemplateAlias values that you used for the TemplateAlias attribute on the buttons. Note that only one control per group can use this value. You cannot have two controls with the same TemplateAlias unless it is an OverflowArea. You can reuse the TemplateAlias across different groups though. There is also an OverflowArea element that defines how controls will render if there are too many controls in a group. The TemplateAlias attributes that refer to OverflowAreas in the GroupTemplate can be used on multiple controls.

In this example, you will define two sections for rendering the controls. One section will be a row of large buttons while the other section will contain two rows of medium-sized buttons.

<Layout

Title="OneLargeTwoMedium"

LayoutTitle="OneLargeTwoMedium">

<Row>

</Row>

</Section>

<Row>

</Row>

<Row>

</Row>

</Section>

</Layout>

</GroupTemplate>

</CommandUIDefinition>

</CommandUIDefinitions>

The final step is to write handlers for the buttons. These are inside CommandUIHandler elements. The Command attribute is a unique name for the command and used for the Command attribute on controls. The CommandAction attribute contains the action that is performed for the control. This can be JavaScript, an URL, or anything that was previously contained in an UrlAction element.

<CommandUIHandler

Command="CustomTabExample.HelloWorldCommand"

CommandAction="javascript:alert('Hello, world!');" />

<CommandUIHandler

Command="CustomTabExample.GoodbyeWorldCommand"

CommandAction="javascript:alert('Good-bye, world!');" />

<CommandUIHandler

Command="CustomTabExample.LoveWorldCommand"

CommandAction="javascript:alert('I love you, world!');" />

</CommandUIHandlers>

</CommandUIExtension>

With the addition of the CommandUIHandlers, you have finished your Elements.xml file. Press F5 to deploy your solution. Then, navigate to the Shared Documents folder. You should see the Custom Tab. Click on Custom Tab to open it. Click any of the buttons to show the associated alert.

Hopefully this walkthrough has been helpful! If you have any questions or concerns, please let me know in the comments.

Full Code Listing:

<?xml version="1.0" encoding="utf-8"?>

<CustomAction

Id="MyCustomRibbonTab"

Location="CommandUI.Ribbon.ListView"

RegistrationId="101"

RegistrationType="List">

<CommandUIDefinition

Location="Ribbon.Tabs._children">

<Tab

Id="Ribbon.CustomTabExample"

Title="My Custom Tab"

Description="This holds my custom commands!"

Sequence="501">

<Scaling

Id="Ribbon.CustomTabExample.Scaling">

<MaxSize

Id="Ribbon.CustomTabExample.MaxSize"

GroupId="Ribbon.CustomTabExample.CustomGroupExample"

Size="OneLargeTwoMedium"/>

<Scale

Id="Ribbon.CustomTabExample.Scaling.CustomTabScaling"

GroupId="Ribbon.CustomTabExample.CustomGroupExample"

Size="OneLargeTwoMedium" />

</Scaling>

<Group

Id="Ribbon.CustomTabExample.CustomGroupExample"

Description="This is a custom group!"

Title="Custom Group"

Sequence="52"

Template="Ribbon.Templates.CustomTemplateExample">

<Button

Id="Ribbon.CustomTabExample.CustomGroupExample.HelloWorld"

Command="CustomTabExample.HelloWorldCommand"

Sequence="15"

Description="Says hello to the World!"

LabelText="Hello, World!"

TemplateAlias="cust1"/>

<Button

Id="Ribbon.CustomTabExample.CustomGroupExample.GoodbyeWorld"

Command="CustomTabExample.GoodbyeWorldCommand"

Sequence="17"

Description="Says good-bye to the World!"

LabelText="Good-bye, World!"

TemplateAlias="cust2"/>

<Button

Id="Ribbon.CustomTabExample.CustomGroupExample.LoveWorld"

Command="CustomTabExample.LoveWorldCommand"

Sequence="19"

Description="Says I love the World!"

LabelText="I love you, World!"

TemplateAlias="cust3"/>

</Controls>

</Group>

</Groups>

</Tab>

</CommandUIDefinition>

<Layout

Title="OneLargeTwoMedium"

LayoutTitle="OneLargeTwoMedium">

<Row>

</Row>

</Section>

<Row>

</Row>

<Row>

</Row>

</Section>

</Layout>

</GroupTemplate>

</CommandUIDefinition>

</CommandUIDefinitions>

<CommandUIHandler

Command="CustomTabExample.HelloWorldCommand"

CommandAction="javascript:alert('Hello, world!');" />

<CommandUIHandler

Command="CustomTabExample.GoodbyeWorldCommand"

CommandAction="javascript:alert('Good-bye, world!');" />

<CommandUIHandler

Command="CustomTabExample.LoveWorldCommand"

CommandAction="javascript:alert('I love you, world!');" />

</CommandUIHandlers>

</CommandUIExtension>

</CustomAction>

</Elements>

SharePoint 2010 SDK Code Samples Posted to Code Gallery

Andrew May — Fri, 23 Oct 2009 23:29:00 GMT

For the SharePoint 2010 release, we’re trying something a little different with our sample code solutions. During the Beta timeframe, we’re going to be posting them to Code Gallery, rather than waiting to release them in the SharePoint 2010 SDK for the first time at RTM. This will let developers benefit from having the code samples available as early as possible. And we’re hoping it’ll benefit the code samples by having the SharePoint developer community giving us feedback on the samples and how we can make them better. We’ll include the code samples in their final form in the SharePoint 2010 SDK download at RTM.

We’ll be keeping the list below up-to-date each time we release a new code sample, so you might want to bookmark this post. (We’ve already got three samples posted, and the SharePoint 2010 Beta isn’t scheduled for public availability until next month.)

Unless otherwise noted, each code sample is written in C#.

SharePoint Foundation 2010 Code Samples

Implementation of IBackupRestore

This sample is a custom content class that implements Microsoft.SharePoint.Administration.Backup.IBackupRestore. Objects that instantiate this interface appear in the backup/restore UI of the SharePoint Central Administration application as items that can be selected for backup or restoration.

SharePoint Server 2010 Code Samples

Activity Feeds Console Application

A console application that demonstrates the basic functions of a custom activity feed gatherer application.

This sample creates a custom activity feed gatherer and demonstrates how to use the new Activity Feed object model in Microsoft SharePoint Server 2010. The sample creates custom ActivityTemplate, ActivityType, and ActivityEvent objects and shows how to publish and multicast events from a custom gatherer. Console output verifies that each step in the application is finished.

Social Data Statistics Web Part

A Web part that displays social data statistics.

This sample consists of a Microsoft Visual Studio 2010 SharePoint Visual Web part project. After you build and deploy this project on your Microsoft SharePoint Server 2010 site, you can add this Web part to any page where you want to display statistics for the social tagging activities of your users. The Web part displays the following information in three tables:

· Each URL that has been tagged, and the terms with which each URL has been tagged.

· Each term that has been used in a social tag, and the number of times that term has been used.

· Each user who has added a social tag, and the number of times that user has tagged URLs.

The sample demonstrates how to use the new Social Data object model in SharePoint Server 2010. It also takes advantage of the SharePoint Visual Web Part template, one of the new SharePoint templates that you can use in Visual Studio 2010.

Got Code?

Andrew May — Wed, 21 Oct 2009 01:49:00 GMT

Contribute a Code Sample and Get Your Name in the SharePoint 2010 SDK

We’re looking for experienced SharePoint developers to share their skill and technical expertise with the SharePoint community. You’ll help your fellow SharePoint developers, and receive full attribution in the SharePoint SDK for doing so!

What we’re looking for are short code samples, what we on documentation teams tend to think of as ‘snippets’. A handful of lines that illustrate a discreet task or show how to exercise a specific piece of the object model, rather than a full-blown solution that addresses an entire scenario. Basically, the short code samples you’d find in a typical reference topic like this one.

In particular, we’re on the hunt for code samples that do one or more of the following:

· Show developers how to accomplish common SharePoint tasks programmatically

· Illustrate best coding practices in using the SharePoint object model

· Demonstrate how to avoid pitfalls when using lesser-known areas of the SharePoint object model

· Or otherwise show off the power and flexibility of developing SharePoint solutions

If you’re an experienced SharePoint developer, you probably have a toolbox of code snippets like these already; sections of code that you use over and over to perform the same routine tasks, or pieces of code that you’re particularly proud of having come up with as work-arounds for some of the, um, “eccentricities” of the SharePoint object model.

What we’re asking is that you share your hard-won knowledge by letting us publish your code samples in our SDK reference topics. In return, we want to make sure you get full credit, by giving you attribution right in the topic where the code sample appears. This includes a link to your company site. You can see an early example of this in this reference topic for the CreateTaskWithContentType class.

The SDK gets more real-world code samples, and you get increased visibility within the larger SharePoint developer community.

To submit a code sample, just shoot us an email including your code sample(s) at gotcode@microsoft.com. Include a short description of what each code sample does, or what task you would use the code sample to accomplish. Oh, and if there are any prerequisites that need to be specified for your code sample to run successfully, that’d be great to know as well. (For example, the code sample on the SPList class topic lists a few using directives, and the existence of an .aspx page containing a label control, as prerequisites.)

I’ve attached a zip with our code sample guidelines and some sample data to this post. These are the best practices for writing code samples that we give our external partners who write samples for us. For the best chance of getting your sample included in the SDK, take a look at the best practices for code snippets (the guidelines are really short, and won’t take more than a few minutes to review, I promise.)

Now, since the SharePoint 2010 Betas aren’t due out until November, for now we’re talking about code snippets written against the WSS 3.0 or MOSS 2007 object models. Go ahead and send them our way. And once you’ve worked with the SharePoint 2010 Betas a bit, you’ll undoubtedly create some useful or illuminating code samples in fairly short order. Send those our way as well. You could end up with a byline in the SharePoint SDK!

Any questions, feel free to ping gotcode@microsoft.com, or leave a comment.

Add Virtual Earth Interactive Maps to your Search Server Site

jcrowley — Wed, 02 Apr 2008 01:57:00 GMT

(cross-posted from Enterprise Search Blog)

Are you trying to think of ways to make your Search Server site more interactive and graphical? You can use Federation as a way to enhance the functionality of your search result pages.

The Federated Search Web Part makes it possible to display more than results from OpenSearch (1.0/1.1) sites on your search results page. The Search Server 2008 SDK explains how to include results from SQL Server database queries and search sites that do not expose XML feeds (such as Atom or RSS). In both scenarios, you do this by means of a "connector," a light-weight interface that sends queries to a given location or database, places the results into a structured XML document, and sends that XML to a Federated Search Web Part.

This sample demonstrates how you can extend the connector concept to Web service requests other than basic search queries. It shows how to use a connector to pass an address string to Microsoft's MapPoint Web service in order to obtain the latitude and longitude coordinates for that address. Once you have those coordinates, displaying a Microsoft Virtual Earth map requires only the addition of some Javascript to your Federated Location definition file. See this Codeplex project for the sample code (along with a sample Federated location definition file) and an explanation of how to implement it on your own site.

This sample is part of the Search Community Toolkit.

Jim Crowley
Programming Writer
Microsoft Corp