Adding a Custom Action to a Display Form for List Items

  • Article

Summary: This article discusses how to add a ribbon button to the display form and link it to a custom action in Microsoft SharePoint 2010.

Applies to: Business Connectivity Services | Open XML | SharePoint Designer 2010 | SharePoint Foundation 2010 | SharePoint Online | SharePoint Server 2010 | Visual Studio

Provided by:   Medha Jagtap, Microsoft Corporation

Contents

  • Creating Custom Actions Overview

  • Custom Action Elements

  • Creating a Custom Action by Using a Feature

  • Creating a Custom Action by Using SharePoint Designer

  • Conclusion

  • Additional Resources

Creating Custom Actions Overview

It is common when customizing SharePoint 2010 to want to extend the user interface. Fortunately, this is easy to do by using the ribbon menu. You can add new functionality to the SharePoint 2010 ribbon as custom actions. Custom actions enable you to expand or extend the standard behavior of SharePoint 2010 core components such as using a custom action to email the details of a list item.

This topic describes two approaches for adding a custom action to a display form of SharePoint 2010 list items. The custom action is added to the ribbon as a button.

You have two options to add custom actions to a display form:

  • Adding a custom action through SharePoint 2010 features. SharePoint features enable you to easily deploy customizations. This is the preferred method when you need to package the customizations and deploy them to different servers.

  • Adding a custom action by using Microsoft SharePoint Designer 2010. SharePoint Designer helps create rapid, no-code customizations on the local server.

Custom Action Elements

Custom actions are implemented by using the following elements.

The CustomAction element

The CustomAction element defines the extension to the user interface and specifies the following attributes:

  • Description: Description of the custom action.

  • Title: The title of the custom action.

  • ID: Custom action unique identifier.

  • Location: Specifies the location of the custom action. For example, CommandUI.Ribbon.DisplayForm will show this custom action on the display form of an item.

  • RegistrationId: Specifies the identifier of the list or item content type that this action is associated with. For example, a value of 100 indicates that you are attaching this custom action to a Custom List type.

  • Sequence: Specifies the ordering priority for actions. A value is 0 indicates that the button will appear at the first position on the ribbon.

  • Rights: Specifies a set of rights that the user must have for the link to be visible. For example, ViewListItems indicates that a person with View List Items permission can access this custom action. If not specified, then the action always appears in the list of actions.

The following listing demonstrates the use of the CustomAction element.

<CustomAction 
Description="Search Title on Bing" 
Title="Bing It!" 
Id="{E538E8C7-65DA-454E-AD87-4A603B6CC569}" 
Location="CommandUI.Ribbon.DisplayForm" 
RegistrationId="100" 
RegistrationType="List" 
Sequence="0" 
Rights="ViewListItems" 
xmlns="https://schemas.microsoft.com/sharepoint/">

The CommandUIExtension element

The CommandUIExtension element contains elements that extend the user interface.

The CommandUIDefinition element

The CommandUIDefinition element contains elements that define a user interface such as a button and specifies the following attribute:

  • Location: Specifies the location of this command. In this topic, this attribute is set to Ribbon.ListForm.Display.Manage.Controls._children which is an existing group on the display form.

The Button element

The Button element defines a push button control and specifies the following attributes:

  • Id: Unique identifier of the control.

  • Command: The name of the command to execute when the control is clicked. This Id should match the CommandUIHandler elements Command attribute.

  • Image32by32: 32 by 32 pixels image displayed on ribbon.

  • Image16by16: 16 by 16 pixel image displayed on the ribbon.

  • Sequence: Position of the control in the current group. A value of 0 indicates that this button will be the first button available in current group.

  • LabelText: The text to be shown on the control. The button in this topic will contain display Bing It!.

  • Description: The tooltip shown when the mouse hovers over the control.

  • TemplateAlias: A value that indicates the image to be used for the control. The value o1 indicates use of Image32by32 whereas o2 indicates use of Image16by16.

The following listing demonstrates the use of the Button element.

<CommandUIDefinition Location="Ribbon.ListForm.Display.Manage.Controls._children"> 
<Button Id="{B511A716-54FF-4EAE-9CBE-EA02B51B626E}" 
Command="{4E2F5DC0-FE2C-4466-BB2D-3ED0D1917763}" 
Image32by32="~site/_layouts/Images/BingSearch/bing32.png" 
Image16by16="~site/_layouts/Images/BingSearch/bing16.png" 
Sequence="0" 
LabelText="Bing It!" 
Description="Search Title on Bing" 
TemplateAlias="o1" /> 
</CommandUIDefinition>

The CommandUIHandler element

The CommandUIHandler element describes the action to be taken when user clicks the control and specifies the following attributes:

  • Command: The name of a command. The value of this attribute matches the value of a Command attribute on an element that defines a control; the button in this example.

  • CommandAction: A script statement to execute when this handler is invoked. The example in this topic posts the current item’s title to the Bing search engine. The command action can be a call to a JavaScript function residing inside an external JavaScript file that is referenced from the function code.

The following listing demonstrates the use of the CommandUIHandler element.

<CommandUIHandler Command="{4E2F5DC0-FE2C-4466-BB2D-3ED0D1917763}" CommandAction="javascript:window.open('https://www.bing.com/search?q='.concat(escape(document.title)))" />

Creating a Custom Action by Using a Feature

The following steps create a custom action in Visual Studio 2010. The procedures in this section assume a development environment where SharePoint 2010 is installed and configured, Microsoft Visual Studio 2010 is installed and the currently logged-in user has administrative rights on the SharePoint environment for deployment purposes.

