Those of you that have worked with Sandboxed Solutions know the give and take they represent: they provide solace and security to the administrators by insuring that runaway code doesn’t kill a server but at the same they can handcuff a developer in their quest to meet the customer’s needs.

I recently worked on a project that needed to provide a web service from within SharePoint in a way that was sandbox-friendly. A coworker of mine found a great link on creating custom web services within a sandbox: Sandboxed Web Service – BillGr’s Blog – Site Home – MSDN Blogs. I’ve done a bit of research to build upon the ideas presented in this article.

Digging Deeper

The example provided in the link about used a StringBuilder to emit JSON.  I like JSON, but I also like XML, especially when I want to use XSLT.  I also like using DataContracts.  Here are some changes to the example provided in the blog referenced above showing a simple DataContract.  This has been tested not only in a sandboxed solution, but also in SharePoint Online.  To show it is possible to read post data, we also return a POSTed request body.

Custom Data Contract Definition

In order to produce the desired output I provided an override to the Render() method in the Web Part. In this simple example I put the list items into an array of Task objects and output the data as XML or JSON.  Note that in lieu of custom XML, you can emit SPListItemCollection.Xml, but in many cases you want more control of what you are providing and it may not be list data at all (not to mention that the XML is quite bloated).

Updated Web Part Code, Including Override to Render() Method

An example of the rendered XML is below (newlines and white space added for clarity).  Note that when using a browser to call the web service manually, you may have to choose to “view source” to see the output because of the limitation that we are unable to specify the Content-Type in the response header.  I was using the REST Client for Firefox so I could POST some data and easily set the Accept request header.

XML Returned from Web Service Call

Using the JSON option, we get this output:

Returned JSON from Web Service Call

Starting with the sample page referenced in the original blog post, I added a few more methods to test in different ways (note that I didn’t modify the existing method that was already in the code).

Modified Script for Test Page

In addition to the above script, I added some markup for buttons:

Buttons for Invoking Test Scripts

Testing my new code produced the following results (note that I’m using Tasks list because I’m expecting there to be a Status in the returned results):

Results From New Methods on Test Page

Building Castles In The Sand

While there are still possible limitations to this (particularly related to the fact that we cannot manipulate the Response-Type in the HTTP Response Header), this is an interesting and exciting technique for implementing web services in a Sandboxed Solution.

As I research and learn more about SharePoint programming I occasionally come across blog posts that start with titles like “the best way…” or “the correct way…” to accomplish a certain task. If there’s anything I’ve learned with SharePoint along the way, it’s that there is rarely one correct and proper way of doing things; rather, there are usually a variety of approaches, each with its own pros and cons. To that end, this post attempts to document some of the ways one might include jQuery into a SharePoint site.

Note that this article isn’t intended to be a tutorial for jQuery (click here to learn more about jQuery). The presumption is that you’re reading this because you already know something about the power of jQuery and you wish to unleash that power in the context of SharePoint 2010. Also, note that I’m not trying to document every single way this problem can be solved; I’m just serving up some recipes that have worked for me. In addition, this article assumes that you already have some knowledge about SharePoint programming (such as using Visual Studio 2010 to create SharePoint projects). Finally, note that the demos below assume that you have Visual Studio 2010 and that you’re working against a Team Site.

A Fork in the Road

As Yogi Berra is alleged to have said, “If you see a fork in the road… take it!” In our case, there are several forks in the road:

1. Do you need to include jQuery for the majority of the pages in a site, or just for one or two?
2. Where do you need to use jQuery (i.e. in a Visual Web Part, on an Application Page, on a Site Page)?
3. Will you be working with a Sandboxed Solution?

The answers to these questions will influence which of the following recipes will work for you.

Recipe 1: Loading jQuery from a Document Library with a Custom Action

This approach is useful when you need to have jQuery available to most or all of the pages in a site. It is also useful in scenario where you’re working in a Sandboxed Solution, since such solutions cannot store files in the SharePoint Root (or “14 hive”). It is also useful in that .js files stored in a document library can be easily maintained without administrator intervention.

