Adding an E-mail button to a Custom List Item

Posted by & filed under , .

Problem:

The client wants a way to send a link to a specific item in a list. For this example, say we have a Custom List for storing book information:

At the List level, we have a method for sending a link via e-mail:

However, as stated in the tooltip, this simply provides a link to the list itself:

What we want is a link to the specific item. Examining the Item tab in the ribbon shows that there exists no such method already:

Similarly when viewing an individual item

The only way to get the link of an individual item out of the box is to copy the shortcut directly from the list item:

Solution:

To solve this problem, we’re going to use a combination of SharePoint Designer, and some jQuery magic. (Warning, in order to get the jQuery script to run in the Display Item dialog, you’ll either need to edit the system.master page (or change the system master page to a custom master page), or create a new display form for your list. If you’re uncomfortable or unable to make these changes, this method won’t work)

First, we open SharePoint Designer and add an icon for the new button we’re going to create in the ribbon, here’s the image I used (I just add it to the style library):

Then we find the List we’re modifying:

After opening the Settings page for the List, we scroll to the lower-right corner to locate the Custom Actions section:

Note: It’s important not to use the New button located on the Custom Actions control, since this automatically creates a List Item Menu action, which isn’t what we’re using. Instead, we click inside the Custom Actions control, and then go all the way up to the Ribbon and select the Custom Action drop down, then select Display Form Ribbon:

Name it something unique (that is, don’t name it the same as something that already shows up in the ribbon) since we’ll be using this to target the item with jQuery later. I chose to name mine “Email Item“:

Then set the icon URL to the image you uploaded earlier, and set the Ribbon Location for your new item. I typically just use Ribbon.ListForm.Display.Actions.Controls._children which sets it to appear in the second group, which already contains the Alert button.

We can ignore the “type of action” section, since we are unable to get the functionality we’re after from the OOB stuff. (We’ll fix it later with jQuery)

After we save the custom action, we can view it by clicking any item in our list and checking the Actions group in the ribbon:

Currently, clicking the button simply sends us to the same URL we’re already at, which is clearly not the desired functionality. To get the desired functionality, we’ll need to get this jQuery running on the page somehow:

Let’s break that down for a second.

  1. First we find an item with the title attribute “Email Item” (this works because SharePoint sets the title attribute to match the Title we used when creating the item)
  2. The next several lines are the secret sauce that make the whole thing work, we grab the ID of the button item, and then create a new child element with that ID, then strip off the ID and onclick events from the button. This is necessary, because SharePoint expects an element with this ID to exist on the page, and will throw a JavaScript error if it doesn’t find it.
  3. Finally, we add the actual functionality that we want from this button. In this case, we’re doing a simple mailto href, but it would be easy to set this button to run a JavaScript method of your choosing, and you could have this button do all sorts of things.

There are a few options for getting this code onto the page:

  • Modify the system.master page to add the code there
    • This will cause this script to load on every page of the site… it likely won’t cause issues, but it’s usually a good idea to leave the OOB master pages alone. If you’ve already got a customized master page, you could certainly add this code there (although you might consider writing some checks to make sure it only runs on the page you want it to)
  • Add the code directly to the display page
    • This involves “customizing” the page, which breaks it from the site definition. This can cause issues down the line with upgrades (although to be honest, upgrading to the next version of SharePoint will likely break the code anyway, since it’s not guaranteed to have the same ribbon DOM)
  • Create a new master page (copy system.master) and add the code to this master page
    • This is a reasonable option, except that in order to use this new master page, you either have to set it as the system master page site-wide, or modify the display page directly to change the master page it’s using. This is a good option if you have other customizations you’d like to do, either to the whole site (set as the system master page), or just this form (edit display page to use this master page). If you’re only adding the code to the display item page, this is a little overkill.

The cleanest solution would be the third option, especially if you’ve already got a customized system master page in place. This should be fairly self explanatory, you simply take the code above and insert it into a script block (below the jQuery call) in your system masterpage. The second option is quicker, and if you’re only adding this ability to a single list, might be the way to go.