Random Musings of Jeremy Jameson https://docs.microsoft.com/archive/blogs/jjameson/feed.xml Wed, 29 Jul 2015 21:04:43 GMT en-US hourly 1 Last Day with Microsoft https://docs.microsoft.com/archive/blogs/jjameson/last-day-with-microsoft Fri, 02 Sep 2011 15:43:00 GMT https://blogs.msdn.microsoft.com/jjameson/2011/09/02/last-day-with-microsoft/ From: Jeremy Jameson
Sent: Friday, September 02, 2011 3:01 PM
To: [snip, snip]
Subject: Last day with Microsoft

Today is my last day with Microsoft and it is with a heavy heart that I now say farewell to past and present teammates, coworkers, and managers.

The last 11 years have been an incredible chapter in my life. Together we have overcome numerous challenges, helped create amazing solutions for our customers, and enjoyed numerous “highs” in the world of technology (and, quite frankly, perservered through the occasional “low” as well).

I’ve learned more in the past decade of my life than perhaps any other, and I wouldn’t trade my decision to join Microsoft for anything (especially considering it put me on the path to meeting my wife and eventually to our daughter). In my time here, I’ve worked with some of the smartest and most talented people I’ve ever known.

I’m not really sure what the next 11 years hold in store for me, but the mere thought that at the end of it, my daughter will be learning how to drive gives me great pause (not to mention the fact that I will then be over 50).

After today, you can reach me via {firstname}_{lastname}@hotmail.com or using my new business email (see below).

Sometimes when I rise out of bed much too early in the morning (such as today) and the world is quiet, I close my eyes and clearly see memories from years ago as if they just happened yesterday. This morning, I was remembering my second day at Microsoft when Ron Stutz told me to head over to J.D. Edwards and help a couple of other Microsoft consultants replace Site Server on their “Knowledge Garden” solution with “Tahoe”. [For those too young to remember, “Tahoe” was the code name for SharePoint Portal Server 2001.]

Since I am far better with technology than I am with prose, I’ll leave you with the following to express how much I appreciate our time together and sincerely hope our paths cross again...

Eventually, all things merge into one, and a river runs through it. The river was cut by the world’s great flood and runs over rocks from the basement of time. On some of the rocks are timeless raindrops. Under the rocks are the words, and some of the words are theirs.

I am haunted by waters.

– Norman Maclean, A River Runs Through It



Jeremy Jameson
[snip, snip]

]]> New Blog Location - https://www.technologytoolbox.com/blog/jjameson https://docs.microsoft.com/archive/blogs/jjameson/new-blog-location-httpwww-technologytoolbox-comblogjjameson Fri, 02 Sep 2011 13:59:38 GMT https://blogs.msdn.microsoft.com/jjameson/2011/09/02/new-blog-location-httpwww-technologytoolbox-comblogjjameson/ As I mentioned in my previous post, today is my last day with Microsoft.

I still have a lot of work to do in setting up my new website, but at this point, I've completed enough to continue blogging the "Random Musings of Jeremy Jameson":

https://www.technologytoolbox.com/blog/jjameson

If you subscribed to my MSDN blog in the past, then I encourage you to update your RSS feed by clicking the Subscribe link on my new blog.

The blog will be in constant flux over the next week or so as I work on branding, layout, etc. So, as they say, please "pardon my dust" ;-)

]]> Leaving Microsoft https://docs.microsoft.com/archive/blogs/jjameson/leaving-microsoft Mon, 22 Aug 2011 07:03:48 GMT https://blogs.msdn.microsoft.com/jjameson/2011/08/22/leaving-microsoft/ Last Thursday, I informed my manager that I have decided to leave Microsoft to pursue other opportunities.

My last day will be September 2nd -- just a few days shy of my 11 year anniversary date with the company (my first day was September 5, 2000).

You might be wondering why I would choose to forgo a steady paycheck, excellent benefits, and four weeks vacation per year -- especially in this economy. (I know my mother certainly questions my sanity at the moment. Fortunately my wife, on the other hand, sincerely understands my decision and respects it -- even though it means that we will need to "cinch up our belts" for some time while I build up my own business.)

It certainly wasn't an easy decision, but it has been one that I've been considering for quite some time.

The reality is that being a Principal Consultant with Microsoft Consulting Services is very challenging. However, if you know me at all, then you know that one of the things I enjoy most is overcoming challenges -- so my decision certainly wasn't based on "burnout" or the desire to get out of the consulting business.

It also wasn't that I was unable to find billable work (in other words, meet my "utilization target" -- which, by the way, was 119% for this past fiscal year). The truth is, prior to my current project (which started in late May), I billed the full rate for a Principal Consultant (i.e. $308.75/hr) at a single customer for 18 months straight -- and no, that wasn't commissioned through one long contract, but rather the result of numerous extensions (made possible by continually delivering a release every six to eight weeks).

Nor was it that I had to travel full-time to work with customers (although that is becoming the norm for many MCS consultants I know). On the contrary, I've been working from home the vast majority of the last five years (since my daughter was born).

So, then why am I leaving Microsoft?

The short answer is that I'm an entrepreneur at heart with a strong passion for leveraging software to help businesses thrive, and while I could have stayed with Microsoft Consulting Services for the foreseeable future, I believe the time is right for change.

If you've engaged my services through Microsoft in the past, then you know that, working together, we can achieve great things. No...not great things, amazing things -- in incredibly short periods of time. If we haven't worked together in the past, but you are looking for top-notch SharePoint/.NET/SQL Server/TFS consulting services, then let's connect so we can discuss how I can help you maximize your investment in Microsoft technology.

I've got a lot to do over the next couple of weeks before my last day -- such as ensuring a smooth transition on my current project, obtaining a business email address other than jjameson@microsoft.com, and finding a new home for my blog (which I promise will see significantly more posts over the coming year than in years past).

I started researching alternative blog services this past weekend, and I'll be sure to update this blog once I know the new location for "Random Musings of Jeremy Jameson."

Until then, you can always reach me via my LinkedIn profile:

https://www.linkedin.com/in/jeremyjameson
]]> Using the SharePoint API to Configure an Expiration Policy on a Document Library https://docs.microsoft.com/archive/blogs/jjameson/using-the-sharepoint-api-to-configure-an-expiration-policy-on-a-document-library Thu, 05 May 2011 07:58:56 GMT https://blogs.msdn.microsoft.com/jjameson/2011/05/05/using-the-sharepoint-api-to-configure-an-expiration-policy-on-a-document-library/ While it typically takes less than a minute or two to configure an expiration policy on a SharePoint document library, there may still be reasons why you want to do this using the SharePoint object model instead.

For example, suppose I have a "Temporary Files" document library for which I want the files to be deleted approximately one day after they are added to the library.

The following C# code shows how to configure an expiration policy on the specified document library (passed as an SPList object):

using Microsoft.Office.RecordsManagement.InformationPolicy;
using Microsoft.SharePoint;
...
        private const string expirationPolicyFeatureId =
            "Microsoft.Office.RecordsManagement.PolicyFeatures.Expiration";

        private static void ConfigureExpirationPolicy(
            SPList tempFilesLibrary)
        {
            Debug.Assert(tempFilesLibrary != null);

            // HACK: Refresh the SPList object in order to avoid
            // the following error when calling Policy.CreatePolicy:
            //
            // "The object has been updated by another user since it was last
            // fetched."
            SPList tempFilesLibrary2 =
                tempFilesLibrary.ParentWeb.Lists[tempFilesLibrary.ID];
            
            SPContentTypeId documentContentTypeId =
                tempFilesLibrary2.ContentTypes.BestMatch(
                    SPBuiltInContentTypeId.Document);

            SPContentType documentContentType =
                tempFilesLibrary2.ContentTypes[documentContentTypeId];

            Debug.Assert(documentContentType != null);
            
            Policy policy = Policy.GetPolicy(documentContentType);

            if (policy == null)
            {
                Policy.CreatePolicy(documentContentType, null);
                policy = Policy.GetPolicy(documentContentType);
            }

            if (policy.Items[expirationPolicyFeatureId] == null)
            {
                string customData =
"<data>"
    + "<formula id=\"Microsoft.Office.RecordsManagement.PolicyFeatures.Expiration.Formula.BuiltIn\">"
        + "<number>1</number>"
        + "<property>Created</property>"
        + "<period>days</period>"
    + "</formula>"
    + "<action type=\"action\" id=\"Microsoft.Office.RecordsManagement.PolicyFeatures.Expiration.Action.MoveToRecycleBin\" />"
+ "</data>";

                policy.Items.Add(expirationPolicyFeatureId, customData);
            }
        }

This code adds an expiration policy to the library if it hasn't yet been configured. If an expiration policy has been configured on the document library, then it it ignored (because the policy may have been modified by an administrator -- for example, to increase the time period used to determine which files to delete).

Note

As shown in the HACK comment above, I fetch a new SPList object in order to avoid the following error when configuring the expiration policy immediately after creating a new document library:

The object has been updated by another user since it was last fetched.