On the downside, storing .js files in a library means they could accidentally or intentionally be deleted or changed, resulting in improper functioning of the application.

This recipe also includes a small bit of custom jQuery code that will be included on each page for demonstration.

1. Create a Visual Studio 2010 Empty SharePoint Project (either Farm Solution or Sandboxed Solution).

2. Add a Module named DeployJQuery; delete the sample.txt file and add your jQuery file to the module.

3. Modify the Elements.xml file for the DeployJQuery module as follows (note that all line numbers are provided for convenience only, and should not be included in source):

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Module Name="DeployJQuery">
<File Path="DeployJQuery\jquery-1.6.4.js" Url="SiteAssets/jquery-1.6.4.js" />
</Module>
</Elements>

4. Add a second Module named DeployCustomJS; rename the sample.txt file to Custom.js.

5. Modify the contents of the Custom.js file:

$(document).ready(function () {
$('.static.menu-item').mouseover(function () {
$(this).fadeTo("fast", 0.33);
$(this).fadeTo("fast", 1);
});
});

6. Modify the Elements.xml for the DeployCustomJS module as follows:

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Module Name="DeployCustomJS">
<File Path="DeployCustomJS\Custom.js" Url="SiteAssets/Custom.js" />
</Module>
</Elements>

7. Add an Empty Element named LoadJQuery and then modify its Elements.xml file as follows:

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<CustomAction Id="BlogSample.LoadJQuery"
ScriptSrc="~site/SiteAssets/jquery-1.6.4.js"
Location="ScriptLink" Sequence="10020" />
</Elements>

8. Add a second Empty Element named LoadCustomJS; modify its Elements.xml to match the following:

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<CustomAction Id="BlogSample.Script"
ScriptSrc="~site/SiteAssets/Custom.js"
Location="ScriptLink" Sequence="10030" />
</Elements>

9. Deploy the project.

10. Navigate to the site. As you float your mouse over the menu items in the quick-launch menu you should see them pulse from solid to opaque to solid.

Recipe 2: Loading jQuery from SharePoint Root using ScriptLink Control

This is useful when you’re using jQuery on an application page or a Visual Web Part; both can easily be configured to use one or more ScriptLink controls.

Obvious limitations include: jQuery is only made available to one page at a time; use of ScriptLink control is limited to certain kinds of pages; and deployment of files to SharePoint root precludes the use of this technique for Sandboxed Solutions.

1. Create a new Farm Solution in Visual Studio 2010.

2. Add a new SharePoint mapped folder to the project; the mapped folder should point to {SharePointRoot}\Template\LAYOUTS\1033.

3. Underneath the mapped folder create a new mapped folder with the same name as your project (in my case, Recipe2 is the name of the sample project). You can see the results below:

4. Deploy the project (this is done here so the ScriptLink control won’t produce an error on a later step when you try to use the .js file).

5. Add a Visual Web Part to the project and name it jQueryPart.

6. Add a ScriptLink control to the web part (see source below). Set the ScriptLink’s Name property to <projectname>/jquery-1.6.4.js (where <projectname> is the name of the folder you created in step 3 above).

<SharePoint:ScriptLink ID="ScriptLinkJQuery" runat="server"
Name="Recipe2/jquery-1.6.4.js" />

7. Add the following markup to the web part just below the ScriptLink:

<script type="text/javascript">
var colors = ['lime', 'aqua', 'orange'];
var i = 0; $(document).ready(function () {
$('#sample').css('background-color', colors[i]);
$('#sample').click(function () {
i++;
if (i >= colors.length) { i = 0; }
$(this).css('background-color', colors[i]);
});
});
</script>

<span id=”sample” style=”cursor: pointer”> Click me </span>

8. Deploy the project.

9. Navigate to the site and then navigate to the Site Pages library.

