The Big Fat Disclaimer - This has not been thoroughly tested for a production environment. I have also removed references in my snippets below to caching and error handling to try and keep it brief. The downloadable version uses both caching and error handling, but it is still really just a proof of concept and you should TEST it before you deploy it! I take no responsibility if your production servers blow up!I must have seen this requirement dozen of times on different projects, having search results which either:
- Filter using a User Profile Property of the current user
- Filter using a dynamic date range (e.g. using the “TODAY” token)
- Specify the Sort-By (which is normally restricted to either “Relevance” or “Modified Date”
“Show News Articles from the past 7 days which filter based on the user’s location”
“Show events coming up in the next 3 months”
“Show discussions / wiki entries / blog posts which include the current user’s Ask Me About values”
ExampleWell .. on my current client project these very requirements came up .. so this time I decided to knock together the basics of the web part in my spare time and then “donate” it to the project… and this post describes how I built it, what goes on under the hood, and also includes both the source code as well as a downloadable WSP package with the working Web Part in it.
FixedQuery used in the Web Part:
Author:[UPP-PreferredName] AND Write:[TODAY-180]..[TODAY] AND ContentType:Event
Step 1 – Extending the Search Core Results Web Part
So .. to get us started, lets kick off by creating our actual Web Part. I am going to be extending the Search CoreResultsWebPart (link to MSDN).
This is easy enough to achieve by simply creating a new Web Part in Visual Studio and inheriting from the CoreResultsWebPart class. This will make sure our web part gets all of the functionality and properties that the normal Search Results web part does without any additional effort.
1: [ToolboxItemAttribute(false)]
2: public class ExtendedSearchWebPart : CoreResultsWebPart
3: {
4:
5: }
Step 2 – Overriding the Query and SortOrder
Now the next bit to tackle is how to override the actual query that gets executed. Well the best place to do this is to override the ConfigureDataSourceProperties method. This method gets called before the query is actually executed against the Search engine itself.
You can then leverage the CoreResultsWebPart.DataSource property (which is of type CoreResultsDataSource). This is what allows all of the magic to happen.
1: protected override void ConfigureDataSourceProperties()
2: {
3: // only perform actions when we are trying to show search results
4: // i.e. not when you're in Design Mode
5: if (this.ShowSearchResults)
6: {
7: // call the base web part method
8: base.ConfigureDataSourceProperties();
9:
10: // get the data source object
11: CoreResultsDatasource dataSource = this.DataSource as CoreResultsDatasource;
12:
13: // override the query being executed
14: dataSource.Query = "Author:\"Martin Hatch\"";
15:
16: // remove the original sort order
17: dataSource.SortOrder.Clear();
18: dataSource.SortOrder.Add("Title", Microsoft.Office.Server.Search.Query.SortDirection.Ascending);
19: }
20: }
So lets talk through the code above.
First off we want to make sure we are only executing our custom code when we are actually trying to retrieve search results. This is a fail-safe block as some instances this will be false (such as when you are editing the web part or if you are viewing the “Design” view in SharePoint Designer). We also need to call the base method (as you typically would when overriding a method call!).
Then things get interesting. Line 11 has us create our “CoreResultsDataSource” object from the local “DataSource” property. This has two properties which we are modifying:
Query (line 14) – This allows us to change or completely override the query which is being executed. This will be the entire query including the Fixed Query, Appended Query and whatever the user typed into their search box (if you are using this on a Search Results page). In my example above I am simply overriding the result so that it just searches for items created by “Martin Hatch” (me!)
SortOrder (lines 17 and 18) – This allows us to override the sort order, allowing us to select ANY indexed Search Property you want (I expect excluding rich text fields of course!). In my example, I am sorting by Title in Ascending order.
This can then be easily extended to provide custom Web Part properties to allow the Sort functionality to be specified by the page editor.
Step 3 – Making it re-usable Part 1 - Dynamic Date ranges
So now that we can override the query easily we can move on to adding some of the good stuff. I decided to go with a relatively simple Token Replacement function using a simple [TODAY] token to represent the current date:
- [TODAY] (todays date)
- [TODAY+7] (today plus 7 days)
- [TODAY-7] (today minus 7 days)
So I started off by creating a bunch of class level constants which I would use to recognise the tokens that we are looking for above:
private const string TODAY_PLACEHOLDER = "[TODAY]";
private const string TODAY_ADD_STARTSTRING = "[TODAY+";
private const string TODAY_SUBTRACT_STARTSTRING = "[TODAY-";
private const string TOKEN_ENDSTRING = "]";
The following code can then be swapped out for our ConfigureDataSourceProperties method.
1: protected override void ConfigureDataSourceProperties()
2: {
3: // only perform actions when we are trying to show search results
4: // i.e. not when you're in Design Mode
5: if (this.ShowSearchResults)
6: {
7: // call the base web part method
8: base.ConfigureDataSourceProperties();
9:
10: // get the data source object
11: CoreResultsDatasource dataSource = this.DataSource as CoreResultsDatasource;
12:
13: // get the current Fixed Query value from the web part
14: string strQuery = this.FixedQuery;
15:
16: // swap out the exact "today" date
17: if (strQuery.IndexOf(TODAY_PLACEHOLDER) != -1)
18: {
19: strQuery = strQuery.Replace(TODAY_PLACEHOLDER, DateTime.UtcNow.ToShortDateString());
20: }
21:
22: // perform all of the "Add Days" calculations
23: while (strQuery.IndexOf(TODAY_ADD_STARTSTRING) != -1)
24: {
25: strQuery = CalculateQueryDates(strQuery, TODAY_ADD_STARTSTRING, true);
26: }
27:
28: // perform all of the "Remove Days" calculations
29: while (strQuery.IndexOf(TODAY_SUBTRACT_STARTSTRING) != -1)
30: {
31: strQuery = CalculateQueryDates(strQuery, TODAY_SUBTRACT_STARTSTRING, false);
32: }
33:
34: // swap out the Fixed Query for our Calculated Query
35: dataSource.Query = dataSource.Query.Replace(this.FixedQuery, strQuery);
36: }
37: }
This then calls the CalculateQueryDates support method which I put together:
1: private static string CalculateQueryDates(string strQuery, string startStringToLookFor, bool AddDays)
2: {
3: try
4: {
5: // get the index of the first time this string appears
6: int firstIndex = strQuery.IndexOf(startStringToLookFor);
7:
8: // get the text which appears BEFORE this bit
9: string startString = strQuery.Substring(0, firstIndex);
10:
11: // get the text which appears AFTER this bit
12: string trailingString = strQuery.Substring(firstIndex);
13: int endIndex = trailingString.IndexOf(TOKEN_ENDSTRING);
14: if (endIndex + 1 == trailingString.Length)
15: {
16: // there is nothing else after this
17: trailingString = "";
18: }
19: else
20: {
21: trailingString = trailingString.Substring(endIndex +1);
22: }
23:
24: // find the number of days
25: string strDays = strQuery.Substring(firstIndex + startStringToLookFor.Length);
26: strDays = strDays.Substring(0, strDays.IndexOf(TOKEN_ENDSTRING));
27: int days = int.Parse(strDays);
28:
29: // re-construct the query afterwards
30: if (AddDays)
31: {
32: strQuery = startString + DateTime.UtcNow.AddDays(days).ToShortDateString() + trailingString;
33: }
34: else
35: {
36: // subtract days
37: strQuery = startString + DateTime.UtcNow.AddDays(0 - days).ToShortDateString() + trailingString;
38: }
39:
40: return strQuery;
41: }
42: catch (FormatException ex)
43: {
44: throw new FormatException("The format of the [TODAY] string is invalid", ex);
45: }
46: catch (ArgumentNullException ex)
47: {
48: throw new FormatException("The format of the [TODAY] string is invalid. Could not convert the days value to an integer.", ex);
49: }
50: }
So you should be able to see we are using simple String.IndexOf() method calls to find out if our Tokens are present.
If they are then we simply calculate the DateTime value based on the static DateTime.UtcNow property and use String.Replace() methods to swap out these into our query text.
When we are using [TODAY+X] or [TODAY-X] we simply use DateTime.UtcNow.AddDays(X) or DateTime.UtcNow.AddDays(0-X) and use the same String.Replace() method.
The search syntax is exactly the same as it was previously, and the Keyword Syntax is very powerful.
Example: Using [TODAY] Token query syntax
Write:[TODAY] – this will return all items that were modified today
Write>[TODAY-7] – this will return all items that were modified in the past week
Write:[TODAY-14]..[TODAY-7] – this will return all items that were modified between 2 weeks ago and 1 week ago
So we already have a powerful and reusable search component .. but there is more!
Step 4 – Making it re-usable Part 2 - Dynamic User Profile Properties
The next one is to allow us to pull in User Profile Properties so that we can start doing searches based on the current user’s profile values.
For this we needed to create new replacable Tokens, for which I decided to use:
- [UPP-{User Profile Property Internal Name}]
- [UPP-PreferredName] (swaps out for the users name)
- [UPP-SPS-Responsibility] (swaps out for their “Ask Me About” values)
- etc ..
private const string USER_PROFILE_PROP_STARTSTRING = "[UPP-";
We can then use this in our code, in exactly the way we did before (using String.IndexOf(), String.SubString() and String.Replace() methods).
So we add the following additional code to our ConfigureDataSourceProperties method;
1: if (dataSource.Query.IndexOf(USER_PROFILE_PROP_STARTSTRING) != -1 &&
2: UserProfileManager.IsAvailable(SPServiceContext.Current))
3: {
4: string strQuery = dataSource.Query;
5:
6: while (strQuery.IndexOf(USER_PROFILE_PROP_STARTSTRING) != -1)
7: {
8: strQuery = ReplaceUserProfilePropertyTokens(strQuery);
9: }
10:
11: if (strQuery != dataSource.Query)
12: {
13: dataSource.Query = strQuery;
14: }
15: }
This uses the additional method call ReplaceUserProfilePropertyTokens which is shown below:
1: private static string ReplaceUserProfilePropertyTokens(string strQuery)
2: {
3: // retrieve the current user's Profile
4: UserProfileManager upm = new UserProfileManager(SPServiceContext.Current);
5: UserProfile profile = upm.GetUserProfile(false);
6:
7: if (profile == null)
8: {
9: throw new ApplicationException("The current user does not have a User Profile");
10: }
11:
12: // extract the user profile property name from the token
13: int startIndex = strQuery.IndexOf(USER_PROFILE_PROP_STARTSTRING);
14: string strPropertyName = strQuery.Substring(startIndex + USER_PROFILE_PROP_STARTSTRING.Length);
15: strPropertyName = strPropertyName.Substring(0, strPropertyName.IndexOf(TOKEN_ENDSTRING));
16:
17: string strToReplace = strQuery.Substring(startIndex);
18: strToReplace = strToReplace.Substring(0, strToReplace.IndexOf(TOKEN_ENDSTRING) + 1);
19:
20: try
21: {
22: // get the value
23: UserProfileValueCollection propertyValue = profile[strPropertyName];
24: string strValues = String.Empty;
25:
26: foreach (object propValue in propertyValue)
27: {
28: if (propValue.ToString().IndexOf(" ") == -1)
29: {
30: strValues += propValue.ToString() + " OR ";
31: }
32: else
33: {
34: strValues += "\"" + propValue.ToString() + "\" OR ";
35: }
36: }
37:
38: if (strValues.Length > 0)
39: {
40: strValues = strValues.Substring(0, strValues.Length - 4);
41: }
42:
43: // swap the value out in the query
44: strQuery = strQuery.Replace(strToReplace, strValues);
45:
46: }
47: catch (ArgumentException ex)
48: {
49: throw new FormatException("The User Profile Property specified in your UPP token does not exist", ex);
50: }
51: return strQuery;
52: }
So there are a few things to point out here which might trip you up:
- We are using the UserProfileManager.IsAvailable() method to find out if we have a user profile service application provisioned and assigned to the current Web Application.
- At the moment this code throws an error if the current user doesn’t have a User Profile. You may want to handle this differently for your environment?
- Handling of multi-value fields. At the moment all we do is take the string values and concatenate them with “OR” in the middle. So if you had “Value1; Value2” as your property value the Token replacement would put “Value1 OR Value2” as the search query.
Example if we now used the Fixed Query:
([UPP-SP-Responsibility]) AND Write:[TODAY-14]..[TODAY]
Then for a user who’s “Ask Me About” properties were “SharePoint” and “IT Administration” then the resulting Search Query would be:
(SharePoint OR “IT Administration”) AND Write:13/05/2012..17/05/2012
If another user comes along whose “Ask Me About” property was just set to “Marketing” then the resulting Search Query would be:
(Marketing) AND Write:13/05/2012..17/05/2012This is without changing any of the web part properties, and allows us to drive dynamic content from a single web part to our entire user base.
Hopefully you can see that this is incredibly powerful and flexible.
Step 5 – Making it re-usable Part 3 – Controllable Sort By
The final step is to allow our content editors to control the “Sort By” functionality. The default OOTB webpart only allows us to sort by “Relevance” or “Last Modified”, which is fine when you are looking at general search results, but when you are building custom components (such as news, links or event feeds) you typically want to control the order by date or title or something a little more usable for the specific component.
So this bolt-in allows you to control the Sort By. First off we need to add some Web Part Properties so that the user can modify their values:
1: [Personalizable(PersonalizationScope.Shared)]
2: [WebBrowsable(true)]
3: [WebDescription("Sort by this managed property")]
4: [WebDisplayName("Managed Property")]
5: [Category("Sort Override")]
6: public string OrderByProperty { get; set; }
7:
8: [Personalizable(PersonalizationScope.Shared)]
9: [WebBrowsable(true)]
10: [WebDescription("Sort direction")]
11: [Category("Sort Override")]
12: public Microsoft.Office.Server.Search.Query.SortDirection SortDirection { get; set; }
This will provide the Web Part property editing functionality:
Once we have done that, we can add the following code to our ConfigureDataSourceProperties method (yes .. this method really is where all of the grunt work goes on in this web part!)
1: // if OrderByProperty is not set, use default behavior
2: if (!string.IsNullOrEmpty(OrderByProperty))
3: {
4: // change the sortorder
5: dataSource.SortOrder.Clear();
6: dataSource.SortOrder.Add(OrderByProperty, SortDirection);
7: }
And that is all there is to it.
Step 6 – Enjoy!
So congratulations if you made it this far. I know this was a long blog post but thought it was worth walking through it properly.
If you have any questions, feedback or questions then please get in touch using the comments, and here are links to the downloads (which are also referenced at the top of this blog post)
Some notes about the “final” version:
- The code structure is slightly different because the DateTime [TODAY] queries are cached using Web Part Properties for better performance
- the [TODAY] token is case sensitive!
- There is an extra “Debug Mode” checkbox in the Web Part Properties which when enabled spits out the entire query being executed at the bottom of the search results.
- Code contains an “Editor Part” .. this just clears out the Cache value when the web part properties are modified
Tokens you can use are:
- [TODAY]
- [TODAY+X] (add X days)
- [TODAY-X] (remove X days)
- [UPP-{Internal Name of User Profile Property}]
Sample user has:ContentType:Event AND ([UPP-SPS-Responsibility]) AND Write:[TODAY-7]..[TODAY]
Name: Martin Hatch
Ask Me About: SharePoint; Solution Architecture; Code
becomes
ContentType:Event AND (SharePoint OR "Solution Architecture" OR Code) AND Write:12/05/2012..17/05/2012
Returns all events which were updated within the past week, and contain the current user's "Ask Me About" values.
Author:[UPP-PreferredName] IsDocument:1
becomes
Author:"Martin Hatch" IsDocument:1
Returns all documents written by the current user
Author:[UPP-PreferredName] Write>=[TODAY-14]
becomes
Author:"Martin Hatch" Write>=02/05/2012
Returns all content created by the current user and updated within the past 2 weeks