This error occurred in Microsoft Office SharePoint Server (MOSS) 2007 -- although I just ran a quick test in SharePoint 2010 and it looks like this may no longer be an issue in the new version.

In my next post, I'll explain more about storing files temporarily in SharePoint.

]]> Missing thumbnail images in SharePoint?...You probably forgot to specify the "ContentType" property https://docs.microsoft.com/archive/blogs/jjameson/missing-thumbnail-images-in-sharepoint-you-probably-forgot-to-specify-the-contenttype-property Mon, 02 May 2011 06:33:08 GMT https://blogs.msdn.microsoft.com/jjameson/2011/05/02/missing-thumbnail-images-in-sharepoint-you-probably-forgot-to-specify-the-contenttype-property/ During the process of creating my previous post, I discovered the thumbnail images were not rendering as expected for the custom images that I added to the out-of-the-box SharePoint /PublishingImages picture library (via a feature).

Here is the content of my original Elements.xml file (used to add the images to the library):

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <Module
    Name="HomeSiteImages"
    Url="PublishingImages"
    Path="HomeSiteConfiguration\PublishingImages">
    <File Url="boat.jpg" Type="GhostableInLibrary"/>
    <File Url="fame.jpg" Type="GhostableInLibrary"/>
    <File Url="ropes.jpg" Type="GhostableInLibrary"/>
  </Module>
</Elements>

To get the thumbnails to render as expected, I simply modified the Elements.xml file as follows:

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <Module
    Name="HomeSiteImages"
    Url="PublishingImages"
    Path="HomeSiteConfiguration\PublishingImages">
    <File Url="boat.jpg" Type="GhostableInLibrary">
      <Property Name="ContentType"
        Value="$Resources:cmscore,contenttype_image_name;" />
    </File>
    <File Url="fame.jpg" Type="GhostableInLibrary">
      <Property Name="ContentType"
        Value="$Resources:cmscore,contenttype_image_name;" />
    </File>
    <File Url="ropes.jpg" Type="GhostableInLibrary">
      <Property Name="ContentType"
        Value="$Resources:cmscore,contenttype_image_name;" />
    </File>
  </Module>
</Elements>

By simply adding the ContentType property (and setting it to "Image"), SharePoint automatically creates the corresponding thumbnail for each image when adding the item to the picture library.

]]> Web Standards Design with SharePoint, Part 6 https://docs.microsoft.com/archive/blogs/jjameson/web-standards-design-with-sharepoint-part-6 Mon, 02 May 2011 05:28:00 GMT https://blogs.msdn.microsoft.com/jjameson/2011/05/02/web-standards-design-with-sharepoint-part-6/ In part 5 of this series, I showed how you can render semantic HTML for SharePoint list items (instead of the out-of-the-box table layout) using the new XsltListViewWebPart in SharePoint 2010.

Note
You can achieve similar results in Microsoft Office SharePoint Server (MOSS) 2007 using the DataViewWebPart.

For those of you that haven't yet read my previous post, the goal was to take a SharePoint list like the one shown below...

Figure 1: Specials list
See full-sized image.

...and subsequently render the list items as an HTML ordered list:

<h2>This Week's Specials</h2>
<ol class='specials group'>
    <li class='group'>
        <div class='special'>
            <div class='special-img'>
                <a href='#'>
                    <img src='/PublishingImages/boat.jpg' alt='coffee' />
                    <span><strong>Fisherman&#8217;s Brew</strong>
                        <em>$9.98 / lb.</em></span></a>
            </div>
        </div>
    </li>
    <li class='group'>
        <div class='special'>
            <div class='special-img'>
                <a href='#'>
                    <img src='/PublishingImages/ropes.jpg' alt='coffee' />
                    <span><strong>Boathouse Bold</strong>
                        <em>$12.50 / lb.</em></span></a>
            </div>
        </div>
    </li>
    <li class='group third'>
        <div class='special'>
            <div class='special-img'>
                <a href='#'>
                    <img src='/PublishingImages/fame.jpg' alt='coffee' />
                    <span><strong>Deadly Decaf</strong>
                        <em>$7.49 / lb.</em></span></a>
            </div>
        </div>
    </li>
</ol>

After replacing the static HTML for the weekly specials section with an XsltListViewWebPart (and specifying the necessary XSL to transform the SharePoint list items into the desired HTML), the content on the Tugboat home page no longer needs to be updated directly. Instead, new items can be added to the custom Specials list (or existing items updated) in order to dynamically update the content on the home page.

However, as I mentioned at the end of my previous post, there's a problem. What happens if the number of items in the list is greater than the expected number? The following screenshot shows the updated home page content after adding a fourth item to the Specials list.

Figure 2: Too many items in the weekly specials section
See full-sized image.

While we could modify the XSLT to only render the first three items from the SharePoint list, this really isn't the best implementation choice. A better way of limiting the number of list items rendered in the weekly specials section is to use a custom view on the underlying list (instead of rendering items based on the default All Items view).

Let's suppose that in addition to restricting the number of weekly specials displayed on the home page (to three items), we also want to show the most recent items first.

To achieve the two goals, start by creating a new view on the Specials list using the following parameters:

  • Name: Most Recent Specials
  • Web address of this view: MostRecent
  • Columns:
    • Title
    • Unit Price
    • Unit of Measure
    • Price
    • Rollup Image
  • Sort
    • First sort by the column: Modified
    • Show items in descending order
  • Item Limit
    • Number of items to display: 3
    • Limit the total number of items returned to the specified amount.

Once we change the XsltListViewWebPart on the home page to use the Most Recent Specials view, the weekly specials section renders as expected regardless of the number of items in the Specials list.

Figure 3: Using the "Most Recent Specials" view (instead of "All Items") renders the home page as expected
See full-sized image.

Now that we have the XsltListViewWebPart rendering the desired HTML, we can turn our attention to automatically creating the Specials list (as well as the custom view), populating the list with default items, and adding an instance of the XsltListViewWebPart to the home page.

Creating the Custom List

While you could create the Specials list via a feature using CAML, I prefer to create custom SharePoint lists using code instead. The reason is because business requirements invariably change over time and I find it much easier to start out with code since it seems almost inevitable that you'll be programmatically manipulating SharePoint lists anyway.

Here's the code I wrote to create automatically create and configure the new Specials list:

        private static void ConfigureSpecialsList(
            SPWeb web)
        {
            Debug.Assert(web != null);

            SPList list = SharePointListHelper.EnsureList(
                web,
                "Lists/Specials",
                SPListTemplateType.GenericList,
                "Specials",
                "Items in this list appear in the \"This Week's Specials\""
                    + " section of the site home page.");

            Debug.Assert(list != null);

            SPField unitPriceField = SharePointListHelper.EnsureField(
                list,
                "UnitPrice",
                "Unit Price",
                SPFieldType.Currency,
                true);

            StringCollection unitOfMeasureChoices = new StringCollection();
            
            const string defaultUnitOfMeasureChoice = "/ lb.";
            unitOfMeasureChoices.Add(defaultUnitOfMeasureChoice);
            
            unitOfMeasureChoices.Add("ea.");

            SPFieldChoice unitOfMeasureField =
                (SPFieldChoice) SharePointListHelper.EnsureField(
                    list,
                    "UnitOfMeasure",
                    "Unit of Measure",
                    SPFieldType.Choice,
                    true,
                    string.Empty,
                    unitOfMeasureChoices);

            unitOfMeasureField.DefaultValue = defaultUnitOfMeasureChoice;
            unitOfMeasureField.Update();

            SPFieldCalculated priceField =
                (SPFieldCalculated) SharePointListHelper.EnsureField(
                    list,
                    "Price",
                    "Price",
                    SPFieldType.Calculated);

            priceField.Formula =
                "= DOLLAR([Unit Price]) & \" \" & [Unit of Measure]";

            priceField.Update();

            SPField rollupImageField = web.AvailableFields[FieldId.RollupImage];
            rollupImageField.Required = true;

            SharePointListHelper.EnsureField(list, rollupImageField);

            string[] defaultViewFields = new string[] {
                    list.Fields[SPBuiltInFieldId.Title].Title,
                    unitPriceField.Title,
                    unitOfMeasureField.Title,
                    priceField.Title,
                    rollupImageField.Title
                };

            ConfigureViewsForSpecialsList(
                list,
                defaultViewFields);

            if (list.ItemCount == 0)
            {
                CreateDefaultItemsInSpecialsList(list);
            }
        }

Note that I use a separate method to configure the default views for the new list:

        private static void ConfigureViewsForSpecialsList(
            SPList list,
            string[] fields)
        {
            Debug.Assert(list != null);
            Debug.Assert(fields != null);
            Debug.Assert(fields.Length > 0);

            // Configure "All Items" view
            SPView allItems = SharePointViewHelper.EnsureView(
                list,
                "All Items",
                fields,
                "AllItems");

            SharePointViewHelper.EnsureViewFields(
                allItems,
                fields);
            
            // Configure "Most Recent Specials" view
            SPView mostRecentSpecials = SharePointViewHelper.EnsureView(
                list,
                "Most Recent Specials",
                fields,
                "MostRecent");

            SharePointViewHelper.EnsureDefaultView(mostRecentSpecials);

            SharePointViewHelper.EnsureViewQuery(
                mostRecentSpecials,
                "<OrderBy>"
                    + "<FieldRef Name='Modified' Ascending='FALSE' />"
                + "</OrderBy>");

            if (mostRecentSpecials.Paged != false
                || mostRecentSpecials.RowLimit != 3)
            {
                mostRecentSpecials.Paged = false;
                mostRecentSpecials.RowLimit = 3;
                mostRecentSpecials.Update();
            }
        }

