Creating custom SharePoint 2010 ribbon actions

If you saw my post on a set of custom ribbon items I created, you’ll know that custom ribbon actions in SharePoint 2010 can be a very powerful tool. In this post I’ll go through the basics of what it takes to connect a custom action to a ribbon button using some handy SharePoint custom JavaScript.

I won’t get into how to create a custom ribbon button in this post, Chris O’Brien does a much better job of that than I ever could. Instead I’ll focus on how to create actions for your custom buttons to perform when clicked.

For this post I’m going to use a button I created in the solution mentioned above. It’s a simple action that inserts a pre-formatted email “mailto:” link into a rich text field.

The Wireup

In the Elements.xml file that creates the Email Link button, we specify a command that should run when the button is clicked:

Later in the same file, we specify the action that command will perform:

As you can see, it’s calling a custom JavaScript function, InsertEmailLink(). We insure that custom function will be available by using the same file to require the JS file that contains it be loaded:

Note that the ScriptSrc attribute is always assumed to be relative to the mapped /_layouts/ directory.

The Action

Most of these actions work by calling up a dialog box to accept user input, and then formatting that input and inserting it into the content. This breaks down into a three step process:

  1. The JavaScript function that opens the dialog box
  2. The .aspx file used in the dialog box
  3. The JavaScript function that runs after the dialog box closes

Opening the Dialog

In the case of the Email Links button, the first step is the InsertEmailLink() mentioned earlier. That function is as follows:

The most important lines in this function are lines 8 and 9. On line 8, we specify the path to the .aspx file we’ll use for the dialog box, and on line 9 we specify the JavaScript function that will run when we close the dialog box (in this case it’s EmailLinkCloseCallback()).

If you want to pass more complicated data to the dialog box, you’ll want to use the args property on your SPDialogOptions object. The args property will be available to JavaScript running in your dialog box as window.frameElement.dialogArgs. You can pass any type of variable, object, or array as the args property.

Inside the Dialog

In most cases, the dialog popup will be a simple form with a few input elements. In this case it’s just two text boxes, one for the display text of the link, and one for the email address to send to. After the text boxes we have two buttons, OK and Cancel.

email-dialog

On page load we run a simple function to insert any selected text passed in the args property to the display text input field:

If the Cancel button is clicked, we call the function to close the dialog and pass two ‘cancel’ arguments that will be passed on to the callback function:

If the OK button is clicked, we get the value of the two text boxes, assign them as properties on an object, and call the function to close the dialog box, passing it a success object as well as the object we created:

Dialog Close Callback

Once the dialog box closes, the callback function we specified earlier will be called. In that function, the first thing we need to do is make sure the dialog was closed with a result of “OK” and not “Cancel”. Once we know that, we can get our email address and display text out of the object we passed from the dialog.

Then we use the SharePoint’s RTE object to determine where the cursor is in the RTE field so we can insert our content there. Then we build the link element using the user provided data, and insert it appropriately.

And that’s it! Pretty much every content editing ribbon action I’ve built follows this basic formula, which can handle just about anything. And if you need to do some server-side work from your ribbon action, it’s as simple as setting up code-behind on your .aspx dialog page.

Tagged with: ,
Posted in HTML & CSS, JavaScript, SharePoint, SharePoint Frontend

Leave a Reply

Your email address will not be published. Required fields are marked *

*