Exercise 2 - Customizing the Ribbon

Task 1 – Add an empty elements.xml file to the project

In this task, you will add a new button to the items section of a custom Products list. The button will go in the red area in the image below. The button will be a shortcut to the list settings page for the list.

In order to do this, you will add a new empty Elements file to your project which will become the basis for the ribbon customization. You will then add the required CAML that will insert the button and define the action that should happen when a user clicks the button.

1. Right click the project CustomActions_EventReceivers and select Add >> New Item…, select Empty Element.
2. Name the element Ribbon and click Add.

3. Insert the following CAML within the <Elements> tags of elements.xml.

   (Code snippet 2.3.2)

   XML

   <CustomAction Id="CustomRibbonTab" Location="CommandUI.Ribbon.ListView" RegistrationId="10001" RegistrationType="List" Title="Edit List Settings" Sequence="3" > </CustomAction>

Note the following important sections of the code

• CommandUI.Ribbon.ListView – Specifies when the customization will be visible. We only want our new button to appear when we select the items icon in the ribbon. You can also show the new button in other places in the UI. The following table explains the 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.

• RegistrationID – Corresponds to the ListID specified in your custom list, this was specified in the List Instance of lab 2.2 as 10001.

• Next, you will be adding a button to the ribbon. In order to this, add the following CAML within Elements/CustomAction.

  (Code snippet 2.3.3)

  XML

  <CommandUIExtension> <CommandUIDefinitions> <CommandUIDefinition Location="Ribbon.ListItem.New.Controls._children"> <Button Id="Ribbon.Documents.New.RibbonTest" Alt="Edit List Settings" Sequence="3" Command="List_Settings" LabelText="List Settings" Image32by32="/_layouts/images/actionssettings.gif" TemplateAlias="o1"/> </CommandUIDefinition> </CommandUIDefinitions> </CommandUIExtension>

Note the following important section of code:

Location="Ribbon.ListItem.New.Controls._children – This line specifies where the button will be located within the ribbon. See MSDN documentation for additional details about this section.

ListItem indicates that we want the button to be located in the List Tools section group.

New indicates that we want the button to be in the New section of the ribbon.

Controls._Children indicates that this will be a new control, not a replacement for an existing control.

1. Next, you will add a CommandUIHandler to the file. This section of code will specify what action will happen when the button is clicked. It can either be URL with tokens (See MSDN for all available tokens), or a call to JavaScript, which can leverage the JavaScript client object model to perform more advanced actions. Insert the following code in elements.xml at Elements\CustomAction\CommandUIExtension just under </CommandUIDefinitions>.

   (Code snippet 2.3.4)

   XML

   <CommandUIHandlers> <CommandUIHandler Command="List_Settings" CommandAction="{SiteUrl}/_layouts/listedit.aspx?List={ListId}"> </CommandUIHandler> </CommandUIHandlers>
2. The elements.xml file should now look like this:

   XML

   <CustomAction Id="CustomRibbonTab" Location="CommandUI.Ribbon.ListView" RegistrationId="10001" RegistrationType="List" Title="Edit List Settings" Sequence="3" > <CommandUIExtension> <CommandUIDefinitions> <CommandUIDefinition Location="Ribbon.ListItem.New.Controls._children"> <Button Id="Ribbon.Documents.New.RibbonTest" Alt="Edit List Settings" Sequence="3" Command="List_Settings" LabelText="List Settings" Image32by32="/_layouts/images/actionssettings.gif" TemplateAlias="o1" /> </CommandUIDefinition> </CommandUIDefinitions> <CommandUIHandlers> <CommandUIHandler Command="List_Settings" CommandAction="{SiteUrl}/_layouts/listedit.aspx?List={ListId}"> </CommandUIHandler> </CommandUIHandlers> </CommandUIExtension> </CustomAction>

Task 3 – Test the Solution on premise

In this task, you will deploy your solution to your local SharePoint instance and verify that the ribbon button has been created and that a new List Settings button is visible.

Press F5 to run the solution against your local SharePoint 2010 instance.

1. Select the Products list from the Quick Launch.
2. Select Items from the ribbon.

3. Select the List Settings button.

4. Verify that it takes you to the lists’ settings page.

Task 4 – Deploy the Solution to SharePoint Online

In this task, you will deploy the solution package to SharePoint Online to confirm that it works as expected.

1. In the Solution Explorer window, right-click on the CustomActions_EventReceivers project and select Package to package the project.
2. Navigate to your SharePoint Online site, e.g., https://contoso.sharepoint.com.

3. Click Site Actions and then select Site Settings.

4. Click the Solutions link in the Galleries section to view the site collection’s solution gallery.

5. Click on the Solutions tab in the ribbon and click the Upload Solution button.

6. Browse to the solution package at C:\ %Office365TrainingKit%\Labs\2.3\Source\Before\CustomActions_EventReceivers\bin\Debug\CustomActions_EventReceivers.wsp and click Open.
7. In the Solution Gallery – Activate Solution, click the Activate button.
8. Browse to the Lab02 sub site.
9. Click Site Actions >> Site Settings and choose Manage Site Features.
10. Click the Activate button next to the CustomActions_EventReceivers Feature1 feature to activate the feature and populate the Products list instance to the Lab02 sub site.

11. Verify that the Products list appears in the Quick Launch and that the List Settings button is visible.