Adding the Default Items to the List

I populate the default list items using a couple of other helper methods (but only if the list is empty upon activation of the feature -- in order to avoid adding duplicate items to the list):

        private static void CreateDefaultItemsInSpecialsList(
            SPList list)
        {
            Debug.Assert(list != null);

            CreateDefaultItemInSpecialsList(
                list,
                "Fisherman's Brew",
                9.98,
                "/ lb.",
                "/PublishingImages/boat.jpg");

            CreateDefaultItemInSpecialsList(
                list,
                "Boathouse Bold",
                12.50,
                "/ lb.",
                "/PublishingImages/ropes.jpg");

            CreateDefaultItemInSpecialsList(
                list,
                "Deadly Decaf",
                7.49,
                "/ lb.",
                "/PublishingImages/fame.jpg");
        }
 
        private static void CreateDefaultItemInSpecialsList(
            SPList list,
            string title,
            double unitPrice,
            string unitOfMeasure,
            string rollupImageUrl)
        {
            Debug.Assert(list != null);
            Debug.Assert(string.IsNullOrEmpty(title) == false);
            Debug.Assert(unitPrice > 0);
            Debug.Assert(string.IsNullOrEmpty(unitOfMeasure) == false);
            Debug.Assert(string.IsNullOrEmpty(rollupImageUrl) == false);

            SPListItem item = list.Items.Add();

            item[SPBuiltInFieldId.Title] = title;
            item["Unit Price"] = unitPrice;
            item["Unit of Measure"] = unitOfMeasure;

            ImageFieldValue rollupImage = new ImageFieldValue();
            rollupImage.ImageUrl = rollupImageUrl;

            item[FieldId.RollupImage] = rollupImage;

            item.Update();
        }

There are certainly other ways to avoid adding duplicate items to a list, but this method is straightforward and sufficient for this scenario.

Adding the XsltListViewWebPart to the Home Page

In order to add the new XsltListViewWebPart to the home page, I modified the existing ConfigureHomeSiteDefaultPage method that I created previously:

        private static void ConfigureHomeSiteDefaultPage(
            SPWeb homeWeb)
        {
            ...

            // Configure Web Parts
            SPWebPartPages.SPLimitedWebPartManager wpm =
                homeWeb.GetLimitedWebPartManager(
                    page.Url,
                    PersonalizationScope.Shared);

            using (wpm)
            {
                string zoneId = "TopLeftZone";
                int zoneIndex = 0;

                SharePointWebPartHelper.EnsureWebPart(
                    wpm,
                    "FindLocation",
                    "Tugboat_FindLocation.webpart",
                    zoneId,
                    ref zoneIndex);

                ConfigureSpecialsWebPart(wpm, zoneId, ref zoneIndex);

                ...
            }

            SharePointPublishingHelper.PublishPage(
                page,
                "Published by Tugboat.Web.HomeSiteConfiguration"
                    + " feature.");
            
        }

The new ConfigureSpecialsWebPart method is shown below:

        private static void ConfigureSpecialsWebPart(
            SPWebPartPages.SPLimitedWebPartManager wpm,
            string zoneId,
            ref int zoneIndex)
        {
            Debug.Assert(wpm != null);
            Debug.Assert(string.IsNullOrEmpty(zoneId) == false);

            SPList specialsList = wpm.Web.Lists["Specials"];
            SPView mostRecentSpecialsView =
                specialsList.Views["Most Recent Specials"];

            WebPart webPart = SharePointWebPartHelper.FindWebPartByTitle(
                wpm,
                "Specials");

            SPWebPartPages.XsltListViewWebPart specials =
                webPart as SPWebPartPages.XsltListViewWebPart;

            if (specials == null)
            {
                specials = new SPWebPartPages.XsltListViewWebPart();
                specials.Title = "Specials";

                specials.ListId = specialsList.ID;

                wpm.AddWebPart(specials, zoneId, zoneIndex);
                zoneIndex++;
            }
            else
            {
                specials.ListId = specialsList.ID;
            }

            specials.ChromeType = PartChromeType.None;
            specials.ViewGuid = mostRecentSpecialsView.ID.ToString();

            Assembly thisAssembly = Assembly.GetExecutingAssembly();

            specials.Xsl = AssemblyHelper.GetEmbeddedResourceAsString(
                thisAssembly,
                "Tugboat.Web.HomeSiteConfiguration.Xsl.Specials.xslt");

            wpm.SaveChanges(specials);

            specials.Dispose();
        }

Deploying the Sample Solution

I've attached an updated version of the Tugboat solution in case you are interested in seeing the changes to render the weekly specials from a SharePoint list.

Here are the instructions to deploy the Tugboat sample to your own SharePoint environment. First, download the attachment and unzip the files. Then you simply need to create a few domain users and run a handful of PowerShell scripts, as described below.

To deploy the Tugboat solution to SharePoint:

  1. Create three service accounts for the Tugboat site:
    • {DOMAIN}\svc-web-tugboat-dev - used as the application pool identity for the new Tugboat site
    • {DOMAIN}\svc-sp-psr-dev - object cache user account providing Full Read access to Web applications (https://technet.microsoft.com/en-us/library/ff758656.aspx)
    • {DOMAIN}\svc-sp-psu-dev - object cache user account providing Full Control access to Web applications
  2. On the Start menu, click All Programs, click Microsoft SharePoint 2010 Products, right-click SharePoint 2010 Management Shell, and then click Run as administrator. If prompted by User Account Control to allow the program to make changes to the computer, click Yes.
  3. From the Windows PowerShell command prompt, change to the directory containing the deployment scripts (e.g. C:\NotBackedUp\Tugboat\Main\Source\DeploymentFiles\Scripts), and run the following commands:
    $env:TUGBOAT_URL = "https://tugboatcoffee-local"
    $env:TUGBOAT_BUILD_CONFIGURATION = "Debug"
    & '.\Rebuild Web Application.ps1'
Note
Technically, you don't have to set the environment variables (and use the "-dev" accounts). However, I recommend this in order to bypass SharePoint timer jobs when deploying the WSPs.

At this point you should be able to modify your hosts file accordingly and browse to either https://www-local.tugboatcoffee.com (to view the site as an anonymous user) or https://tugboatcoffee-local (to view the site as an administrator).

Additional Resources

Here are some additional resources that you may find helpful for rendering SharePoint list items using the XsltListViewWebPart.

XsltListViewWebPart and Custom List Views
https://msdn.microsoft.com/en-us/library/ff806162.aspx
Overview of XSLT List View Rendering System
https://msdn.microsoft.com/en-us/library/ff604024.aspx
Examples of Input and Result Node Trees in XSLT Transformations
https://msdn.microsoft.com/en-us/library/ff602042.aspx
How to: Customize the Rendering of a Field on a List View
https://msdn.microsoft.com/en-us/library/ff606773.aspx

Tugboat - 1.0.58.0.zip

]]> Web Standards Design with SharePoint, Part 5 (a.k.a. Rendering Semantic HTML Using the XsltListViewWebPart) https://docs.microsoft.com/archive/blogs/jjameson/web-standards-design-with-sharepoint-part-5-a-k-a-rendering-semantic-html-using-the-xsltlistviewwebpart Wed, 27 Apr 2011 08:33:00 GMT https://blogs.msdn.microsoft.com/jjameson/2011/04/27/web-standards-design-with-sharepoint-part-5-a-k-a-rendering-semantic-html-using-the-xsltlistviewwebpart/ In part 4 of this series, I provided a sample SharePoint Server 2010 solution solution based on Dan Cederholm's Tugboat sample site (from his most recent book, Handcrafted CSS : More Bulletproof Web Design).

In that sample, however, all of the content on the home page of the site is rendered as static HTML. In other words, it doesn't truly leverage the power of SharePoint in order to make the site dynamic based on content stored throughout the site.

In this post, I'll show you how to take a small part of the home page (specifically This Week's Specials) and render it from items specified in a SharePoint list.

In case you aren't yet familiar with the Tugboat sample site, the following screenshot shows the site home page.

Figure 1: Tugboat - Home page
See full-sized image.

When I put on my "SharePoint Architect" hat and look at the content in the This Week's Specials section, I see a SharePoint list with columns like Title (e.g. "Fisherman's Brew"), Price (e.g. "$9.98 / lb."), and Rollup Image (e.g. "/PublishingImages/boat.jpg").

Depending on the size of the fictitious Tugboat Coffee company, we might choose to use the Business Connectivity Services in SharePoint 2010 to pull this data from some external system. However, for the sake of this sample, let's assume that Tugboat isn't anywhere near being considered a threat to Starbucks, and we want to start out by managing the "weekly specials" using a simple SharePoint list.