10. Add a new page named jQueryTest.

11. On the jQuery test page click Insert tab | Web Part | Custom | jQueryPart; then click the Add button to place the part on the page as follows:

12. Click the Save and Close button to save your changes.

13. Click the “Click me” text and observe the color change.

Recipe 3: Loading jQuery from a Content Delivery Network (CDN) using the Content Editor web part

This approach is beneficial when you only need to use jQuery on one or a small number of site pages (both Wiki and Web Part Pages). It is also advantageous in that it does not require storing any extra files on the SharePoint server: the jQuery source is loaded from a Content Delivery Network while the jQuery code that you author is embedded directly into the page itself. Additionally, this solution doesn’t violate any of the tenets of Sandboxed Solutions.

Obviously this isn’t a useful approach for site-wide jQuery needs. Also, there may be some rare cases where you can’t accomplish what you want with this approach because the jQuery links and source are placed down within the document as opposed to the preferred approach of locating script in the <head> section of the HTML markup.

1. Navigate to the site pages library and add a new page named jQueryContent.

2. Add a Content Editor Web Part to the page.

3. Edit the Content Editor Web Part and click on the “Click Here to add new content” link.

4. On the Ribbon select HTML | Edit HTML Source.

5. In the Edit HTML Source dialog enter the following markup and then click OK:

<script language="javascript" type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js"> </script> <script language="javascript" type="text/javascript">
$(document).ready(function() { alert("jQuery"); });
</script>

6. Click OK to stop editing web part, then click Save and Close button.

7. The page should now display a popup as follows:

What about Master Pages?

One can certainly embed the needed jQuery references directly in a master page, using either a ScriptLink control or a simple <script> tag. However, I’ve chosen not to focus on that approach simply because I’m inclined to view modifying the Master Page as something I don’t want to do unless I absolutely must. If you’ll be changing the Master Page as a part of a bigger branding solution then it certainly makes sense to embed jQuery there; otherwise, Recipe 1 above will give you similar site-wide functionality in what is perhaps and easier and safer way.

Learning to be a great cook

One of the attributes of a great cook is the ability to synthesize ingredients to come up with something new and delicious. The same can be said of these SharePoint recipes. For example, the use of a Content Delivery Network to serve up jQuery isn’t limited to just one recipe. Experience and experimentation will allow you to find the mix of ingredients that works best for your masterpiece.

Careful not to burn yourself…

There are always hazards when cooking: hot stoves, sharp knives, and dropped pans. Likewise there are hazards involved in integrating jQuery with SharePoint, including the following:

• The risk that some other developer would introduce their own jQuery solution, resulting in a possible conflict of versions or files.
• Failure to test thoroughly resulting in erratic behavior in the SharePoint UI.
• The lack of Microsoft providing an “officially sanctioned” approach to introducing jQuery into SharePoint means that any introduction of jQuery involves a certain amount of wizardry.

Hazards notwithstanding, the power of jQuery makes it a compelling option for customizing and enhancing the SharePoint UI.

• SharePoint Hyperlink Column
• Informative Graphics

I could give you the full multi-paragraph tour of the different options that I tried (and failed on) – but’s let’s skip that and just get to the solution.

Creating the Calculated Column

My calculated column needed to provide two things: (a) the Title of the entry in the library, and (b) a unique token where I could find all instances of the calculated column on the page and convert their contents as desired. I accomplished that with the following formula:

=”{125ED6EA-0E45-4A0B-9235-B898B1C104D4}”&[Title]

Making the Results Behave

Now obviously, the formula above would produce output that would scare our users. So the next step was to create a chunk of JavaScript that would find the GUID, strip it off, and then formulate the remaining title into a clickable link. After doing a little inspection of the HTML produced by SharePoint, I was able to deduce that my data was always inserted into an element that had a certain CSS class associated with it (ms-vb2 in this case), so I created a jQuery selector that would search for elements that were decorated with that class and contained the GUID. If you reference Figure 1 below, you’ll see the selector code on lines 14 through 16.

