Sharepoint 2013 : Understanding SharePoint app model architecture (part 7) - Working with app user-interface entry points - Building UI custom actions

Building UI custom actions

A UI custom action is a developer extension in the SharePoint app model with which you can add custom commands to the host site. The command for a UI custom action is surfaced in the user interface of the host site by using either a button on the ribbon or a menu command in the menu associated with items in a list or documents in a document library that is known as the Edit Control Block (ECB) menu. It is the act of installing an app with UI custom actions that automatically extends the user interface of the host site with ribbon buttons and ECB menu commands.

As in the case of the client web part, UI custom actions are supported in each of the three app hosting models. However, a UI custom action is different than the client web part because its purpose is not to display content in the host web. Instead, it provides an executable command for business users with which they can display a page supplied by the app. The page that is referenced by a UI custom action can be in either the app web or the remote web.

As a developer, you have control over what is passed in the query string for a UI custom action. This makes it possible to pass contextual information about the item or the document on which the command was executed. This in turn makes it possible for code inside the app to discover information such as the URL that can be used to access the item or document by using either the Client-Side Object Model (CSOM) or the new Representational State Transfer (REST) API.

In the dialog box shown earlier in Figure 6, you can see that Visual Studio 2012 provides a project item template named UI Custom Action. When you use this item template to create a new UI custom action, Visual Studio 2012 adds a new elements.xml file to your SharePoint app project. When you look inside the elements.xml file you find a <CustomAction> element that you can modify to define either an ECB menu item or a button on the ribbon.

Many SharePoint developers already have experience working with custom actions in SharePoint 2007 and SharePoint 2010. The good news is that the manner in which you edit the XML within the <CustomAction> element for a SharePoint app project works the same way as it does for a SharePoint solution project. The bad news is that many of the custom actions available when developing farm solutions are not available when developing a SharePoint app.

In particular, a SharePoint app only allows for UI custom actions that create ECB menu commands and ribbon buttons. The SharePoint app model imposes this restriction to provide a balance between functionality and security concerns. Furthermore, you are prohibited from adding any custom JavaScript code when you configure the URL for a UI custom action in a SharePoint app. If this restriction were not enforced, JavaScript code from the app could call into the host site without being granted the proper permissions.

Suppose that you want to create a UI custom action to add a custom ECB menu item to all the items in every Contacts list within the host site. You can structure the <CustomAction> element to look like that presented in Example 3.

<CustomAction
  Id="CustomAction1"
  RegistrationType="List"
  RegistrationId="105"
  Location="EditControlBlock"
  Sequence="100"
  Title="Send Contact To App">

    <UrlAction Url="~appWebUrl/Pages/Action1.aspx" />

</CustomAction>

Once you install an app with this UI custom action, it registers an ECB menu command for every item in lists that have a list type ID of 105. This is the ID for the Contacts list type. Once the app is installed, the host web will provide a custom menu item on the ECB menu for each item in any Contacts list. An example of what the ECM menu command looks like is shown in Figure 8.

Figure 8. A custom UI action is used to add an item to the edit-control block or ribbon.

The default action of a UI custom action is to redirect the user to the page referenced by the URL configured within the <UrlAction> element. This makes sense for a scenario in which you want to move the user from the host web into the full immersion experience of the app in order to do some work. However, this default behavior will provide a distracting user interface experience for a scenario in which a user wishes to return to the host web immediately after seeing the page displayed by the app. For these scenarios, you can modify the UI custom action to display the page from the app as a dialog box in the context of the host web. The user interface experience is much better because the user can see a page from the app without ever leaving the host web.

Example 4 demonstrates the technique to display the page referenced by a UI custom action as a dialog box, which involves adding three attributes to the <CustomAction> element. First, you add the HostWebDialog attribute and assign it a value of true. Next, you add the HostWebDialogWidth attribute and the HostWebDialogHeight attribute and assign them values to set the width and height of the dialog box.

<CustomAction
  Id="CustomAction1"
  RegistrationType="List"
  RegistrationId="105"
  Location="EditControlBlock"
  Sequence="100"
  Title="Display more information about this contact"
  HostWebDialog="TRUE"
  HostWebDialogWidth="480"
  HostWebDialogHeight="240" >

    <UrlAction Url="~appWebUrl/Pages/Action1.aspx" />

  </CustomAction>
</Elements>

Now, let’s go into more detail about configuring the Url attribute of the <UrlAction> element. When you configure the URL you can use the same familiar tokens that you use with the start page and with client web parts such as ~appWebUrl, ~remoteAppUrl, and {StandardTokens}, as shown in the following code:

<UrlAction Url="~appWebUrl/Pages/Action1.aspx" />

However, UI custom actions support several additional tokens beyond what is available for start pages and client web parts. These are the tokens that make it possible to pass contextual information about the item or document on which the command was executed. For example, you can pass the site-relative URL to the item or document by using the {ItemURL} token.

<UrlAction Url="~appWebUrl/Pages/Action1.aspx?ItemUrl={ItemURL}" />

In most scenarios, you will also need the absolute URL to the root of the host web, which can be passed by using the {HostUrl} token. Note that the Url is configured by using an XML attribute, so you cannot use the “&” character when combining two or more parameters together. Instead, you must use the XML encoded value, which is &amp, as shown in the following example:

<UrlAction Url="~appWebUrl/Pages/Action1.aspx?HostUrl={HostUrl}&amp;ItemURL={ItemUrl}" />

Note that the SharePoint host environment substitutes values into these tokens by using standard URL encoding. This means that you must write code in the app to use a URL decoding technique before you can use these values to construct a URL that can be used to access the item or document.

Table 2 lists the tokens that can be used in UI custom actions, beyond those that are also supported in start pages and client web parts. Note that some of the tokens work equally well regardless of whether the UI custom action is used to create an ECB menu item or a button in the ribbon. However, the {ListID} token and the {ItemID} token work with ECB menu items but not with buttons on the ribbon. Conversely, the {SelectedListId} token and the {SelectedItemId} token work with buttons on the ribbon but not with ECB menu items.