To Create a Custom Action by Using a Feature

  1. In Visual Studio 2010, click New Project, expand the SharePoint node, click 2010, and then click Empty SharePoint Project. Name the project BingSearchAction and then click OK.

  2. In the SharePoint Customization Wizard, select the local SharePoint site that can be used for debugging and whether the solution will be deployed as a sandboxed or farm solution as shown in Figure 1. Click Finish.

    Figure 1. Specify the deployment method

    Specify the deployment method

  3. In Solution Explorer, right-click the Features node and then click Add Feature as shown in Figure 2.

    Figure 2. Add new feature

    Add new feature

  4. Name the feature BingSearchButton and add a description as shown in Figure 3.

    Figure 3. Name the feature

    Name the feature

  5. In Solution Explorer, right-click the BingSearchAction project, select Add, and then select New Item as shown in Figure 4.

    Figure 4. Add a new item to the project

    Add a new item to the project

  6. In the Add New Item dialog box, select the Empty Element template, type BingSearchButtonElement as the name, and then click Add as shown in Figure 5.

    Figure 5. Add an element to the project

    Add an element to the project

  7. Open the Elements.xml file inside BingSearchButtonElement and then replace the file content with the following code example.

    <?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
<CustomAction
Description="Search Title on Bing"
Title="Bing It!"
Id="{E538E8C7-65DA-454E-AD87-4A603B6CC569}"
Location="CommandUI.Ribbon.DisplayForm"
RegistrationId="100"
RegistrationType="List"
Sequence="0"
Rights="ViewListItems"
xmlns="https://schemas.microsoft.com/sharepoint/">
<CommandUIExtension xmlns="https://schemas.microsoft.com/sharepoint/">
<!-- Define the (UI) button to be used for this custom action -->
<CommandUIDefinitions>
<CommandUIDefinition Location="Ribbon.ListForm.Display.Manage.Controls._children">
<Button Id="{B511A716-54FF-4EAE-9CBE-EA02B51B626E}"
Command="{4E2F5DC0-FE2C-4466-BB2D-3ED0D1917763}"
Image32by32="~site/_layouts/Images/BingSearch/bing32.png"
Image16by16="~site/_layouts/Images/BingSearch/bing16.png"
Sequence="0"
LabelText="Bing It!"
Description="Search Title on Bing"
TemplateAlias="o1"
/>
</CommandUIDefinition>
</CommandUIDefinitions>
<CommandUIHandlers>
<!-- Define the action expected on the button click -->
<CommandUIHandler Command="{4E2F5DC0-FE2C-4466-BB2D-3ED0D1917763}" CommandAction="javascript:window.open('https://www.bing.com/search?q='.concat(escape(document.title)))" />
</CommandUIHandlers>
</CommandUIExtension>
</CustomAction>
</Elements>

  8. Save the file.

  9. Add the BingSearchButtonElement element to the BingSearchButton feature as shown in Figure 6.

    Figure 6. Add the element the feature

    Add the element the feature

  10. Right click the solution name and then click Deploy as shown in Figure 7. Visual Studio 2010 will build and deploy the solution to the farm.

    Figure 7. Build and deploy the solution

    Build and deploy the solution

  11. Navigate to the local site, add a custom list, and then add an item to test. Click on the title and observe the first action on the ribbon as shown in Figure 8.

    Figure 8. The Bing It! button

    The Bing It! button

  12. Click the button and notice the redirection to the Bing search site as shown in Figure 9.

    Figure 9. The Bing search site

    The Bing search site

Creating a Custom Action by Using SharePoint Designer

The following steps demonstrate adding a custom action by using the SharePoint Designer. Ensure that SharePoint Designer is installed and that the currently logged-in user has administrative rights on the SharePoint 2010 environment.

To Create a Custom Action by Using the SharePoint Designer

  1. Start Microsoft SharePoint Designer 2010.

  2. On the File menu, point to Sites, and then click Open Site.

  3. Type the URL of the local site such as http://intranet.contoso.com and then click Open Site as shown in Figure 10.

    Figure 10. Open the local site

    Open the local site

  4. In the Navigation pane, click the List and Libraries link, and then click the list name to which the custom action is to be added as shown in Figure 11.

    Figure 11. Click the list name where the action will be added

    Click the list name where the action will be added

  5. Click the Custom Action menu in the list settings section in the ribbon and then click Display Form Ribbon as shown in Figure 12.

    Figure 12. Select the Display Form Ribbon option

    Select the Display Form Ribbon option

  6. In the Create Custom Action screen, type a name and description for the custom action.

  7. Type a URL in the Navigate to URL box such as javascript:window.open('https://www.bing.com/search?q='.concat(document.title)) as shown in Figure 13.

    Figure 13. Type a URL to open the search site

    Type a URL to open the search site

  8. Scroll down and type in the URLs for the button images for the 16x16 and 32x32 sizes that will be displayed in the normal and the compressed view of the ribbon. Click OK.

  9. Open the site in the browser, navigate to the list, and then click on any item title. The display form will open. Ensure the new action button in the first tab of the ribbon as shown in Figure 8.

  10. Click the button will redirect you to the Bing search site as shown in Figure 9.

Conclusion

As you have seen in the previous steps, adding a custom action to a control on a display form by using the two techniques is fairly easy. You can now have better idea of which method will work in your own applications.

Additional Resources

Find more information about the topics discussed in this article at the following locations.