Figure 1: JavaScript Code Listing

The remaining code in Figure 1 breaks down as follows:

• Line 17: extract the text node from the element
• Line 18: strip off the GUID, leaving just the Title remaining
• Line 19: create a string that contained the anchor tag to be added
• Line 20: replace the matching element’s HTML with the newly formatted anchor tag

One other thought: don’t be distracted by the fact that I’m simply calling the JavaScript alert() function. I could call any JavaScript function I want, including my own custom code or functions of the SharePoint client API. On the project where I employed this technique I called SP.UI.ModalDialog.showModalDialog() to display information in a modal dialog.

Before and After

Every great late-night infomercial has to have a before and after shot to drive home the effectiveness of the product. Figure 2 and Figure 3 show us the fabulous results in this case.

Figure 2: Calculated column before JavaScript

Figure 3: Calculated column after JavaScript

You can also see in Figure 4 that upon clicking the link the popup shows the Title of the library item.

Figure 4: Popup appears when calculated column link is clicked

 Constraints, Gotchas, and Notes

Obviously, you will have to add jQuery to your SharePoint page or pages in order to have this work. There are several ways to add jQuery to SharePoint, but enumerating each of them is beyond the scope of this article (maybe we’ll get to that one in a future blog post).

In my case I loaded jQuery and my own script from .js files that I loaded to the Site Assets library. Why? Because I was working in a Sandboxed Solution and therefore couldn’t store anything under the LAYOUTS folder (I smell another future blog post).

Finally, it would be very easy for a user to enter a single quote in the Title column and break my code. That’s right, the same issues that led us to SQL injection are present here. In the real world we’d have to add the additional code to scrub the data and properly escape any characters that would interfere with the proper function of our code.

Digging into the code (via .NET Reflector) I uncovered more detail. There is a property on each list named “CanReceiveEmail” which enables email for a list. Unfortunately, the code associated with this property only functions for the out-of-the-box list templates.

The overall email process goes as follows:

1. A timer job calls the SPIncomingEmailServiceInstance.ProcessEmail() method; it picks up the *.eml files and begins the processing (for development environments this can be configured to a local folder in IIS for testing).
2. Further into the process the SPEmailMap.GetEmailAliasRecord() method calls a stored procedure in the SharePoint Admin database called proc_getEmailEnabledListsByAlias.
3. The proc_getEmailEnabledListsByAlias stored procedure checks for the alias portion of the incoming email settings (e.g. the portion of the address before the “@” sign) in the EmailEnabledLists table.
4. The stored procedure returns the guids for the site, web, and list for the email alias; from there, the SPEmailEngine.HandleEmailFilesForWeb() begins processing the emails for the Web/Lists.
5. At this point the SPEmailHandler.GetHandler(SPList) method is called and determines the email handler for a list.

The SPEmailHandler implementation (such as SPDocLibEmailHandler) is then responsible for carrying out the reception of emails for the list. For reference, see the figure below:

So then, how can we have email enabled Custom Lists? The SPExternalEmailHandler is the key. As seen in the code listing below, the SPExternalEMailHandler class is actually an SPEmailHandler subclass which  has a ProcessMessage() method.

ProcessMessage() Method listing

So, we can attach SPEmailEventReceivers to any list based on this code, but what do we lose?   Since the processing of the message is now totally on you, you now have to manage the storage of the attachments, security of who is posting, virus scanning, and a whole host of other things.  Doing a full run through of the SPEmailHandler and its subclasses (like the ones below) is probably a prerequisite for estimation and expectation setting  before rolling your own for a client.

SPEmailHandler and its subclasses

While it is great to have options, remember that if you undertake writing your own handler you’ll have several important expectations to meet in your code. Proceed with caution!

