The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

This topic has not yet been rated - Rate this topic

How to: Create custom actions to deploy with apps for SharePoint

apps for SharePoint

Published: July 16, 2012

How to

Learn how to create a custom action in SharePoint 2013 that deploys to the host web when you deploy an app for SharePoint.

Applies to: apps for SharePoint | Office 365 | SharePoint Foundation 2013 | SharePoint Server 2013

In this article
Prerequisites for using the examples in this article
Code example: Create a custom action in the host web document libraries
Next steps
Additional resources

When you are creating an app for SharePoint, custom actions let you interact with the lists and the ribbon in the host web. A custom action deploys to the host web when end users install your app. Custom actions can open a remote webpage and pass information through the query string. There are two types of custom actions available for apps: Ribbon and Menu Item custom actions.

Prerequisites for using the examples in this article

To follow the steps in this example, you need the following:

Visual Studio 2012
SharePoint development tools in Visual Studio 2012
A SharePoint 2013 development environment (app isolation required for on-premises scenarios)

For guidance on how to set up a development environment that fits your needs, see Start building apps for Office and SharePoint.

Core concepts to help you understand custom actions

The following table lists useful articles that can help you understand the concepts and steps that are involved in a custom action scenario.

Table 1. Core concepts for custom actions

Article	Description
Apps for SharePoint overview	Learn about the new app model in SharePoint 2013 that enables you to create apps, which are small, easy-to-use solutions for end users.
UX design for apps in SharePoint 2013	Learn about the user experience (UX) options that you have when you are building apps for SharePoint.
Host webs, app webs, and SharePoint components in SharePoint 2013	Learn about the difference between host webs and app webs. Find out which SharePoint 2013 components can be included in an app for SharePoint, which components are deployed to the host web, which components are deployed to the app web, and how the app web is deployed in an isolated domain.

Code example: Create a custom action in the host web document libraries

Follow these steps to create a custom action in the host web document libraries:

Create the app for SharePoint and remote web projects.
Add a custom action feature to the app for SharePoint project.
Add an app webpage to the web project.

Figure 1 shows a document library that has custom actions.

Figure 1. A document library with custom actions

To create the app for SharePoint and remote web projects

Open Visual Studio 2012 as administrator (Right-click the Visual Studio 2012 icon in the Start menu, and choose Run as administrator).
Create a new project using the App for SharePoint 2013 template.
Figure 2 shows the location of the App for SharePoint 2013 template in Visual Studio 2012, under Templates, Visual C#, Office SharePoint, Apps.
Figure 2. App for SharePoint 2013 Visual Studio template
Provide the URL of the SharePoint website that you want to use for debugging.
Select Autohosted or Provider-hosted as the hosting option for your app.
After the wizard finishes, you should have a structure in Solution Explorer that resembles Figure 3.
Figure 3. App for SharePoint projects in Solution Explorer

To add an app webpage for the custom actions

Right-click the web project, and add a new Web Form. Rename the Web Form to CustomActionTarget.

Copy the following markup and paste it in the ASPX page. The markup performs the following tasks:

Provides a placeholder for the query string parameters.
Extracts the parameters from the query string.
Renders the parameters in the placeholder.

JavaScript

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Custom action target</title>
</head>
<body>
    <h2>Query string parameters passed by the custom action:</h2>

    <!-- Placeholder for query string parameters -->
    <ul id="qsparams"/>

    <!-- Main JavaScript function, renders
         the query string parameters -->
    <script lang="javascript">
        var params = document.URL.split("?")[1].split("&");
        var paramsHTML = "";

        // Extracts the parameters from the query string.
        // Parameters are URLencoded, decode for rendering
        //   in page.
        for (var i = 0; i < params.length; i = i + 1) {
            params[i] = decodeURIComponent(params[i]);
            paramsHTML += "<li>" + params[i] + "</li>";
        }

        // Render parameters in the placeholder.
        document.getElementById("qsparams").innerHTML =
            paramsHTML;
    </script>
</body>
</html>

To add a menu item custom action feature to the app for SharePoint project

Right-click the app for SharePoint project, and add a new Menu Item Custom Action item.

Set the following properties for the custom action.

Table 2. Menu Item custom action properties

Property question	Answer
Where do you want to expose the custom action?	Choose Host Web.
Where is the custom action scoped to?	Choose List Template.
Which particular item is the custom action scoped to?	Choose Document Library.
What is the text on the menu item?	Type Invoke custom action.
Where does the custom action navigate to?	Choose the CustomActionTarget page. Append the following query string parameters to the URL: ?HostUrl={HostUrl}&Source={Source}&ListURLDir={ListUrlDir}&ListID={ListId}&ItemURL={ItemUrl}&ItemID={ItemId}

Visual Studio generates the following markup in the elements.xml file of the menu item custom action feature:

XML

<?xml version="1.0" encoding="utf-8"?>
<Elements 
    xmlns="http://schemas.microsoft.com/sharepoint/">
    <!-- RegistrationId attribute is the list type id,
        in this case, a document library (id=101). -->
  <CustomAction 
      Id="65695319-4784-478e-8dcd-4e541cb1d682.CustomAction"
      RegistrationType="List"
      RegistrationId="101"
      Location="EditControlBlock"
      Sequence="10001"
      Title="Invoke custom action">
    <!-- 
    Update the Url below to the page you want the custom action to use.
    Start the URL with the token ~remoteAppUrl if the page is in the
    associated web project, use ~appWebUrl if page is in the app project.
    -->
    <UrlAction Url=