Let's start by designing the custom SharePoint list used to specify the data for the weekly specials.

My decision to use the Title and Rollup Image columns should be relatively straightforward. When you create a custom list in SharePoint, you get a Title column by default (so it just makes sense to use that for the name of the product). Similarly, the Publishing Image column type (used for the Rollup Image column) provides the best user experience for selecting an image from the SharePoint site (as opposed to creating a custom column using the Hyperlink or Picture column type).

However, we need to think a little bit about the Price column. We could certainly choose to add a custom column using the Single line of text column type, which would contain values like "$9.98 / lb." However, besides putting an unnecessary burden on the people maintaining the data in the list -- because they would need to explicitly type in the currency symbol and unit of measure when adding new items to the list -- using a Single line of text column type for the price wouldn't really be leveraging the full power of SharePoint. It would also allow for mistakes like:

  • "9.98 / lb." (no currency symbol)
  • "$9.98" (missing " / lb." from the price)
  • "$9.98/lb." (no spaces)
  • "$9.98 /lb." (inconsistent spacing)
  • "$9.98 / lb" (missing period on the abbreviation)
  • "$9.98 / bl." (yikes, what is a "bl."?!)

Therefore, let's instead break the price into two parts: Unit Price and Unit of Measure. We can then use a calculated column for Price (in order to concatenate the values specified in the other two columns).

Data for "This Week's Specials"
TitleUnit PriceUnit of MeasurePriceRollup Image
Fisherman's Brew $9.98 / lb. $9.98 / lb. /PublishingImages/boat.jpg
Boathouse Bold $12.50 / lb. $12.50 / lb. /PublishingImages/ropes.jpg
Deadly Decaf $7.49 / lb. $7.49 / lb. /PublishingImages/fame.jpg

Here's a breakdown of the custom SharePoint list:

  • Name: Specials
  • Description: Items in this list appear in the "This Week's Specials" section of the site home page.
  • Columns:
    • Title (Single line of text, Required)
    • Unit Price (Currency, Required)
    • Unit of Measure (Choice, Required)
      • Choices:
        • / lb. (default value)
        • ea.
    • Price (Calculated)
      • Formula:
        • =DOLLAR([Unit Price]) & " " &[Unit of Measure]
    • Rollup Image (Publishing Image, Required)
    • Created By (Person or Group)
    • Modified By (Person or Group)
Important
Even though the Unit Price column is defined using the Currency type and specifies a Currency format of $123,456.00 (United States), you must specify the DOLLAR function in the formula for the calculated column. Otherwise, the values in the Price column would not appear as expected (e.g. "12.5 / lb.").
Note
I chose to name the list "Specials" instead of "Weekly Specials" for a reason. If this were a real world solution, then there would be a significant chance the business rules would change over time (for example to show "Today's Specials" or "This Month's Specials"). By simply naming the list "Specials", we can avoid tightly coupling the implementation to the current business rules.

Assuming you are proficient in SharePoint, within a matter of a few minutes you should be able to create the list and populate the sample data shown in the following screenshot.

Figure 2: Specials list
See full-sized image.

The next step is to render the items in the list using the semantic markup previously specified using static HTML. In other words, instead of rendering the SharePoint list items in a table, we need to render them using an ordered list (along with the corresponding CSS class names):

<h2>This Week's Specials</h2>
<ol class='specials group'>
    <li class='group'>
        <div class='special'>
            <div class='special-img'>
                <a href='#'>
                    <img src='/PublishingImages/boat.jpg' alt='coffee' />
                    <span><strong>Fisherman&#8217;s Brew</strong>
                        <em>$9.98 / lb.</em></span></a>
            </div>
        </div>
    </li>
    <li class='group'>
        <div class='special'>
            <div class='special-img'>
                <a href='#'>
                    <img src='/PublishingImages/ropes.jpg' alt='coffee' />
                    <span><strong>Boathouse Bold</strong>
                        <em>$12.50 / lb.</em></span></a>
            </div>
        </div>
    </li>
    <li class='group third'>
        <div class='special'>
            <div class='special-img'>
                <a href='#'>
                    <img src='/PublishingImages/fame.jpg' alt='coffee' />
                    <span><strong>Deadly Decaf</strong>
                        <em>$7.49 / lb.</em></span></a>
            </div>
        </div>
    </li>
</ol>

Start SharePoint Designer 2010 and open the site containing the Specials list. In the Site Objects pane, click Site Pages. In the ribbon, click Web Part Page and then select the first page layout (i.e. the layout with exactly one Web Part zone) to create a new page (Untitled_1.aspx).

Click the new page to view the settings for the page. In the Customization section, click Edit file.

In the page editor, in the Insert tab on the ribbon, click Data View and then click Specials to insert a new Web Part. Select the List View Web Part, click the Design tab on the ribbon, click Customize XSLT, and then click Customize Entire View.

Switch to the Code view for the page and locate the <WebPartPages:XsltListViewWebPart> element. Right-click the <xsl:stylehsheet> element within the <xsl> element for the Web Part, click Select Tag, and then delete the default XSL stylesheet.

Note that the XsltListViewWebPart provides a <dsQueryResponse> XML document containing the items from underlying the SharePoint list. Each list item is represented as a row:

<dsQueryResponse ViewStyleID="" BaseViewID="1" TemplateType="100" RowLimit="30">
  <Rows>
    <Row ID="1"
      PermMask="0x7fffffffffffffff"
      Title="Fisherman&amp;#39;s Brew"
      UnitPrice="$9.98" UnitPrice.="9.98000000000000"
      UnitOfMeasure="/ lb."
      Price="9.98 / lb."
      PublishingRollupImage="&lt;img alt=&quot;&quot; src=&quot;/PublishingImages/boat.jpg&quot; style=&quot;border:px solid&quot; /&gt;" />
    <Row ID="2"
      PermMask="0x7fffffffffffffff"
      Title="Boathouse Bold"
      UnitPrice="$12.50"
      ... />
    <Row ID="3"
      PermMask="0x7fffffffffffffff"
      Title="Deadly Decaf"
      ... />
  </Rows>
</dsQueryResponse>
Tip
To view the "raw" XML document, insert the XSLT identity transform into the <xsl> element of the XsltListViewWebPart, save the page, and then browse to the page in Internet Explorer.

At this point, I recommend using Visual Studio to create two files (e.g. Specials.xml and Specials.xslt) for development purposes. Paste the data that you want to transform into the XML file (i.e. the <dsQueryResponse> document). Then iterate on the XSLT file until you get the final HTML that you are looking for.

Since we know that we want to generate HTML from the XML document, start by specifying the corresponding output element and a template that simply emits a heading:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="https://www.w3.org/1999/XSL/Transform"
  xmlns:msxsl="urn:schemas-microsoft-com:xslt"
  exclude-result-prefixes="msxsl">

  <xsl:output method='html' indent='yes'/>

  <xsl:template match='dsQueryResponse'>
    <h2>This Week's Specials</h2>
  </xsl:template>
</xsl:stylesheet>

Next, enhance the dsQueryResponse template to output an ordered list. Add a second XSL template to render a list item element containing the value of the Title field for each "row" of data (in other words, for each SharePoint list item):

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="https://www.w3.org/1999/XSL/Transform"
  xmlns:msxsl="urn:schemas-microsoft-com:xslt"
  exclude-result-prefixes="msxsl">

  <xsl:output method='html' indent='yes'/>

  <xsl:template match='dsQueryResponse'>
    <h2>This Week's Specials</h2>
    <ol class='specials group'>
      <xsl:apply-templates select='Rows/Row'/>
    </ol>
  </xsl:template>

  <xsl:template match='Row'>
    <li>
      <xsl:value-of select='@Title'/>
    </li>
  </xsl:template>
</xsl:stylesheet>

At this point, the HTML rendered by the XsltListViewWebPart is:

This Week’s Specials

  1. Fisherman&#39;s Brew
  2. Boathouse Bold
  3. Deadly Decaf

As you can see, we need to tweak the XSLT a little bit in order to render special characters as expected (such as an encoded apostrophe). This is simply a matter of adding the disable-output-escaping attribute:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="https://www.w3.org/1999/XSL/Transform"
  xmlns:msxsl="urn:schemas-microsoft-com:xslt"
  exclude-result-prefixes="msxsl">

  <xsl:output method='html' indent='yes'/>

  <xsl:template match='dsQueryResponse'>
    <h2>This Week's Specials</h2>
    <ol class='specials group'>
      <xsl:apply-templates select='Rows/Row'/>
    </ol>
  </xsl:template>

  <xsl:template match='Row'>
    <li>
      <xsl:value-of select='@Title' disable-output-escaping='yes'/>
    </li>
  </xsl:template>
</xsl:stylesheet>

