Introduction

Drop-down menus in Windows SharePoint Services and SharePoint Portal Server 2003 enable actions that relate to a specific document in a document library to be viewed and invoked. This article shows how these document context menus can be extended to add custom menu items. The document first explains how SharePoint document library context menus work, and then demonstrates how custom menu items can be added.

 

The Business Problem

Windows SharePoint Services (WSS) document libraries provide a location to store and share files and documents. The WSS user interface provides a context sensitive drop-down menu for each item stored in a document library (Figure 1). A common requirement is the ability to customise this menu to add new actions. For example you might wish to add an option to enable a document to be copied or moved to another location or emailed to a colleague.

Figure 1 Document context menu in a SharePoint Document Library

 

The solution and sample code presented in this article shows how a custom menu item can be created that sends an email link to the relevant document to another user.

 

Solution Overview

The WSS document context menu is generated by client-side Javascript. The script to display these menus is located in a file called ows.js in the folder \Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\LAYOUTS\1033 on the SharePoint server. The AddDocLibMenuItems function in ows.js is responsible for generating the drop-down menus. The AddDocLibMenuItems implementation provides a hook through which additional menu items can be added to the context menu. The first few lines of this function read:

 

function AddDocLibMenuItems(m, ctx)

{

  if (typeof(Custom_AddDocLibMenuItems) != “undefined”)

  {

    if (Custom_AddDocLibMenuItems(m, ctx))

    return;

  }

 

  ..etc..

 

This piece of code is checking whether a function called Custom_AddDocLibMenuItems is defined, and if it is then calling it. By implementing this function in a page containing a document library web part, we can extend the context menu, adding our own menu items.

 

The Custom Menu Items Web Part

So, how can we add a custom piece of JavaScript to a SharePoint page? We need to make sure that the technique we use is configurable and flexible, and that we don’t change any of the built-in script or features of SharePoint so that our implementation is not overwritten by any SharePoint upgrades or service packs that may be deployed in the future.

Fortunately SharePoint provides a convenient mechanism for doing this – the Content Editor Web Part. The Content Editor Web Part enables custom HTML and script to be added to a page and delivered to the browser.

 

Adding the Web Part to a Page

In SharePoint, navigate to a page with a document library web part on it, or add one to an existing page.

On the Modify Shared Page menu, point to Add Web Parts and click on Browse.

Drag the Content Editor Web Part from the tool pane onto the page, then click Open Tool Pane link in the web part.

In the Layout section clear the Visible on Page checkbox. This means the web part is not visible to the end-user, but the script we add to the web part is still delivered to the client browser. In the page design view, you can still see the web part, but it is marked as hidden. If you wish you can also change the title of the web part in the Appearance section of the tool pane.

Figure 2 Hidden Web Part in Design View

 

From the tool pane, open the Source Editor and insert the following script:

 

<script language="javascript">

function Custom_AddDocLibMenuItems(m, ctx)

{

  var strDisplayText = "Say Hello World!";

  var strAction = "alert('Hello World')";

  var strImagePath = "";

 

  // Add our new menu item

  CAMOpt(m, strDisplayText, strAction, strImagePath);

 

  // add a separator to the menu

  CAMSep(m);

 

  // false means that the standard menu items should also be rendered

  return false;

}

</script>

 

Click Save in the Source Editor, and then click OK in the tool pane.

Now test the web part by opening a document library drop-down menu on the same page. You should see the new menu item at the top of the menu with a separator bar splitting it from the rest of the menu.

Figure 3 Drop-down menu with Hello World item added

 

How It Works

The Custom_ AddDocLibMenuItems function takes two parameters. The first parameter, called m, represents the menu object itself; the second parameter, ctx, provides HTTP context information about the web request.

Adding a menu item to the menu requires just one function call:

CAMOpt(m, strDisplayText, strAction, strImagePath);

 

The CAMOpt function takes four parameters: the menu object to add the new item to, the display text of the menu item, the javascript action to perform when the item is clicked and a path to an image file to associate with the item.

A call to the CAMSep function adds the separator bar to the menu. Both these functions are defined in the menu.js file on the SharePoint server.

Finally, the function returns false to the caller. This makes sure the standard menu items are also added to the menu; returning true indicates that these items should not be added.

 

Debugging the Web Part

To debug the web part, insert a debugger statement into the web part JavaScript:

debugger;

 

Provided a suitable debugger (such as Visual Studio.NET or the Microsoft Script Debugger) is installed, this statement causes Internet Explorer to break into the script when it is run, and offer the opportunity to start debugging.

 

Note: By default Internet Explorer disables script debugging. To make sure script debugging is enabled, open the Internet Options dialog from the Tools menu, and on the Advanced tab clear the Disable script debugging check box.

 

Once in the debugger, you can use the watch window to examine the variables that are available. Interesting variables to examine are m – the menu object, ctx which contains HTTP context information and itemTable which contains information about the list item the menu is associated with.

 

The Send Mail Web Part

Now we have figured out the principles of customising the drop down menus, the next step is to have them do something useful! The following script adds a menu item that sends an email link to the relevant document. It works by parsing the document URL out of the itemTable object and creating an action that instructs Internet Explorer to start a new mail message.

To use create this web part, simply follow the same steps that we used to create the Hello World menu item, using this script instead:

 

<script language="javascript">

 

function Custom_AddDocLibMenuItems(m, ctx)

{

var strDisplayText = "Send Link By Email...";

var strAction;

var strImagePath = "";

 

// parse the URL out of the itemTable

var URL = "";

var index = itemTable.innerHTML.indexOf("href=");

if (index > 0)

{

  var str = itemTable.innerHTML.substr(index + 6);

  index = str.indexOf('"');

  if (index > 0)

  {

    URL = str.substr(0, index);

  }

}

 

if (URL != "")

{

  strAction = 'window.navigate("mailto:%20?subject=Take a look at this document...&body=<' + URL + '>")';

 

  // Add menu item

  CAMOpt(m, strDisplayText, strAction, strImagePath);

 

  // add a separator to the menu

  CAMSep(m);

}

 

return false;

}

</script>

 

Clicking the custom menu item opens a new email message with the URL of the document in the body of the message.

 

Code Samples

Attached with this article are dashboard web parts (.dwp files) for the two samples discussed here. To use them, first unzip them to disk, then go to the Modify Shared Page menu, point to Add Web Parts and click on Import. This adds the custom web parts to the web part gallery so that they can be added to a page.

 

Conclusion

This article has demonstrated one way in which SharePoint Document Library drop-down menus can be augmented with custom menu items. An alternative technique is also described in the SharePoint Products and Technologies SDK


One final thing to note is that the technique described here is not limited to Document Library menus - custom menu items can be added to any list in SharePoint 2003 thanks to a similar hook called Custom_AddListMenuItems.