Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

Create custom actions to deploy with SharePoint Add-ins

SharePoint Add-ins

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

Last modified: June 09, 2015

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

Note Note

The name "apps for SharePoint" is changing to "SharePoint Add-ins". During the transition, the documentation and the UI of some SharePoint products and Visual Studio tools might still use the term "apps for SharePoint". For details, see New name for apps for Office and SharePoint.

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.

You need a development environment as explained in Get started creating provider-hosted SharePoint Add-ins.

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

SharePoint Add-ins

Learn about the new app model in SharePoint that enables you to create apps, which are small, easy-to-use solutions for end users.

UX design for SharePoint Add-ins

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 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.

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

  1. Create the app for SharePoint and remote web projects.

  2. Add a custom action feature to the app for SharePoint project.

  3. Add an app webpage to the web project.

To create the app for SharePoint and remote web projects

  1. Open Visual Studio as administrator. (To do this, right-click the Visual Studio icon on the Start menu, and choose Run as administrator.)

  2. Create the provider-hosted app for SharePoint as explained in Get started creating provider-hosted SharePoint Add-ins and name it CustomActionsApp.

To add an app webpage for the custom actions

  1. After the Visual Studio solution has been created, right-click the web application project (not the app for SharePoint project) and add a new Web Form by choosing Add > New Item > Web > Web Form. Name the form CustomActionTarget.aspx.

  2. In the CustomActionTarget.aspx file, replace the entire html element and it's children with the following HTML code. Leave all the markup above the html element as it is. The HTML code contains JavaScript that 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.

    Important note Important

    The ItemURL and ItemID tokens only get passed when there is an item selected. In a production quality app for SharePoint, your code needs to handle situations where no item is selected. In this example the code alerts the user that no item has been selected. 

    <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>";
            }
    
             // Alert the user when no item has been selected.
             // (The SPListItemId is the 5th parameter.)
             if (params[5] === undefined) {
                paramsHTML += "<div> <h3> No item has been selected from the list.  Please select an item. </h3> </div> ";
             }
    
            // Render parameters in the placeholder.
            document.getElementById("qsparams").innerHTML =
                paramsHTML;
        </script>
    </body>
    </html>
    

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

  1. Right-click the app for SharePoint project, and choose Add > New Item > Office/SharePoint > Menu Item Custom Action.

  2. Keep the default name and choose Add.

  3. The Create Custom Action for Menu Item wizard asks you a series of questions. Give the answers from the following table:

    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 My Custom Action.

    Where does the custom action navigate to?

    Choose the CustomActionAppWeb\CustomActionTarget.aspx page.

  4. Choose Finish.

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

    <?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?{StandardTokens}&amp;SPListItemId={ItemId}&amp;SPListId={ListId}" />
      </CustomAction>
    </Elements>
    
    
  5. Add the following query parameters to the end of the Url attribute of the UrlAction element:

    &amp;SPSource={Source}&amp;SPListURLDir={ListUrlDir}&amp;SPItemURL={ItemUrl}

    The UrlAction element should look like the following:

    <UrlAction Url= "~remoteAppUrl/CustomActionTarget.aspx?{StandardTokens}&amp;SPListItemId={ItemId}&amp;SPListId={ListId}&amp;SPSource={Source}&amp;SPListURLDir={ListUrlDir}&amp;SPItemURL={ItemUrl}" />

Note Note

In this example, the remote web page opens in a full window when the user selects the custom action from the menu. Custom menu actions can also open a 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.

To add a Ribbon custom action to the app for SharePoint project

  1. Right-click the app for SharePoint project, and choose Add > New Item > Office/SharePoint > Ribbon Custom Action.

  2. Keep the default name and choose Add.

  3. The Create Custom Action for Ribbon wizard asks you a series of questions. Give the answers from the following table:

    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 My Custom Ribbon Button.

    Where does the custom action navigate to?

    Choose the CustomActionAppWeb\CustomActionTarget.aspx page.

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

    <?xml version="1.0" encoding="utf-8"?>
    <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
      <CustomAction Id="85691508-c076-4f43-93d4-96b4d5253a09.RibbonCustomAction1"
                    RegistrationType="List"
                    RegistrationId="101"
                    Location="CommandUI.Ribbon"
                    Sequence="10001"
                    Title="Invoke &apos;RibbonCustomAction1&apos; action">
        <CommandUIExtension>
          <!-- 
          Update the UI definitions below with the controls and the command actions
          that you want to enable for the custom action.
          -->
          <CommandUIDefinitions>
            <CommandUIDefinition Location="Ribbon.Documents.Manage.Controls._children">
              <Button Id="Ribbon.Documents.Manage.RibbonCustomAction1Button"
                      Alt="My Custom Ribbon Button"
                      Sequence="100"
                      Command="Invoke_RibbonCustomAction1ButtonRequest"
                      LabelText="My Custom Ribbon Button"
                      TemplateAlias="o1"
                      Image32by32="_layouts/15/images/placeholder32x32.png"
                      Image16by16="_layouts/15/images/placeholder16x16.png" />
            </CommandUIDefinition>
          </CommandUIDefinitions>
          <CommandUIHandlers>
            <CommandUIHandler Command="Invoke_RibbonCustomAction1ButtonRequest"
                              CommandAction="~remoteAppUrl/CustomActionTarget.aspx?{StandardTokens}&amp;SPListItemId={SelectedItemId}&amp;SPListId={SelectedListId}"/>
          </CommandUIHandlers>
        </CommandUIExtension >
      </CustomAction>
    </Elements> 
    
    
  5. Add the following query parameters to the end of the CommandAction attribute of the CommandUIHandler element:

    &amp;SPSource={Source}&amp;SPListURLDir={ListUrlDir}

    The CommandUIHandler element should look like the following:

    <CommandUIHandler Command="Invoke_RibbonCustomAction1ButtonRequest" CommandAction="~remoteAppUrl/CustomActionTarget.aspx?{StandardTokens}&amp;SPListItemId={SelectedItemId}&amp;SPListId={SelectedListId}&amp;SPSource={Source}&amp;SPListURLDir={ListUrlDir}" />

    Note Note

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

Set the app start page to the host web home page

  1. The continuing sample app for SharePoint doesn't have any app web and its remote web application exists only to host the form. So the start page of the app should be set to the home page of the host web.

    To begin, select the app for SharePoint project (not the web application project) in Solution Explorer and copy the value of the Site URL property, including the protocol (for example https://contoso.sharepoint.com) into the clipboard.

  2. Open the app manifest, and then paste the URL into the Start Page box.

  3. Optionally, you can delete the Default.aspx page from the web application project, because it is not used in the app for SharePoint.

To build and run the solution

  1. Press the F5 key.

    Note Note

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

  2. Choose the Trust It button. The default page of your developer site opens.

  3. Navigate to any document library in the host web.

    Launching a custom menu action

    Document library with callout for a document open, the menu that that the callout button on the callout opens, and the Advanced menu open.
  4. Choose the callout button (...) for any document. The callout opens.

  5. Choose the callout button (...) on the callout.

  6. Choose Advanced.

  7. Choose My Custom Menu Action in the context menu. You should see something like the following on the remote webpage that opens:

    Remote webpage with parameters from the custom action

    Web page with parameters from a custom action
  8. Click the Back button on your browser to return to the library.

    Launching a custom ribbon action

    A document library with a document selected, the File tab open on the ribbon, and the custom button on the ribbon.
  9. Select any document.

  10. Open the File tab on the ribbon.

  11. Choose My Custom Ribbon Button. You see the same remote web page.

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.

Show:
© 2015 Microsoft