ThreeWill

Custom Search Refiners

William Holland — Thu, 19 Apr 2012 17:29:44 +0000

Default refiners are great....if you have some pre-existing knowledge of the document.

Out of the box, SharePoint’s search feature makes finding documents, videos, and other items much easier when the user doesn’t know where to begin looking. Sometimes, however, it’s just not enough. If your site collection contains a large number of documents, as was the case with a recent project I was on, a user’s search may return hundreds of results. The only methods the user has at their immediate disposal for narrowing those results down is to either search again with more keywords or use some crummy filters provided by the Search Refinement Panel. The default refiners, such as author, require that the searching user know details of the document prior to searching for it. Great if you just published a document and immediately had a brain fart; not so useful for the rest of us though.

Fortunately, it’s not all that difficult to create your own custom refiners that will provide your users with the experience they have been searching for. All puns aside, adding custom refiners will allow your user to narrow their search results down by more meaningful filters, thereby reducing the amount of time spent searching and, hopefully, increase productivity.

Requirements

You have an existing site collection with the Search feature active and configured.
You have sufficient permissions to access and modify Central Administration.
You have permissions to edit pages and web parts.

Scenario

For the sake of consistency, I’ll be using the “Productivity Hub” as my example site collection. The Productivity Hub is a SharePoint 2010 site collection that contains a plethora of content for users making the migration from Office 2007 to Office 2010. It’s a free download, available at http://www.microsoft.com/download/en/details.aspx?id=7122.

The content for the Productivity Hub is stored in a document library, aptly named “Content Library”. The content library contains a “Product” column which indicates what Office product the document is intended for. This is the column that I will use during this tutorial.

In the beginning…

To start things off, the first thing we must do is determine what data we have that could be useful to searching users. Something that helps them define what they’re looking for. If your site collection contains a large number of documents that relate to specific clients, it would probably be useful if the user could narrow their search by documents that only pertained to a chosen customer. In my case, my documents all pertain to various products in Microsoft Office 2010, so I’ll use the “Product” column so that my users can narrow their search results down based on specific Office products.

As a best practice, the best columns to use for metadata are those that are indicative of the document contents, which is why I’m not a huge fan of the OOB search refiners. It’s also best if the data stored in the column is NOT a multi-value choice or multi-line text.

If your library doesn’t contain a particularly useful column…create one!

If you must walk before you run, before you walk you must have crawled.

Unless you created a new column for your library, the chances are that your desired column has already been indexed when the last scheduled site crawl ran. Regardless, we still need to verify that it was crawled. You know what they say happens when you assume something.

The Crawled Properties Page of Central Administration

Open up Central Administration and navigate to Application Management | Manage Service Applications
From list of Service Applications click Search Service Application
From the Queries and Results section, click the Metadata Properties link.
Finally, click the Crawled Properties link.

This page contains a list of every column captured during a crawl and, hopefully, your column will be in this list somewhere. To find out, type the name of the column in the search bar towards the top of the page and let’er rip. With any luck, you’ll receive a few results. My search for “Product” resulted in quite a few, but the one I’m interested in is ows_Product(Text). If given the choice, the crawled property that contains the ows_ prefix is usually the one you want.

If you created your own column or your search results didn’t include an ows_{YourColumnName}({YourColumnType}) type result, then I’m sorry to say that before you can continue, you’re going to have to do a full or incremental crawl. This may or may not be an issue for you depending on how long a crawl takes to complete.

Once you have verified that your column has been crawled, click the Managed Properties link followed by the New Managed Property link.

The "New Managed Property" window.

Fill out this new window by giving your property a useful name.

Try keeping the name to one word, but if you need to use multiple words be sure to use Pascal casing.

Give your property a useful description.
Select the appropriate type.
In the second section, select Include values from a single crawled property based on the order specified.
Click the Add Mapping button.
Type the name of your crawled property and click the Find button.
Select your crawled property from the list and click the OK button.
Everything else can be left at its default values, so click the OK button.

Setup for Search Success

With our new managed property in place, we’re ready to begin adding our refiners.