"~remoteAppUrl/CustomActionTarget.aspx?HostUrl={HostUrl}&amp;Source={Source}&amp;ListURLDir={ListUrlDir}&amp;ListID={ListId}&amp;ItemURL={ItemUrl}&amp;ItemID={ItemId}" />
  </CustomAction>
</Elements>

You can also open the remote webpage in a dialog box by using the HostWebDialog attribute. For more information, see SharePoint 2013: The bookstore, a custom actions and cross-domain library sample.

(Optional) To add a Ribbon custom action feature to the app for SharePoint project

Right-click the app for SharePoint project, and add a new Ribbon Custom Action item.

Set the following properties for the custom action

Table 3. Ribbon custom action properties

Property question	Answer
Where do you want to expose the custom action?	Choose Host Web.
Where is the custom action scoped to?	Choose List Template.
Which particular item is the custom action scoped to?	Choose Document Library.
Where is the control located?	Choose Ribbon.Documents.Manage.
What is the text on the menu item?	Type Invoke custom action.
Where does the custom action navigate to?	Choose the CustomActionTarget page. Append the following query string parameters to the URL: ?HostUrl={HostUrl}&Source={Source}&ListURLDir={ListUrlDir}&SelectedListID={SelectedListId}&SelectedItemID={SelectedItemId}

Visual Studio generates the following markup in the elements.xml file of the Ribbon custom action feature:

XML

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <!-- Adds a Ribbon custom action to a list in the host web site. -->
  <!-- Create a new custom list and add a new item to it -->
  <!-- RegistrationId attribute is the list type id,
        in this case, a document library (id=101). -->
    <CustomAction Id="75dd24d9-0c16-4ef5-be0a-f52ed0e620fa.CustomAction"
                RegistrationType="List"
                RegistrationId="101"
                Location="CommandUI.Ribbon"
                Sequence="10001"
                Title="Invoke custom action">
    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition Location="Ribbon.Documents.Manage.Controls._children">
          <Button
              Id="Ribbon.Library.Connect.PropertyViewer"
              Alt="Invoke custom action"
              Sequence="115"
              Command="Invoke_CustomAction"
              LabelText="Invoke custom action"
              TemplateAlias="o1"
              Image32by32="_layouts/15/images/placeholder32x32.png"
              Image16by16="_layouts/15/images/placeholder16x16.png" />
        </CommandUIDefinition>
      </CommandUIDefinitions>
      <CommandUIHandlers>
        <CommandUIHandler
            Command="Invoke_CustomAction"
            CommandAction="~remoteAppUrl/CustomActionTarget.aspx?HostUrl={HostUrl}&amp;Source={Source}&amp;ListURLDir={ListUrlDir}&amp;SelectedListID={SelectedListId}&amp;SelectedItemID={SelectedItemId}"/>
      </CommandUIHandlers>
    </CommandUIExtension>
  </CustomAction>
</Elements>
<?xml version="1.0" encoding="utf-8"?>
<Elements 
    xmlns="http://schemas.microsoft.com/sharepoint/">
    <!-- RegistrationId attribute is the list type id,
        in this case, a document library (id=101). -->
  <CustomAction 
      Id="65695319-4784-478e-8dcd-4e541cb1d682.CustomAction"
      RegistrationType="List"
      RegistrationId="101"
      Location="EditControlBlock"
      Sequence="10001"
      Title="Invoke custom action">
    <!-- 
    Update the Url below to the page you want the custom action to use.
    Start the URL with the token ~remoteAppUrl if the page is in the
    associated web project, use ~appWebUrl if page is in the app project.
    -->
    <UrlAction Url=
"~remoteAppUrl/CustomActionTarget.aspx?HostUrl={HostUrl}&amp;Source={Source}&amp;ListURLDir={ListUrlDir}&amp;ListID={ListId}&amp;ItemURL={ItemUrl}&amp;ItemID={ItemId}" />
  </CustomAction>
</Elements>

Note
Ribbon custom actions use SelectedListId and SelectedItemId. ListId and ItemId work only with menu item custom actions.

To build and run the solution

Make sure that the app for SharePoint project is set as the startup project.
Press the F5 key.
Note
When you press F5, Visual Studio builds the solution, deploys the app, and opens the permissions page for the app.
Choose the Trust It button.
Go to any document library in the host web.
Choose Invoke custom action in the context menu.
Figure 4 shows a remote webpage with parameters from the custom action.
Figure 4. Remote webpage with parameters from the custom action

Note
When you press F5, Visual Studio builds the solution, deploys the app, and opens the permissions page for the app.

Table 4. Troubleshooting the solution

Problem	Solution
Visual Studio does not open the browser after you press the F5 key.	Set the app for SharePoint project as the startup project.
The tokens in the URL are not resolved after you press the F5 key in Visual Studio.	Go to the Site Contents page in the host web, and click the icon for your app.

Next steps

This article demonstrated how to create a custom action in an app for SharePoint. As a next step, you can learn about other UX components that are available for apps for SharePoint. To learn more, see the following:

Additional resources

Change history

Date	Description
July 16, 2012	Initial publication

Did you find this helpful? Yes No

Not accurate

Not enough depth

Need more code examples

(1500 characters remaining)

How to: Create custom actions to deploy with apps for SharePoint

Core concepts to help you understand custom actions

To create the app for SharePoint and remote web projects

To add an app webpage for the custom actions

To add a menu item custom action feature to the app for SharePoint project

(Optional) To add a Ribbon custom action feature to the app for SharePoint project

To build and run the solution

Community Additions

SharePoint 2013

Code Samples

Training

Connect

Dev Centers

Information for