Now that we have the basic implementation working, let's replace the content of the <li> element with the actual markup from the static HTML, and replace the various pieces of content with corresponding placeholders:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="https://www.w3.org/1999/XSL/Transform"
  xmlns:msxsl="urn:schemas-microsoft-com:xslt"
  exclude-result-prefixes="msxsl">

  <xsl:output method='html' indent='yes'/>

  <xsl:template match='dsQueryResponse'>
    <h2>This Week's Specials</h2>
    <ol class='specials group'>
      <xsl:apply-templates select='Rows/Row'/>
    </ol>
  </xsl:template>

  <xsl:template match='Row'>
    <li class='group'>
      <div class='special'>
        <div class='special-img'>
          <a href='#'>
            <xsl:value-of select='@PublishingRollupImage'
                disable-output-escaping ='yes'/>
            <xsl:text> </xsl:text>
            <span>
              <strong>
                <xsl:value-of select='@Title' disable-output-escaping ='yes'/>
              </strong>
              <xsl:text> </xsl:text>
              <em>
                <xsl:value-of select='@Price'/>
              </em>
            </span>
          </a>
        </div>
      </div>
    </li>
  </xsl:template>
</xsl:stylesheet>

At this point, our HTML is very close to what we want it to be:

This Week’s Specials

  1. Fisherman's Brew $9.98 / lb.
  2. Boathouse Bold $12.50 / lb.
  3. Deadly Decaf $7.49 / lb.

Obviously the image URLs are invalid (outside the context of the SharePoint site -- due to server-relative URLs), but that's okay...the images should appear as soon as we view this within the actual SharePoint site.

However, there is still one minor discrepancy between the dynamic HTML generated using the above XSLT and the original static HTML created by Dan. The problem is that the third list item needs to have an additional CSS class name specified (in other words, for the last item in the list we need to render <li class="group third"> instead of <li class="group">).

Fortunately, this is very easy to achieve using a little more XSLT. Here is the final version of the XSL stylesheet that I developed to render items in the Specials list to match the original HTML specified by the Web designer (Dan):

<xsl:stylesheet version='1.0'
    xmlns:xsl='https://www.w3.org/1999/XSL/Transform'
    xmlns:msxsl='urn:schemas-microsoft-com:xslt'
    xmlns:ddwrt2='urn:frontpage:internal'
    exclude-result-prefixes='msxsl'>
  <xsl:output method='html' indent='yes'/>
  <xsl:template match='dsQueryResponse'>
    <h2>This Week's Specials</h2>
    <ol class='specials group'>
      <xsl:apply-templates select='Rows/Row'/>
    </ol>
  </xsl:template>

  <xsl:template match='Row'>
    <li>
      <xsl:choose>
        <xsl:when test='position() = 3'>
          <xsl:attribute name='class'>group third</xsl:attribute>
        </xsl:when>
        <xsl:otherwise>
          <xsl:attribute name='class'>group</xsl:attribute>
        </xsl:otherwise>
      </xsl:choose>
      <div class='special'>
        <div class='special-img'>
          <a href='#'>
            <xsl:value-of select='@PublishingRollupImage'
                disable-output-escaping ='yes'/>
            <xsl:text> </xsl:text>
            <span>
              <strong>
                <xsl:value-of select='@Title' disable-output-escaping ='yes'/>
              </strong>
              <xsl:text> </xsl:text>
              <em>
                <xsl:value-of select='@Price'/>
              </em>
            </span>
          </a>
        </div>
      </div>
    </li>
  </xsl:template>
</xsl:stylesheet>

Copy this into the the <xsl> element for the Web Part (using SharePoint Designer) and save the page. Then view the page in Internet Explorer to verify that it renders the expected HTML.

Once you have a test page rendering the SharePoint list items using the HTML you want (rather than the out-of-the-box table-based layout), you can export the Web Part to a .webpart file and subsequently import it onto the home page (at which point, the custom Tugboat CSS rules will be applied and the content should exactly match the static HTML previously used to render This Week's Specials).

There's still quite a bit I want to cover on this topic, but I need to move on to my "day job". In my next post, I'll show you how to programmatically configure the Specials list (yep, you guessed it...upon feature activation), add some sample items to the list, and replace the static HTML content on the home page with an instance of the XsltListViewWebPart configured with the custom XSLT.

There are also some "bugs" in this new solution. For example, what happens if there are more than three items in the Specials list? Don't worry, this is easy to fix -- thanks to the power of SharePoint.

Stay tuned...

Update (2011-05-02)
The next post in this series is now available.
]]> Script to Reset WSUS for SysPrep'ed Image https://docs.microsoft.com/archive/blogs/jjameson/script-to-reset-wsus-for-syspreped-image Mon, 25 Apr 2011 05:03:15 GMT https://blogs.msdn.microsoft.com/jjameson/2011/04/25/script-to-reset-wsus-for-syspreped-image/ Here's a useful script for those, like me, that use SysPrep'ed images to create new virtual machines and also leverage Windows Server Update Services (WSUS) to keep machines up-to-date with the latest patches.

Reset WSUS for SysPrep Image.cmd

net stop wuauserv

reg.exe delete HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate /v PingID /f
reg.exe delete HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate /v AccountDomainSid /f
reg.exe delete HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate /v SusClientId /f
reg.exe delete HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate /v SusClientIDValidation /f

net start wuauserv

wuauclt.exe /resetauthorization /detectnow

I keep a copy of this script in my Toolbox and run it after creating a new VM from a SysPrep'ed image.

If you are not sure why this is helpful, refer to the following KB article:

A Windows 2000-based, Windows Server 2003-based, or Windows XP-based computer that was set up by using a Windows 2000, Windows Server 2003, or Windows XP image does not appear in the WSUS console
https://support.microsoft.com/kb/903262/en-us
]]> Reusable Content in SharePoint Publishing HTML Fields, Part 3 https://docs.microsoft.com/archive/blogs/jjameson/reusable-content-in-sharepoint-publishing-html-fields-part-3 Thu, 14 Apr 2011 06:56:00 GMT https://blogs.msdn.microsoft.com/jjameson/2011/04/14/reusable-content-in-sharepoint-publishing-html-fields-part-3/ In part 2 of this series, I explained how to programmatically add a new Reusable Content list item and subsequently add it to a Publishing HTML field on a page. I also provided a complete sample for SharePoint 2010 that demonstrates how this can be accomplished with minimal effort (thanks to some nitfy helper classes).

However, depending on your specific business requirements, creating a SharePoint page that leverages reusable content may only be half the battle. What if you need to get that content out of SharePoint?

For example, in part 1 of this series, I mentioned how I previously built a custom "document publishing" system based on the WCM features in SharePoint. In the first sprint of that effort, one of the core scenarios was exporting a SharePoint site (typically containing about a hundred pages of content) to a PDF file. We call this the "Export to PDF" feature. In the current sprint, I've been working on an enhancement to export the documents to an external system (so clients can view a copy of the content stored in that other system). We call this the "Export to {external system}" feature. [I've substituted the name of the actual system with a placeholder to protect the innocent ;-) ]

The "Export to PDF" feature was originally built with very little code. [You may recall that I previously stated this solution had to be delivered to Production in four weeks.]

Essentially, I wrote a little bit of code to "aggregate" all of the pages in a specific SharePoint site into one large HTML document. The solution then uses Prince (in combination with some custom cascading style sheets I created) to convert the HTML file into a commercial-quality PDF file.

The "Export to PDF" process typically takes between 10-15 seconds (which seems very reasonable given that some of the resulting PDF documents can exceed 100 printed pages). Consequently, I implemented this using a "long running page" in SharePoint (you know, one of those application pages with the "spinning wheel" that says something like "Please wait while...").

The most important aspect of the "Export to PDF" feature -- with regards to reusable content -- is that it runs within the context of a SharePoint HTTP request. In other words, when SPContext.Current is not null. During that original sprint, I discovered that it is actually quite trivial to "expand" the reusable content placeholders in Publishing HTML fields when SPContext.Current is not null. On the other hand, when SPContext.Current is null, it takes a fair amount of custom code to retrieve the same content. More on that in a moment.

Let's start with the simplest scenario first...

"Expanding" reusable content placeholders when SPContext.Current is not null

When you need to get the HTML content from a SharePoint page and SPContext.Current is not null (i.e. your code is running in the context of a SharePoint HTTP request), then you can simply use the HtmlField.GetFieldValueAsHtml method, as shown below:

    HtmlField pageContentField =
        (HtmlField) page.Fields[FieldId.PublishingPageContent];

    string pageContent = pageContentField.GetFieldValueAsHtml(
        page.ListItem[FieldId.PublishingPageContent]);

If you look at this method with Reflector, you'll see that most of the work is actually done by the HtmlEditorInternal class.

If SPContext.Current is null, then a NullReferenceException is thrown in the HtmlEditorInternal.ConvertStorageFormatToViewFormat method (due to an attempt to reference SPContext.Current.Site).

When developing the original "Export to PDF" solution, I implemented a hack to insert a warning message in the underlying HTML when SPContext.Current is null. [Note that I tend to write as much code as a I can outside the context of a Web request -- for example, by writing unit tests that invoke the core services underlying the presentation layer.]