Wow, we’re at our last ThreeWill Hero. In this final post, we want to recognize both a special person and a special company. The person that we would like to recognize is Jason Jones and the company is Microsoft. Jason epitomizes all that is good about partnering with Microsoft. He’s a great communicator, he’s energetic and aggressive at the right times, and he looks for opportunities that make sense for both Microsoft and ThreeWill.

A Microsoft Partner Since the Beginning

One of the first things that we did as a business was to register as a Microsoft partner. Besides the generous licensing offered from partnering with Microsoft, this gave us the confidence that we were not starting our business alone. We felt like our company was starting out with one of the best brands in the industry and gained credibility that comes only by working with a company that has a strong reputation like Microsoft.

How Many Thousands of Companies Have Started Because of Microsoft?

It seems like sometimes it’s fashionable to take shots at Microsoft (I think it’s a part of human nature for people to try and knock success). But there is one thing that is undeniable about Microsoft – they are a partner focused company. For all that is said about the greatness of Apple and Google, Microsoft has provided thousands of companies like ThreeWill the opportunity to start and succeed because they are partner focused. For that, we are grateful. We wouldn’t have started ThreeWill without Microsoft – they gave us a business model that helped us grow and thrive.

Deepening the Relationship

About five years in (and lots of conversations to convince certain people) we became a managed partner for Microsoft. We have had a number of Partner Account Managers (PAMs). We started out with Trey Kimbel, another real gem at Microsoft. Trey provided a great introduction to working well with Microsoft. We learned that PAMs have one of the most demanding and difficult jobs out there. Lots of responsibility with little authority and the difficulties of trying to serve multiple masters.

Partnering as a Systems Integrator

As a systems integrator, your business is making things work together. We’ve built a business around making SharePoint work with other platforms and key emerging technologies (including Enterprise Video with Polycom, Mobile with Rover Apps, Social with Jive Software). Although sometimes these integrations might lead to competitive situations, most folks at Microsoft understand that all Microsoft solutions might not be the right solution for all companies (I said most). No one can deny Microsoft’s success in focusing on the Enterprise over the last ten years, and a key part of this success is their willingness to work well with other products/platforms. Kudos, Microsoft.

Back to Jason

I’ve been talking a lot about Microsoft in the last couple of paragraphs, but many of the positive attributes could also be said about Jason as a person. Jason is always looking out for us – talking to us about how to improve what we do based on what he learns from other companies like us. Part advocate, part mentor, part friend – he checks in with frequent calls to make sure things are going well and he looks to connect us to people both inside and outside of Microsoft that have the potential to make an impact on our business. Jason is also a man of faith – the highlight of every Microsoft Partner Conference is attending the Partners in Christ meeting that Jason helps lead. He’s got his head set on straight and knows what is important – another reason why we enjoy working with him and trust him. Jason is also very involved with his local Church serving in the middle school ministry which shows Jason has a heart for his community as well as his business.

Our PAM is a Celebrity

Jason is a bit of a celebrity — or at least his family is…his daughters, Mary-Charles Jones – http://www.imdb.com/name/nm2325460/ and Maggie Elizabeth Jones – http://www.imdb.com/name/nm1369619/, are successful young actors. Mary-Charles has been on Grey’s Anatomy and she plays the recurring role of a younger version of Hanna Montana. Both girls were in the recent remake of Footloose. In December of 2011, Maggie will star opposite Matt Damon in Cameron Crowe’s “We Bought a Zoo” which is sure to be a big family hit! I’m not sure how he does this, but for a good part of the year his family is in Hollywood to meet the demands of success. Pretty amazing.

The Future

We recently brought on a twenty year veteran of Microsoft (Kirk Puffenberger). Kirk will be taking the lead in building our partnership with Microsoft (working quite a bit with Jason) and other companies that we are aligning with for success. We look forward to seeing where this partnership leads us and what the next 10 years has in store for both companies. Like any healthy relationship, we’ve had our share of disagreements…(we’re still waiting for an app store for SharePoint) But, by pushing each other, we have learned to grow stronger.

A Word from Jason

