Add a context menu: Send document link by email.

Introduction and project outline

Ok, this is a well documented task, but I wanted to add my own methods here.

This post will detail how to add a Send Document Link By Email page to the context menu of a document library (and a picture library). A later post will tell you how to send the actual document by email.

To add an item to the context menu we need to do the following:

  1. Create a custom_ows.js file
  2. Add methods to custom_ows.js file to add new menu items
  3. Add CustomJS attribute to site definition
  4. Create a asp.net project to hold your CustomMenuAction pages

1. Create a custom_ows.js file

Windows SharePoint Services uses a file called ows.js to hold a whole bunch of javascript code used throughout the application, including creating the Menu options used in the Sharepoint context menu's.

We could of course just alter this file to add our new options, but that is not recommended because if Microsoft release an update or service pack, they may make changes to their default files, including this one. So, they very cleverly gave us the ability to use the custom_ows.js file. A method in this file gets called at before ows.js creates it's own menu options. So, our menu items will appear at the top of the list.

We can also use this file to override the existing menu items, which allows us to either remove them or change their action without having to edit the ows.js file directly.

Create a empty text file called custom_ows.js in the folder:
C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\LAYOUTS\1033

2. Add methods to custom_ows.js file to add new menu items

Open the file for editing and paste in the following code:

function Custom_AddDocLibMenuItems(m, ctx)
{
var currentItemFileUrl;
var currentItemFSObjType;

if (currentItemFileUrl == null)
currentItemFileUrl = itemTable.ServerUrl;

if (currentItemFSObjType == null)
currentItemFSObjType = itemTable.FSObjType;

if (currentItemFSObjType != 1)
{
// Add Send Link By Email Menu Item
var strDisplayText = "Send Link By Email";
var strAction = "SendLinkByEmail('" + ctx.HttpRoot + "', 'FileName=" + currentItemFileUrl + "')";
var strImagePath = ctx.imagesPath + "EML16.GIF";

// Add our new menu item
CAMOpt(m, strDisplayText, strAction, strImagePath);

// add a separator to the menu
CAMSep(m);
}

return false; // this enables the rest of the menu items to be rendered.
}

function SendLinkByEmail(strHttpRoot, strArgs)
{
var strUrl = strHttpRoot + "/_layouts/" + L_Language_Text + "/3iSendLinkByEmail.aspx?" + strArgs + "&Source=" + GetSource();
window.location.href = strUrl;
}

The first function Custom_AddDocLibMenuItems() is the method called by ows.js. This is the function we use to add our own menu items.

It takes a bit of time figuring out how to use these methods, and you really do need to spend time looking into the ows.js file to see what you can do and use in your own code. Hopefully this example will give you a start, but as we all know, there is no such thing as a free lunch, and you DO have to put some effort into learning it!

First thing we do is declare 2 variable:

var currentItemFileUrl;
var currentItemFSObjType;

currentItemFileUrl tells us, funnily enough, the URL of the file we used to click the context menu on and currentItemFSObjType tells us the type of object we are dealing with.

The next to lines of code populate these values:

if (currentItemFileUrl == null)
currentItemFileUrl = itemTable.ServerUrl;

if (currentItemFSObjType == null)
currentItemFSObjType = itemTable.FSObjType;

itemTable holds a whole load of useful values. Take a hunt through ows.js to see what else it can do. I'll try to write a blog article about this another time.

The next bit of code checks the FSObjType is not 1. This is because we don't want the menu items to be displayed on folders, only documents.

if (currentItemFSObjType != 1)
{

We are finally ready to create the link. We need to set some properties first, such as the Display Text, Action and Image Path:


// Add Send Link By Email Menu Item
var strDisplayText = "Send Link By Email";
var strAction = "SendLinkByEmail('" + ctx.HttpRoot + "', 'FileName=" + currentItemFileUrl + "')";
var strImagePath = ctx.imagesPath + "EML16.GIF";

As you can see the Action text declares another Javascript function SendLinkByEmail and pass on the site Url and the File Url. We will create this function in just a minute.

Once we have configured these values we can call a simple function that adds the menu item to the menu item collection (notice the m parameter that we passed into the function?)

// Add our new menu item
CAMOpt(m, strDisplayText, strAction, strImagePath);

The last thing we want to do is add a seperator to our menu.

// add a separator to the menu
CAMSep(m);

Well, maybe this isn't quite a minute on, but I did say we would come to the SendLinkByEmail function soon!


function SendLinkByEmail(strHttpRoot, strArgs)
{
var strUrl = strHttpRoot + "/_layouts/" + L_Language_Text + "/3iSendLinkByEmail.aspx?" + strArgs + "&Source=" + GetSource();
window.location.href = strUrl;
}

Now, when the user clicks on the menu item we want to redirect them to a page of our choosing. In this case it will be a aspx file of our creation that resides in the /_layouts/1033/ directoy.

3. Add CustomJS attribute to site definition

Once we have created our custom_ows.js file we need to make sure our SharePoint sites know how to find it. To do this we need to edit our site definitions so that they contain a CustomJS attribute when we create out sites.

There is a very important fact to remember here, this change will NOT affect sites already created, it will only allow this code to work with sites created AFTER we make this change.

If you are not familiar with Site Definitions in SharePoint, then shame on you! This is not the place for a discussion of User Templates Vs Site Definitons, but there will come a time when you'll be able to read all about it here. In the mean time there are a lot of places on the googlenet which will cover in glorious detail.

Site Definitions can be found in the following folder on your SharePoint server:
C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\1033\

Once again, it is not recomended that you modify the standard Microsoft files, and that goes for these site definitions. If you want to configure your own definitions then it is generally recommended that you make a copy of one of the site definitions and customise that. This operation is not part of this blog entry, but will be covered later. Again, you can and should, check out one of the many other blogs entries out there on the internet that describe how to do this. For the sake of this article we will modify the STS site definition, which is the default definition used for WSS team sites.

Navigate into the \STS\XML\ folder and you will see the gorgeous ONET.XML file. Get to know this file well. If you are planning on customising your SharePoint definitions then you will have to learn to love your little onet.xml friend!

Fortunately for us, we only need to look at the first line at this point, well, actually the third line if you want to get pedantic! basically change this line:

And add the CustomJS attribut so it looks like this:

You may notice that we use [%=System.Threading.Thread.CurrentThread.CurrentUICulture.LCID%] as part of our URL. This lets us support multiple localities within SharePoint. I don't want to go any further into this in this article, but basically, for the English speaking world, this will resolve down to 1033 when the page runs.

4. Create a asp.net project to hold your CustomMenuAction pages

Now that we have the custom menu items showing on the context menu, we need to write the code to actually perform the menu actions.

Create a standard asp.net project in Visual Studio.Net and call is something like SPCustomMenuActions. This project can be used to store all your custom menu items, rather than creating a new project for each.

Add a webform to this project called SendDocumentByEmail. You can now create this page as a standard asp.net webform.

I will cover this specific page in a future entry.

Mark
Source:sharepointstudio.markstokes.com

0 nhận xét:

Post a Comment

thanks comment