The original code looked like this:

                if (pageContent.Contains("__publishingReusableFragment") == true)
                {
                    // HACK: We need to "expand" the reusable content in order
                    // to obtain the complete HTML page content. Unfortunately,
                    // SharePoint does not currently provide an easy way to do
                    // this outside the context of a Web request. Therefore
                    // just emit a warning message in the content when
                    // SPContext.Current is null (since attempting to replace
                    // the reusable content fragments ourselves would require
                    // a substantial amount of custom code).
                    if (SPContext.Current != null)
                    {
                        HtmlField pageContentField =
                            (HtmlField)page.Fields[FieldId.PublishingPageContent];

                        pageContent = pageContentField.GetFieldValueAsHtml(
                            pageContent);
                    }
                    else
                    {
                        writer.WriteLine(
@"<p><strong>Warning:</strong> The page content contains reusable content, which
    is not included when SPContext.Current is null. To obtain the full content
    -- including all reusable content -- submit the request within the context
    of a SharePoint site.</p>");
                    }
                }

This worked fine for the original release because we only needed to support the "Export to PDF" feature in the "long running page" that I mentioned before. When running my unit tests, the resulting PDF contained the warning message inserted by the code above, but that was just fine with me.

However, as is often the case, the business requirements changed over time and we needed to evolve the solution accordingly.

"Expanding" reusable content placeholders when SPContext.Current is null

As I mentioned before, in addition to the original "Export to PDF" feature, we now need the ability to export the documents to an external system. The problem is that, unlike the process of exporting to PDF, exporting to an external system isn't going to run in a matter of a few seconds. Rather, I estimated that it could take several minutes to export a ~100 page document from SharePoint to the external system. [Keep in mind that this is going over the Internet and we also need to export inline images and referenced files from the SharePoint site to the external system (in addition to the actual HTML content).]

Due to the expected latency of the export process, I decided to implement it using a custom SharePoint workflow. This would allow it to run asynchronously instead of within the context of a "long running page" (which would be problematic if the user closed the browser while the export was still running).

The problem with running the export in a workflow, however, is that SPContext.Current is null -- and unlike, my simple hack in the intial sprint, a warning message simply wasn't going to cut it in this case ;-)

Consequently, I implemented a custom method in the SharePointHtmlFieldHelper class for getting the "expanded" HTML content from a Publishing HTML field:

        public static string GetFieldValueAsHtml(
            SPWeb web,
            object value)
        {
            if (web == null)
            {
                throw new ArgumentNullException("web");
            }

            string str = value as string;

            if (string.IsNullOrEmpty(str) == true)
            {
                return string.Empty;
            }

            bool canCacheResults = true;

            return ConvertStorageFormatToViewFormat(
                web,
                str,
                out canCacheResults);
        }

If the method signatures look a little goofy, it's because I tried to keep them as similar as possible to the out-of-the-box SharePoint classes. [My hope -- no matter how small the probability -- is that the SharePoint code will be eventually be improved to handle the scenario where SPContext.Current is null. Let's just say that I'm not expecting that to happen, but that doesn't mean I can't hope for more robust code from the SharePoint team.]

The reason why I require an SPWeb object is so I can subsequently read the corresponding list items from the Reusable Content list. [Technically speaking, I really only need an SPSite object, but I chose an SPWeb in order to provide additional detail in cases where "malformed" content is detected (e.g. the number of placeholders specified in the HTML does not match the number of items in the reusable content "header").]

If you look at the code (see attachment on previous post), then you'll see that I'm essentially just following the original implementation in HtmlEditorInternal except that I don't rely on SPContext.Current and instead use the specified SPWeb parameter to access the Reusable Content list.

Important
Also note that, unlike the original HtmlEditorInternal implementation, I don't leverage any caching when fetching Reusable Content list items. Consequently, you should be wary of using this implementation in very high volume scenarios. For the purposes of my current project, performance has proved to be more than adequate.

I should point out, however, that I still prefer to use the out-of-the-box SharePoint code whenever possible, which is why I provide a wrapper method in the SharePointPublishingHelper class that determines whether or not it is "safe" to use the HtmlField.GetFieldValueAsHtml method:

        /// <summary>
        /// Returns the value of the "Page Content" field for the specified page
        /// in HTML format. If the field contains any "reusable content"
        /// placeholders, they are expanded in order to return the HTML just as
        /// it would appear directly on the page.
        /// </summary>
        /// <param name="page">The page to get the content for.</param>
        /// <returns>The HTML content for the "Page Content" field.</returns>
        public static string GetPageContentAsHtml(
            PublishingPage page)
        {
            if (page == null)
            {
                throw new ArgumentNullException("page");
            }

            string pageContent = null;

            if (SPContext.Current != null)
            {
                // In this case, the out-of-the-box SharePoint functionality
                // works, so use it (rather than our own hack)
                HtmlField pageContentField =
                    (HtmlField) page.Fields[FieldId.PublishingPageContent];

                pageContent = pageContentField.GetFieldValueAsHtml(
                    page.ListItem[FieldId.PublishingPageContent]);

            }
            else
            {
                // HACK: In this case, the out-of-the-box SharePoint
                // functionality throws a NullReferenceException, so get the
                // HTML content using custom code
                pageContent = SharePointHtmlFieldHelper.GetFieldValueAsHtml(
                     page.PublishingWeb.Web,
                     page.ListItem[FieldId.PublishingPageContent]);
            }

            return pageContent;
        }

If you download the sample solution from my previous post, you can run all the various unit tests to verify things are working as expected, including the following unit test, which demonstrates why you can't use the HtmlField.GetFieldValueAsHtml method when SPContext.Current is null:

        /// <summary>
        /// This test simply demonstrates why the out-of-the-box
        /// <see cref="Microsoft.SharePoint.Publishing.Fields.HtmlField.GetFieldValueAsHtml"/>
        /// method cannot be used to "expand" reusable content when
        /// SPContext.Current is null.
        /// </summary>
        [System.Diagnostics.CodeAnalysis.SuppressMessage(
            "Microsoft.Naming",
            "CA1707:IdentifiersShouldNotContainUnderscores")]
        [TestMethod()]
        [ExpectedException(typeof(NullReferenceException))]
        public void HtmlField_GetFieldValueAsHtml_FailsWhenSPContextCurrentIsNull()
        {
            string fabrikamDemoUrl = GetFabrikamDemoUrl();

            const string webUrl = "/";
            const string pageUrl = "Pages/ReusableContentSample.aspx";

            // The following HTML should not appear in the "storage" format but
            // should appear in the "view" format (in other words, when the
            // reusable content is "expanded")
            const string reusableContentFragment =
                "<h2>Statement of Non-Discrimination and Affirmative Action</h2>";

            using (SPSite site = new SPSite(fabrikamDemoUrl))
            {
                using (SPWeb web = site.OpenWeb(webUrl))
                {
                    PublishingPage page =
                        SharePointPublishingHelper.FindPublishingPage(
                            web,
                            pageUrl);

                    string pageContent = (string)page.ListItem[
                        FieldId.PublishingPageContent];

                    Assert.IsTrue(pageContent.Contains(
                        "__publishingReusableFragment"));

                    Assert.IsFalse(pageContent.Contains(
                        reusableContentFragment));

                    // Now demonstrate that HtmlField.GetFieldValueAsHtml
                    // throws NullReferenceException when SPContext.Current is
                    // null...
                    Assert.IsNull(SPContext.Current);

                    HtmlField pageContentField =
                        (HtmlField)page.Fields[FieldId.PublishingPageContent];

                    pageContentField.GetFieldValueAsHtml(
                        pageContent);
                }
            }
        }

If this unit test ever starts failing, I'll know there's a good chance that I can scrap my custom code and go with the out-of-the-box SharePoint code instead ;-)

Note
You must be running Visual Studio 2010 Service Pack 1 in order to run my SharePoint 2010 unit tests (in order to avoid bugs in 64-bit environments like the one I described in a post from a couple of years ago).
]]> Reusable Content in SharePoint Publishing HTML Fields, Part 2 https://docs.microsoft.com/archive/blogs/jjameson/reusable-content-in-sharepoint-publishing-html-fields-part-2 Wed, 13 Apr 2011 19:06:00 GMT https://blogs.msdn.microsoft.com/jjameson/2011/04/13/reusable-content-in-sharepoint-publishing-html-fields-part-2/ In my previous post, I introduced a scenario for using the "Reusable Content" feature in Microsoft Office SharePoint Server (MOSS) 2007 and SharePoint Server 2010. In this post, I show you how to programmatically add Reusable Content list items (which is very helpful when deploying to multiple environments, such as DEV, TEST, and PROD) as well as how to insert reusable content into a Publishing HTML field on a page (e.g. the Page Content field). I also provide a complete code sample for SharePoint 2010 that demonstrates the key concepts discussed in this series.

Adding a new Reusable Content list item

Since reusable content in SharePoint is enabled by the Publishing features, I chose to enhance the SharePointPublishingHelper class -- which I introduced in a previous post -- to provide a new method for ensuring some piece of reusable content has been configured.