Navigate your way to your search results page and put it in edit mode. The first thing we need to do is include our new metadata in the search results.

Locate the Search Core Results Web Part, located roughly in the middle of the page.
From the web part context menu, click Edit Web Part.
In the web part editor, expand the Display Properties section.
In the Fetched Properties text box, scroll towards the end until your cursor is directly in front of the tag.
Add the following: , replace ProductName with whatever you named your managed property.
Click the Apply button.
Click the OK button.

Next, we need to define our actual refiner.

Locate the Search Refinement Panel web part, located on the left side of the page.
From the web part context menu, click Edit Web Part
In the web part editor, expand the Refinement section.

We need to add our refiner definition in the Filter Category Definition text box. This text box is quite a bit wordy, so it may be easier for you to copy the contents and paste them in an editor that will format it for you, such as NotePad++ or Visual Studio.

I do declare!

Once you have your code formatted, you can see that it’s an XML document that contains a series of definitions. These definitions are what define the refiners that appear on the refinement panel web part. You may also notice that they appear on the web part in the order that they are defined here, so a decision must be made on where you want your refiner to appear. I think the Product refiner is pretty useful, so I’ll simply insert my code before the other categories. Below is the definition I’ll use to declare my refiner.


  
	
	  
		OutLook
	  
	  
		Lync
	  
	  
		Word
	  
	  
		Excel
	  
	  
		PowerPoint
	  
	  
		OneNote
	  
	  
		SharePoint

As you can see, the Category tag contains a large number of properties that you can configure. Here are a few that you’ll certainly want to understand.

Title – This is the display name for your refiner category.
MappedProperty – Extremely important. This should match the name of your managed property and the name specified when you added the column tag to the search core results web part. It is case sensitive!
MetadataThreshold – The number you specify is how many search results are required to be returned that match a filter before it will be presented to the user.
NumberOfFilterToDisplay – The number of filters to be displayed before the user has to click the “show more” link.
MaxNumberOfFilters – If the user clicks the “show more” link, how many filters do you want them to see. Set the value to zero if you want to show all filters.

For the complete list, please refer to this MSDN article: Refinement Panel XML Schema

The CustomFilters element has a few properties of its own, but for the most part, it will use the values shown above. The most common exception to that is when you’re refining by dates. The link above provides an explanation for each of these properties as well.

Finally, you have the CustomFilter and OriginalValue nodes. The “Name” property of CustomFilter is the text that will be displayed on the refinement panel, so keep it short and precise. The value between the OriginalValue tags is the value we expect for each custom filter. Again, this value is case sensitive.

Once you’ve created your declaration, copy the contents of your editor and find your way back to that cluttered text box. Replace its contents with your code.

Click the Apply button and stop editing the page.

And you’re done! Well, almost. If you do a search, you notice that your refiners aren’t showing up.

I just learned to run, now you tell me to crawl again?

Yup. You’ll have to do another full crawl before your refiner will appear. Pretty much anytime you make a change to the search metadata, you’ll be forced to do this.

However, once that’s completed….

Ta-Da! My Custom Refiner LIVES!

Flooding the Sandbox

John Underwood — Mon, 19 Mar 2012 20:36:10 +0000

As you work with and develop sandboxed solutions, you may find the need to intentionally exceed a solution’s quota for testing or demonstration purposes. Here’s a little insight on a demo I recently created that does that very thing.

Rewarded For Doing the Wrong Thing?

Usually developers don’t get rewarded for writing code that blows up, but in this case that’s precisely what I wanted to do. I wanted to create a simple sandboxed solution that could easily and predictably exceed a resource quota so that I could demonstrate what happens when an errant sandboxed solution gets “locked up” for the day. To accomplish this, I created an Empty SharePoint Project using Visual Studio 2010, and then I wrote a simple web part (not a visual web part, mind you) that would throw an exception in its OnLoad() method as follows:

A Web Part That's Guaranteed to Fail!

From there, I deployed the solution to the site, created a new page in the Site Pages library, and added my web part to the page. Obviously, from this point forward any time the page loads, the web part will generate an unhandled exception.

Setting The Bar Low