Jason had the following to share upon hearing that he was a ThreeWill Hero…

”I am truly honored to be featured as a THREEWILL HERO. It is working with companies like THREEWILL that truly make my job a joy each and every day. Threewill has shown unwavering commitment to not only Microsoft but to building great relationships with everyone they work with. Over the years I have seen how the Threewill team has positively impacted customers with their innovative approach to technology and knowing them has certainly impacted me personally over the years as well. I know that the next ten years will hold tremendous success for the entire Threewill team and I am excited to watch it happen.”

Thanks for being our final ThreeWill Hero Jason and thanks Microsoft for your support through the years!

Follow Jason Jones on Twitter

Microsoft has implemented a resource center for the object model (http://msdn.microsoft.com/en-us/sharepoint/ff770207). Any study of the object model should begin with this resource.

The SharePoint Client Object Model can prove useful to address the following problems:

• Integrate data between SharePoint and other systems in cases where Business Connectivity Services don’t provide an appropriate solution.
• Allow users to manipulate SharePoint data from a Windows application or web application without any SharePoint knowledge.
• Enhance the SharePoint browser-based user interface by providing new capabilities or refreshing data without a costly refresh of the entire screen.
• Allow developers to work around constraints where Sandboxed Solutions are required (see http://msdn.microsoft.com/en-us/magazine/ee335711.aspx for more details about sandboxed solutions).

Three Delicious Flavors!

The SharePoint Client Object Model supports three programming environments:

• .NET 3.5 or greater
• Silverlight
• EMCAScript (JavaScript, JScript)

As you would expect, .NET and Silverlight model each other most closely because, after all, Silverlight logic is implemented using a .NET langauge. In some cases JavaScript simply cannot implement the exact same syntax as a .NET language, but wherever possible Microsoft has maintained a consistent syntax. Not only that, the syntax for all three flavors maintains a level of consistency to the SharePoint Server Object Model.

Understanding Context

Most remote programming models use some sort of proxy to act as the mediator between local client code and the server code that’s being invoked remotely. In the case of the Client Object Model the ClientContext class provides that plumbing. For .NET and Silverlight, the class accepts a URL for the site to be accessed. On the other hand, the JavaScript implementation of ClientContext requires no URL because the JavaScript on a page must implicitly work with resources from the site where the page loaded from; to attempt to load another site would violate rules concerning cross-site scripting.

Hello, World!

To write Hello, World! (or the Client Object Model equivalent) I did the following:

1. Create a console app using Visual Studio 2010.
2. Add a reference to two DLLs:  Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll (these can be found at “C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\ISAPI”).
3. Add a using statement for the Microsoft.SharePoint.Client namespace.
4. Write the code below and run the app.

using (ClientContext ctx = new ClientContext("http://demo2010a/sites/spcom"))

{

   Site siteColl = ctx.Site;

   ctx.Load(siteColl); // ask for siteColl object

   ctx.ExecuteQuery(); // go to server and get it!

   Console.WriteLine(siteColl.Url);

}

Running the app produces this result:

Now, let’s look at the code…

First, notice what you don’t see: the keyword new. That’s not to say that you’d never allocate an object in the Client Object Model, but in this case everything that is needed is provided by the client context.

Second, notice the Load() method. It would be natural to assume that it’s loading the siteColl object, but in reality Load() is simply queuing up a request for data. It’s as though we’re making a shopping list of things we’re going to need before going to the store. Given that analogy, it stands to reason that one might have multiple Load() statements each doing a different thing: requesting an object, loading list data, etc.

Finally, observe the ExecuteQuery() method. This is where we actually go off to the store and pickup what we need – in this case, the siteColl object. Attempting to access any properties of the siteColl object before we run ExecuteQuery() would result in an exception.

Coming Attractions

In an upcoming blog post I’ll dig deeper and show you how to manipulate list data. For now I hope I’ve given you a brief intro to the object model and given you some food for thought on how you might use it.