In case you are not familiar with the "ensure" logic that I tend to implement in various SharePoint helper classes, in essence the code performs any necessary actions to achieve some condition (for example, ensure a specific page exists -- by creating a new page if one doesn't already exist). The key design principle in the "ensure" logic is to avoid trampling any manual changes that may have been made to SharePoint by content authors and administrators.

When it comes to adding a piece of reusable content, this "ensure" logic means that we only want to configure the Reusable Content list item if it doesn't already exist. In other words, we don't want to overwrite the content if the list item already exists, because it may have been updated by a content author or administrator since it was originally created (presumably upon activation of some feature). [There are scenarios where you do want to overwrite the existing site configuration, but those are beyond the scope of this post.]

For example, consider the following method of SharePointPublishingHelper:

        public static SPListItem EnsureReusableContentItem(
            SPSite site,
            string title,
            bool automaticUpdate,
            string reusableHtml)

Imagine that you run the following code upon activation of a feature:

            SPListItem reusableContent =
                SharePointPublishingHelper.EnsureReusableContentItem(
                    web.Site,
                    "Copyright",
                    true,
                    "Copyright© 2009 Contoso Corporation - All Rights Reserved");

If the specified Reusable Content list item already exists (found by matching on the Title field), then the existing list item is returned. Otherwise, a new list item is added (with the specified field values) and subsequently returned. Note that we don't want to overwrite the content in the list item because someone may have updated the copyright content (e.g. "Copyright© 2011 Fabrikam Technologies - All Rights Reserved").

Also note that the Reusable Content list is configured for approval by default, and -- as I mentioned in part 1 of this series -- "bad things" happen when a page includes a reference to reusable content that has not been approved. Consequently, the EnsureReusableContentItem method also takes care of approving the list item (if it does not have at least one approved version):

        public static SPListItem EnsureReusableContentItem(
            SPSite site,
            string title,
            bool automaticUpdate,
            string reusableHtml,
            string comments,
            string contentCategory)
        {
            if (site == null)
            {
                throw new ArgumentNullException("site");
            }

            if (title == null)
            {
                throw new ArgumentNullException("title");
            }

            title = title.Trim();
            if (string.IsNullOrEmpty(title) == true)
            {
                throw new ArgumentException(
                    "The title must be specified.",
                    "title");
            }

            if (reusableHtml == null)
            {
                throw new ArgumentNullException("reusableHtml");
            }

            reusableHtml = reusableHtml.Trim();
            if (string.IsNullOrEmpty(reusableHtml) == true)
            {
                throw new ArgumentException(
                    "The reusable HTML must be specified.",
                    "reusableHtml");
            }

            // Note: comments and contentCategory may be null
            
            SPLogger.Log(
                LogCategory.Configuration,
                TraceSeverity.Medium,
                "Configuring reusable content item ({0}) on site ({1})...",
                title,
                site.Url);

            if (string.IsNullOrEmpty(contentCategory) == true)
            {
                SPLogger.Log(
                    LogCategory.Configuration,
                    TraceSeverity.Medium,
                    "The content category was not specified, using default"
                        + " value (None)",
                    title);

                contentCategory = "None";
            }

            const string rootFolderUrl = "ReusableContent";

            SPList reusableContentList = SharePointListHelper.FindListByRootFolderUrl(
                site.RootWeb.Lists,
                rootFolderUrl);

            if (reusableContentList == null)
            {
                string message = string.Format(
                    CultureInfo.CurrentCulture,
                    "The list ({0}) could not be found on the site ({1}).",
                    rootFolderUrl,
                    site.Url);

                throw new InvalidOperationException(message);
            }

            EnsureReusableContentCategoryExists(reusableContentList, contentCategory);

            string camlQuery =
                "<Where><Eq><FieldRef Name='Title'/><Value Type='Text'>"
                    + title + "</Value></Eq></Where>";

            SPListItem listItem = SharePointListHelper.FindUniqueListItem(
                reusableContentList,
                camlQuery);

            if (listItem == null)
            {
                SPLogger.Log(
                    LogCategory.Configuration,
                    TraceSeverity.Medium,
                    "Adding reusable content item ({0}) to site ({1})...",
                    title,
                    site.Url);

                listItem = reusableContentList.Items.Add();
                listItem[SPBuiltInFieldId.Title] = title;
                listItem[FieldId.AutomaticUpdate] = automaticUpdate;
                listItem[FieldId.ReusableHtml] = reusableHtml;
                listItem[SPBuiltInFieldId.Comments] = comments;
                listItem[FieldId.ReusableTextType] = contentCategory;

                listItem.Update();

                SPLogger.LogEvent(
                    LogCategory.Configuration,
                    EventSeverity.Information,
                    "Successfully added reusable content item ({0}) to site"
                        + " ({1}).",
                    title,
                    site.Url);
            }

            if (listItem.HasPublishedVersion == false)
            {
                SPLogger.Log(
                    LogCategory.Configuration,
                    TraceSeverity.Medium,
                    "The reusable content item ({0}) does not have a published"
                        + " version. Approving list item ({1}/{2})...",
                    title,
                    listItem.Web.Url,
                    listItem.Url);

                listItem.ModerationInformation.Status =
                    SPModerationStatusType.Approved;

                listItem.Update();

                SPLogger.LogEvent(
                    LogCategory.Configuration,
                    EventSeverity.Information,
                    "Successfully approved reusable content item ({0})"
                        + " ({1}/{2}).",
                    title,
                    listItem.Web.Url,
                    listItem.Url);
            }
            else
            {
                SPLogger.Log(
                    LogCategory.Configuration,
                    TraceSeverity.Medium,
                    "The reusable content item ({0}) already has a"
                        + " published version and may have been customized, so"
                        + " no changes will be made to the list item"
                        + " ({1}/{2}).",
                    title,
                    listItem.Web.Url,
                    listItem.Url);
            }

            return listItem;
        }

The method is rather long, but keep in mind that roughly half of the code above is error checking and logging. This is intended to be "Production-quality" code, not just a minimal code sample.

Adding reusable content to a page

Once you have the Reusable Content list item created (either manually or programmatically using code like that shown above), the next task is to add the content to a page. Since I'm assuming you already know how to do that using the out-of-the-box page editing features in SharePoint, let's see how this can be achieved through code.

First it is important to understand how reusable content is implemented in SharePoint (the foundation is the same in MOSS 2007 and SharePoint 2010). There are two key concepts to grasp:

  1. The "storage format" of the content in a Publishing HTML field uses a special <div> element as a "header" and corresponding <span> elements to designate the placeholders where reusable content is to be inserted (note that I'm only talking about reusable content that is specified to automatically update).
  2. The "view format" of the content is generated by reading the "header" and subsequently replacing the corresponding placeholders that follow. Hence I tend to refer to this as the "expanded" HTML. In most cases,  you can get the expanded HTML using out-of-the-box SharePoint functionality. [In part 3 of this series, I'll discuss when you can't get it that way and explain the not-so-elegant workaround that I came up with.]

Here is a sample of the HTML content in "storage format":

    <div id="__publishingReusableFragmentIdSection">
        <a href="/ReusableContent/1_.000">a</a>
        <a href="/ReusableContent/3_.000">a</a>
    </div>
    <p>
        Here is some reusable content...</p>
    <p>
        <span id="__publishingReusableFragment"></span>
    </p>
    <p>
        ...and here is some more:</p>
    <p>
        <span id="__publishingReusableFragment"></span>
    </p>

The corresponding "view format" is shown below:

    <p>
        Here is some reusable content...</p>
    <p>
        <span class="ms-rtestate-read  ms-reusableTextView"
            contenteditable="false" id="__publishingReusableFragment"
            fragmentid="/ReusableContent/1_.000">
            Copyright© 2009 Contoso Corporation - All Rights
            Reserved</span>
    </p>
    <p>
        ...and here is some more:</p>
    <p>
        <span class="ms-rtestate-read  ms-reusableTextView"
            contenteditable="false" id="__publishingReusableFragment"
            fragmentid="/ReusableContent/3_.000">
            <em>&quot;Example quotation&quot;</em>
        </span>
    </p>
Note
I have no idea why the out-of-the-box Byline and Quote reusable content items in SharePoint 2010 specify Automatic Update = Yes. I can see the reasoning for enabling automatic update of the default Copyright item, but these other two baffle me.

Look again at the sample "storage format" HTML above. Notice how the reusable content placeholders (i.e. the <span> elements) do not specify which Reusable Content list item to render. Rather, the list item is determined based on the position of the placeholder (relative to other placeholders) -- which is matched to the corresponding item specified in the "header" (by index).

In other words, if you were to swap the order of the <a> elements in the "header"...

    <div id="__publishingReusableFragmentIdSection">
        <a href="/ReusableContent/3_.000">a</a>
        <a href="/ReusableContent/1_.000">a</a>
    </div>
    ...

...then the order of the reusable content in the corresponding "view format" would be reversed, as shown below:

    <p>
        Here is some reusable content...</p>
    <p>
        <span class="ms-rtestate-read  ms-reusableTextView"
            contenteditable="false" id="Span1"
            fragmentid="/ReusableContent/3_.000">
            <em>&quot;Example quotation&quot;</em>
        </span>
    </p>
    <p>
        ...and here is some more:</p>
    <p>
        <span class="ms-rtestate-read  ms-reusableTextView"
            contenteditable="false" id="__publishingReusableFragment"
            fragmentid="/ReusableContent/1_.000">
            Copyright© 2009 Contoso Corporation - All Rights
            Reserved</span>
    </p>

This actually makes the code for inserting reusable content into Publishing HTML fields significantly more complex than it would be if the "storage format" specified something like the following instead:

    <div id="__publishingReusableFragmentIdSection" />
    <p>
        Here is some reusable content...</p>
    <p>
        <span id="__publishingReusableFragment">
            <a href="/ReusableContent/1_.000">a</a>
        </span>
    </p>
    <p>
        ...and here is some more:</p>
    <p>
        <span id="__publishingReusableFragment">
            <a href="/ReusableContent/3_.000">a</a>
        </span>
    </p>

Rather than simply listing the code for inserting reusable content into a page (which you can easily access in the attached sample solution), start by reviewing some of the unit tests that I created when developing the InsertReusableContentIntoHtmlField method:

        /// <summary>
        /// Basic test for appending reusable content to an HTML field.
        /// </summary>
        [TestMethod()]
        public void InsertReusableContentIntoHtmlField001()
        {
            const string reusableContentListItemUrl = "/ReusableContent/1_.000";
            const string htmlFieldContent = null;

            const string expected =
                "<div id=\"__publishingReusableFragmentIdSection\">"
                        + "<a href=\"/ReusableContent/1_.000\">a</a>"
                    + "</div>"
                    + "<span id=\"__publishingReusableFragment\"></span>";

            string actual =
                SharePointHtmlFieldHelper.InsertReusableContentIntoHtmlField(
                    reusableContentListItemUrl,
                    htmlFieldContent);

            Assert.AreEqual(expected, actual);
        }

        /// <summary>
        /// Basic test for appending reusable content to an HTML field which
        /// already contains another piece of reusable content.
        /// </summary>
        [TestMethod()]
        public void InsertReusableContentIntoHtmlField002()
        {
            const string reusableContentListItemUrl = "/ReusableContent/2_.000";
            const string htmlFieldContent =
                "<div id=\"__publishingReusableFragmentIdSection\">"
                        + "<a href=\"/ReusableContent/1_.000\">a</a>"
                    + "</div>"
                    + "<span id=\"__publishingReusableFragment\"></span>";

            const string expected =
                "<div id=\"__publishingReusableFragmentIdSection\">"
                        + "<a href=\"/ReusableContent/1_.000\">a</a>"
                        + "<a href=\"/ReusableContent/2_.000\">a</a>"
                    + "</div>"
                    + "<span id=\"__publishingReusableFragment\"></span>"
                    + "<span id=\"__publishingReusableFragment\"></span>";

            string actual =
                SharePointHtmlFieldHelper.InsertReusableContentIntoHtmlField(
                    reusableContentListItemUrl,
                    htmlFieldContent);

            Assert.AreEqual(expected, actual);
        }

        /// <summary>
        /// Basic test for inserting reusable content into an HTML field at a
        /// specific location.
        /// </summary>
        [TestMethod()]
        public void InsertReusableContentIntoHtmlField003()
        {
            const string placeholder = "{TODO: Insert reusable content here}";

            const string reusableContentListItemUrl = "/ReusableContent/1_.000";
            const string htmlFieldContent = "<p>" + placeholder + "</p>";

            const string expected =
                "<div id=\"__publishingReusableFragmentIdSection\">"
                        + "<a href=\"/ReusableContent/1_.000\">a</a>"
                    + "</div>"
                    + "<p><span id=\"__publishingReusableFragment\"></span></p>";

            string actual =
                SharePointHtmlFieldHelper.InsertReusableContentIntoHtmlField(
                    reusableContentListItemUrl,
                    htmlFieldContent,
                    placeholder);

            Assert.AreEqual(expected, actual);
        }

        /// <summary>
        /// Basic test for inserting reusable content into an HTML field which
        /// already contains other pieces of reusable content.
        /// </summary>
        [TestMethod()]
        public void InsertReusableContentIntoHtmlField004()
        {
            const string placeholder = "{TODO: Insert reusable content here}";

            const string reusableContentListItemUrl = "/ReusableContent/3_.000";
            const string htmlFieldContent =
                "<div id=\"__publishingReusableFragmentIdSection\">"
                        + "<a href=\"/ReusableContent/1_.000\">a</a>"
                        + "<a href=\"/ReusableContent/2_.000\">a</a>"
                    + "</div>"
                    + "<div id='reusableContent1'>"
                        + "<span id=\"__publishingReusableFragment\"></span>"
                    + "</div>"
                    + "<div id='reusableContent3'>" + placeholder + "</div>"
                    + "<div id='reusableContent2'>"
                        + "<span id=\"__publishingReusableFragment\"></span>"
                    + "</div>";

            const string expected =
                "<div id=\"__publishingReusableFragmentIdSection\">"
                        + "<a href=\"/ReusableContent/1_.000\">a</a>"
                        + "<a href=\"/ReusableContent/3_.000\">a</a>"
                        + "<a href=\"/ReusableContent/2_.000\">a</a>"
                    + "</div>"
                    + "<div id='reusableContent1'>"
                        + "<span id=\"__publishingReusableFragment\"></span>"
                    + "</div>"
                    + "<div id='reusableContent3'>"
                        + "<span id=\"__publishingReusableFragment\"></span>"
                    + "</div>"
                    + "<div id='reusableContent2'>"
                        + "<span id=\"__publishingReusableFragment\"></span>"
                    + "</div>";

            string actual =
                SharePointHtmlFieldHelper.InsertReusableContentIntoHtmlField(
                    reusableContentListItemUrl,
                    htmlFieldContent,
                    placeholder);

            Assert.AreEqual(expected, actual);
        }
Note
Initially, I added the code for inserting reusable content into a page to the SharePointPublishingHelper class. However, I ended up refactoring this code into the new SharePointHtmlFieldHelper class. I'll discuss this new class in more detail in part 3 of this series.

Sample "Reusable Content" solution for SharePoint Server 2010

I've attached a complete Visual Studio 2010 solution so you can see just how easy it is to automatically create reusable content and add it to a page using the provided helper classes (for example, upon activation of a feature).

If you've deployed any of my other sample SharePoint solutions, you'll find this one just as easy.

Here are the instructions to deploy the sample to your own SharePoint environment. First, download the attachment and unzip the files. Then you simply need to create a few domain users and run a handful of PowerShell scripts, as described below.

To deploy the sample solution to SharePoint 2010:

  1. Create three service accounts for the Fabrikam Demo site:
    • {DOMAIN}\svc-web-fabrikam-dev - used as the application pool identity for the new "Fabrikam Demo" site
    • {DOMAIN}\svc-sp-psr-dev - object cache user account providing Full Read access to Web applications (https://technet.microsoft.com/en-us/library/ff758656.aspx)
    • {DOMAIN}\svc-sp-psu-dev - object cache user account providing Full Control access to Web applications
  2. On the Start menu, click All Programs, click Microsoft SharePoint 2010 Products, right-click SharePoint 2010 Management Shell, and then click Run as administrator. If prompted by User Account Control to allow the program to make changes to the computer, click Yes.
  3. From the Windows PowerShell command prompt, change to the directory containing the deployment scripts (e.g. C:\NotBackedUp\Fabrikam\Demo\Dev\SharePointReusableContent\Source\DeploymentFiles\Scripts), and run the following commands:
    $env:FABRIKAM_DEMO_URL = "https://fabrikam-local"
    $env:FABRIKAM_DEMO_BUILD_CONFIGURATION = "Debug"
    & '.\Add Event Log Sources.ps1'
    & '.\Create Web Application.ps1'
    & '.\Configure Object Cache User Accounts.ps1'
    & '.\Create Site Collections.ps1'
    & '.\Enable Anonymous Access.ps1'
    & '.\Add Solutions.ps1'
    & '.\Deploy Solutions.ps1'
    & '.\Activate Features.ps1'
Note
Technically, you don't have to set the environment variables (and use the "-dev" accounts). However, I recommend this in order to bypass SharePoint timer jobs when deploying the WSPs.

At this point you should be able to modify your hosts file accordingly and browse to either https://www-local.fabrikam.com (to view the site as an anonymous user) or https://fabrikam-local (to view the site as an administrator).

You can then click the Reusable Content Sample link on the home page of the site to view the sample page. Once you have verified the page renders as expected, modify the corresponding item in the Reusable Content list and verify the page is "automatically updated" accordingly. [Now that you understand how reusable content works in SharePoint, you know the page isn't "automatically updated" at all. Rather, the dynamically generated "view format" renders the updated content.]

In part 3 of this series, I'll discuss various ways of accessing the "expanded" HTML content (a.k.a. the "view format.")

Fabrikam Demo - SharePointReusableContent.zip

]]>