Next, I set artificially low quotas so that I could reach my quota limit very quickly. This involved the following steps:

Navigate to Central Administration | Application Management | Specify quota templates
Create a new template named “Small Sandbox” with the following settings:

Creating the Quota Template

Click OK to save changes.

Once the quota template is created, we’ll need to use it:

Navigate to Central Administration | Application Management | Configure quotas and locks
Select the correct web application and then apply the previously created template as follows:

Selecting the Quota Template

Click OK to save changes.

It’s All in the Timing

Now that we’ve configured the quota limit at a single point, one would assume that we could simply request the page with the errant web part a sufficient number of times and immediately exceed the quota. However, there’s one problem: the statistics used to measure quotas do not update instantly, but instead wait on the following timer jobs:

Solution Resource Usage Log Processing (runs every 5 minutes by default)
Solution Resource Usage Update (runs every 15 minutes by default)

In order to actually get to the point where I’d exceed the daily quota I could have done any of the following:

Sit around and wait on the timer jobs (boring, and a time-waster)
Interactively choose to run the jobs from Central Administration (useful, but a bit tedious after a while)
Run them from PowerShell (yes!)

Now, if the timer job is named “Solution Resource Usage Log Processing” then one would assume that’s the name we’d use in PowerShell, amirite? Well, not so fast… there’s a completely different name that must be used from PowerShell and, as far as I can tell, these alternate names aren’t documented on the Microsoft site (if anyone does have a link, I’ll take it). So, I used the following PowerShell script to list all of the timer jobs for my web application:

List Available Timer Jobs for Web Application

Using the output from the PowerShell script (and a few Google searches), I deduced that I needed the following jobs:

job-solution-resource-usage-log
job-solution-resource-usage-update

The completed PowerShell script exercises the errant web part by repeatedly requesting the page that hosts it, and then kicks off the correct time jobs. Remember, the PowerShell script simply kicks off the jobs – it doesn’t wait until they finish! Because of this there still might be a short lag time between the running of the job and the updating of the statistics.

Exceeding the Quotas and Updating the Results

All Locked Up

To show the current quota usage, do the following:

Click Site Actions | Site Settings
On the Site Settings page click Solutions (in the Galleries section)

Once the quota is exceeded the following information is presented:

Daily Quota Exceeded

Upon returning to my page I get a different error message indicating that the daily quota has been exceeded:

Web Part Throws a Different Exception

Hitting the Reset Button

Presumably, one would want to be able to reset the quota once the demo or test was complete. Again, the key lies with a timer job. In this case it is the “Solution Daily Resource Usage Update” job that resets the daily quota count back to zero. Using the name “job-solution-daily-resource-usage” I was able to kick off the timer job from PowerShell as follows:

Resetting the Locked Solution

Other Ways to Fail

If you wish to stress test other aspects of the quota points calculation, the following articles may be of interest:

Have Fun Playing in the Sandbox!

Download sample code and PowerShell scripts…

Sandboxed Web Services

Kirk Liemohn — Wed, 25 Jan 2012 22:10:37 +0000

Playing in the Sand

Those of you who 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 time 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 above 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 that 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 used 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 a 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.

Adding jQuery to SharePoint

John Underwood — Wed, 25 Jan 2012 20:14:17 +0000

Options, Options, Options

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 in 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:

Do you need to include jQuery for the majority of the pages in a site, or just for one or two?
Where do you need to use jQuery (i.e. in a Visual Web Part, on an Application Page, on a Site Page)?
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 the scenario where you’re working in a Sandboxed Solution, since such solutions cannot store files in the SharePoint Root (or “14 hive”). Additionally, it is 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):

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:

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

Id="BlogSample.LoadJQuery" ScriptSrc="~site/SiteAssets/jquery-1.6.4.js" Location="ScriptLink" Sequence="10020" />

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

ScriptSrc="~site/SiteAssets/Custom.js" Location="ScriptLink" Sequence="10030" />

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 /jquery-1.6.4.js (where is the name of the folder you created in step 3 above).

Name="Recipe2/jquery-1.6.4.js" />

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

Click me

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 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:

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