Microsoft Enterprise Content Management (ECM) Team Blog : How To

Building a real world extranet application with MOSS 2007 (Part 2 of 3)

ecmblog — Wed, 07 Mar 2007 08:43:38 GMT

Introduction

In the first installment of this blog series, we introduced the project and its requirements and started creating the basic site and content structure. In this installment, we’ll cover the customization and branding choices that we made, venture into the slightly gray areas that needed some additional thinking, and discuss some of our “off the beaten path” customization tactics.

Site and content customization (i.e. branding)

The new file management system was to replace an existing model, which users were already familiar with. This coupled with the fact that an already well established corporate brand existed meant that creating a consistent and familiar experience would be very important towards encouraging speedy user adoption of and efficient transition to the new system.

Once the UI was established visually, we began the process of matching best practices with both customer requirements and the new MOSS 2007 design and development experience.

The customization process was divided into two major sections in an attempt to offer maximum scalability while separating the majority of presentation from the content and code base.

Master Page Customization
Cascading Style Sheet Customization

The art of creating a custom Master Page in MOSS 2007

MOSS 2007 adopted the ASP.NET 2.0 master pages model, a model which allows you to separate the chrome (UI elements) from the content. The second major benefit of using master pages in MOSS 2007 is that you can control the UI of a site or entire site collection with a single page, the master page.

Before creating our custom Master Page, it was important for us to fully understand the following concepts:

Content Place Holders and Content Controls, and how they are used in MOSS 2007

There are several pages behind a rendered page that you would see in SharePoint. The Master Page which holds the UI chrome as well as content place holders where content can later be “plugged in” from other pages. These other pages, known as Content Pages have Content Controls with IDs matching those on the placeholders in the master page.
When requested, the content from the Content Control is merged into the Content Place Holder of the Master Page, finally presenting you with a single rendered page. Understanding this concept is very important when customizing a Master Page because removal of a content place holder that is later called on will result in an error. It’s important the content place holders exist on the page – even if not visible. For a list of content place holders, which reside in the default Master Page of a SharePoint site, see http://msdn2.microsoft.com/en-us/library/ms467402.aspx.

Creating a minimal Master Page

Unlike standard design, there is no blank slate from which to start a site in SharePoint. There is no magic “File New” button in SharePoint Designer 2007 that will allow you to just begin coding your UI and have the SharePoint functionality just work. Instead, you will need to understand how to work with SharePoint’s default Master Page and to minimize it by leaving only the placeholders that are required for SharePoint to function. Luckily for us, MSDN has been kind enough to post a minimal Master Page complete with comments, which you can use as a starting point for your own sites: http://msdn2.microsoft.com/en-us/library/aa660698.aspx.

Armed with information on the preceding topics and the tool of choice, SharePoint Designer 2007, we set out to create our custom branded application. SharePoint Designer 2007 allows you to connect to and work with your SharePoint sites, so the first thing we did was fire up SharePoint Designer 2007 and connected to our site via the File, Open Site menu.

MOSS 2007 introduces a new concept of “publishing features”. Publishing features represent the CMS 2002 integration into SharePoint, now known as Web Content Management or WCM. When enabled, publishing features allow you to do things like enable content approval workflow or change the Master Page and style sheet on the fly, both of which we utilized and proved useful in creating a custom branded application.

After combining our custom UI (graphics and code) with the minimal Master Page from MSDN, we uploaded our custom Master Page to the _catalogs/masterpage folder. This is a good time to point out that with a blank starting Master Page (and page layouts), we were able to vastly reduce the number of tables, and take advantage of our CSS based UI.

After uploading our custom Master Page, we added some final tweaks such as adding the company logo to the Master Page. While there is an out of the box method for adding a logo (Site Settings > Title, Description and Icon), doing this does not automatically carry the logo down to new sub-sites as they are created; instead, you would need to re-specify the logo on each site. This is by design just in case you want to specify a different logo on the subsites, which normally makes perfect sense, but in our project, a requirement was that all sites are to be created using the parent company’s corporate logo unless otherwise specified. To accomplish this, we created a custom picture library labeled “site images” and uploaded the corporate logo (named companylogo.gif) to the library. Next we replaced the default mechanism for switching the logo in the Master Page:

<SharePoint:SiteLogoImage id="onetidHeadbnnr0" LogoImageUrl="/_layouts/images/titlegraphic.gif" runat="server"/>

replacing it with some key new functionality in SharePoint 2007:

<asp:Image runat="server" id="Logo" ImageUrl="<% $SPUrl: ~site/site images/companylogo.gif %>"/>

What this change does is tell the image control to check in the site’s site images library for companylogo.gif. Because this is specified in the Master Page, the change is seen on subsites, which inherit this Master Page. Also, because we have specified the “site” site images library in SPURL, changing the company logo on a sub site is simply a matter of over writing the default companylogo.gif image in the specific site's site images library. We mimicked this approach when adding a header image to the page, allowing even further customization on a site by site basis.

To apply our custom Master Page, we went to the root site's Site Settings, Master Page section where we were able to select and apply it to the site and subsites right from the browser, completely transforming the UI into an intuitive and branded application.

Separating the presentation

To separate the content, mark-up, and presentation as much as possible, we opted to use the alternate style sheet approach. By default, the core style sheet, appropriately named CORE.CSS controls the majority of the sites, colors, fonts, and positioning.

To over-ride these default values, we took advantage of the “AlternateCSS”, an option which can be specified from the browser under Site Settings, Master Page, Specify “AlternateCSS” URL.

We started by creating a blank style sheet and saving it to the style library, a library created by default with all publishing portals. After adding our style sheet and specifying it using the method described above, any styles/properties we add which exist in the default (CORE.CSS) will be overwritten because our alternate style sheet is read last.

To figure out what classes we needed to override, we took advantage of a free tool from Microsoft’s Internet Explorer Team, the Internet Explorer Developer Toolbar. Download the beta here.

Using the “Select Element by Click” option in the IE Developer Toolbar, we were able to click on any element of our screen and instantly see what class should be changed in our alternate style sheet. In the example below, we clicked on the Recycle Bin link.

In the example above, we could add .ms-recyclebin to the alternate style sheet to change its properties. Tip: Make sure you copy all properties specified in the CORE.CSS; otherwise, they will not be overwritten.

Using “AlternateCSS”, we were able to isolate the presentation to a single style sheet, overriding the default styles when applied.

Because subsites can be set to inherit the Master Page and alternate style sheets of their parent, this method also allows for sweeping brand changes by editing a single file. Just as it can be set to inherit, you can also choose not to in which case subsites are free to use a completely different Master Page or style sheet.

In this installment, we covered the key customization methods which allowed us to brand our sites as well as keep a familiar and intuitive UI for our application. In the next and final installment, we will take a look at Search as well as how we overcame multilingual obstacles before wrapping up with a look at our template system and our finished product. We'll also provide a summary of the MOSS 2007 specific features that were utilized for our project.

Shane Perran – User Experience Lead, SharePoint MVP
Jared Rypkema – Lead Software Architect
Infotech Canada | Information Worker Solutions

Customizing Content Query RSS feeds

ecmblog — Sat, 09 Dec 2006 03:59:00 GMT

One of the great features of the Content Query web part is that, once you configure it and have it showing the content that you want, you can have it emit an RSS feed of the same content. So, if you have a Content Query web part showing the latest news articles published on the site, you can offer readers an RSS feed of this same content for them to subscribe to.

One question that comes out of this is, "How can I change the output of the RSS feed?" For example, let's say you want to emit a different column of your data as the feed item title or description. Or, let's say you wanted to offer the feed in a different format, such as Atom.

Let's first take a closer look at the feed that is emitted by the Content Query web part. Here, I have a CQWP showing the latest news articles on my site, and it has a feed enabled. By the way, to enable a feed on a Content Query web part, simply edit the web part, expand the Presentation section, and check the Enable Feed box.

If I click through to the feed, I see a preview of it in IE7, and I can subscribe to it from here. The URL of the feed in this case is http://<servername>/_layouts/feed.aspx?xsl=1&web=%2FNews%2FEnglish&page=fe5ab523-46d2-4285-a095-d590ca8975a5&wp=4144557a-1f5e-4ebf-9ec7-9b1525df1e43

The query string parameters after the feed.aspx page are the key here. They are:

Parameter name	Description	Valid values
Xsl	The xsl to use to produce the feed	Registered xsls in the web.config file
Web	The web where the CQWP lives that is emitting this feed	Server-relative url
Page	The page where the CQWP lives that is emitting this feed	GUID
Wp	The CQWP ID	GUID

Feed.aspx effectively "looks up" the Content Query web part that is emitting the feed, figures out the query it runs, runs the same query, but instead of outputting HTML, it outputs feed xml by using the XSL in question.

Now, you may be wondering what "XSL=1" is referring to. That's not a path to an XSL file. Instead of feed.aspx supporting the ability to run XSLs here, we wanted to make it something that the admin could manage. So, only XSLs that are registered in the web.config file can be used by feed.aspx. Looking at the web.config for this site, you'll find the following line:


<appsettings>
 ...
    <add key="FeedXsl1" value="/Style Library/Xsl Style Sheets/Rss.xsl" >
 ...
</appsettings>

This is the out of box registered XSL. You'll notice it lives in the Style Library, right next to the XSLs used to render content in the Content Query web part.

If I wanted to have my own XSL be used for CQWP RSS feeds, I could do a couple of things. First, I could edit this XSL file. Then, all CQWPs would use this updated XSL file to render the feeds. However, if I want something custom that pertains to just one Content Query web part, it makes more sense to add my own XSL file.

To do that, you need to do the following:

1. First, add the XSL file that you want your Content Query web part to use for the feed in the Style Library. You can place it in the same folder as the out-of-box rss.xslt.

2. Next, add a line to the web.config file to register this XSLT file. The important thing is what number(s) or letter(s) you use after the "FeedXsl" token. I'm going to stick to numbers, so I'll use a "2":


<appSettings>
 ...
   <add key="FeedXsl1" value="/Style Library/Xsl Style Sheets/Rss.xsl" />
   <add key="FeedXsl2" value="/Style Library/Xsl Style Sheets/Rss-custom.xsl" />
 ...
</appSettings>

3. Now we'll need to modify the XSLT that emits the RSS feed link in the Content Query web part. Again, if I edit the shared ContentQueryMain.xsl, it'll affect all Content Query web parts. Since I only care to modify only one, I'm going to make a copy of this file:

4. And then, I'm going to change one line in it, from:


<xsl:variable name="FeedUrl1" select="concat($SiteUrl,$FeedPageUrl,'xsl=1&amp;web=',$WebUrl,'&amp;page=',$PageId,'&amp;wp=',$WebPartId)" />

To:


<xsl:variable name="FeedUrl1" select="concat($SiteUrl,$FeedPageUrl,'xsl=2&amp;web=',$WebUrl,'&amp;page=',$PageId,'&amp;wp=',$WebPartId)" />

5. Now, I'll need to ensure my CQWP is using the ContentQueryMain-custom.xsl. To do that, I'll need to edit the web part property that determines which Main file is used. One easy way to do that is to find my web part on a page, export it, edit the property, and re-import it.

The property in question here is:


<property name="MainXslLink" type="string" />

For my web part, I'd say:


<property name="MainXslLink" type="string">/Style Library/XSL Style Sheets/ContentQueryMain-custom.xsl</property>

That's it! I now have the ability to have a Content Query web part that's emitting an feed in a custom way. Hopefully people find this helpful. And, if people do customize the Content Query web part feeds in this manner, please post a comment and tell us what you did.

--George Perantatos, Program Manager

Long awaited "Customizing and Branding SharePoint Sites" technotes are now published

LLiu — Wed, 15 Nov 2006 11:38:00 GMT

I recall reviewing a few months ago the following MSDN articles written by Patrick Tisseghem (a long time SharePoint MVP), and I’ve been waiting anxiously ever since to see them published:

· Customizing and Branding Web Content Management-Enabled SharePoint Sites (Part 1 of 3): Understanding Web Content Management and the Default Features

· Customizing and Branding Web Content Management-Enabled SharePoint Sites (Part 2 of 3): Extending WCM

· Customizing and Branding Web Content Management-Enabled SharePoint Sites (Part 3 of 3): Creating and Configuring WCM-Enabled Sites

These articles are relatively lengthy, but they’re definitely well worth reading especially since they’re the ideal complements to the recent series of technical posts by the WCM feature team on this blog.

Configuring and Customizing the Content Query Web Part

ecmblog — Wed, 25 Oct 2006 21:25:00 GMT

Hi everyone, George Perantatos here. Last time I posted on this blog, I discussed how Smart Client Authoring can be used to convert documents into web pages. This time I want to switch gears a bit and talk about how you can aggregate content from various places in your web site and present it all in one place.

So, let's imagine that you've built out a web site using Office SharePoint Server 2007. Your web pages, documents, and images are stored in SharePoint libraries. Content types define the schemas of discrete items, and sub-sites are used for organization and navigation. Now, the question is: how do I aggregate interesting slices of this information on places like my web site's home page?

Well, we have a great web part for doing just that right out of the box, and it's called the Content Query Web Part. This web part allows you to show items from your site based on a query, or set of rules, that you define. You can control what part of the site the web part looks for content, what types of items it returns, and it lets you filter, sort, and group those results. And, it lets you control how the items are rendered, so you can make these aggregations match the look and feel of the rest of your web site, both in what content is shown as well as how it's styled.

The best way to show what the web part is capable of is to walk through an example. Let's say that you've defined a type of page in your site called a "Product Page". A Product Page has a set of common fields, like Title, Description, and Body, but it also has some additional metadata that tells you what product line the page is for. Now, let's say that you want your home page to feature a list of the latest 5 product pages from your entire site that are about the Widget product line. Furthermore, you want to show this list of product pages by displaying the Title of the page as well as a portion of the Body content, with a little "more..." link that takes people to the full article. Something like:

Widget 2007
The Widget 2007 Beta 2 has recently gone to market. This innovative... (more)

Widget Community launches!
Our first community driven application portal has just launched. You can...(more)

OK, let's get to work!

Step 1: add a Content Query Web Part to the home page

This part is pretty basic. I go to the home page of our site, click on Site Actions, and click Edit Page. The page is checked out to me, and is placed in edit mode. In one of the web part zones, I click "Add Web Part", scroll down to the Content Query Web Part, select it, and add it.

Now, I have a Content Query Web Part on my checked-out version of the home page. It's running a default query that shows me all of the web pages in my site collection.

Step 2: configure Content Query to rollup product pages

Well, that's an OK query as a placeholder to show me that the web part is working correctly, but the results are not exactly what I want to show. So, I have to edit the web part and configure it to show product pages. First, I click on the web part menu and select Modify Shared Web Part.

The toolpane opens and I see sections of properties. The Query section lets me configure what content the web part will show, and the Presentation lets me configure how the content is displayed.

Let's expand the Query section and configure this part:

For Source, I don't know (or care) where the product pages live, so I'll leave that set to the entire site collection.

For List Type, I know these are Web pages, which reside in a pages library, so I'll leave this set to Pages Library.

For Content Type, I know these are pages of a particular content type: Product Page. So, I'll pick the content type group that I created Product Page in, and then set the drop-down to Product Page.

Now, if I click Apply on my web part, I see just product pages appearing!

OK, but my tasks is to show the latest 5 product pages that are about the Widget product line. Let's look further down the toolpane UI and see what we can do.

If I expose the Additional Filters drop-downs, I see the properties that are defined for the Product Page content type. Great; so if I select Product line, is equal to, and type in Widget, I should only get back those pages whose metadata says they're for the Widget product line.

Down on the Sorting drop-down, I see that we're sorting by created date (most recent first). I care about when people update product pages, so I'll set this to Modified.

Finally, I like to have an item limit here so the web part doesn't show too much information (it's the home page after all). I'll set the item limit to 5.

Now, if I click Apply on my web part, I see not only just product pages, but the latest 5 product pages about the Widget product line!

OK, we're getting close. But...hmm, the styles don't look quite right. I see a title, but I don't see the body text and the "more...". How do we fix that?

Step 3: customize Content Query to ask for additional product page fields

Anytime you want the Content Query web part to show specific fields from the items that you're aggregating, you have to do two things:

You have to tell the web part to ask for those fields
You have to render those fields in the styles that the web part uses to show the items

Let's tackle the first one. So, I want to have the web part show the Body field from the product pages, so I have to configure the web part to ask for it.

First, I export the web part that we've added. From the web part menu, I select Export..., and pull down the .webpart file. This is just a text file that shows all of the properties of the web part and their values.

We look for the property called "CommonViewFields". This property makes the web part request additional fields, on top of the "base" ones it asks for out of the box. We can edit this property and specify one additional field to ask for, namely the Body field.

<property name="CommonViewFields" type="string">Body_x0020_content, RichHTML</property>

There's a few ways you can configure this property but the most common one is "Internal name of field", followed by a comma, followed by the type of the field. If you want more than one, add a semicolon between each pair. (Don't worry, we have an SDK article coming soon that gets into all the details of using this and other properties.)

Now, all we have to do is save this .webpart file and import it back on the site. By selecting Import from the toolpane, and browsing to the .webpart file, you can upload this new .webpart and then add it to your page.

As soon as we add our web part, we see...

Wow, that looks exactly the same! Right, so the web part now has the Body field content, but it's not rendering the content. How do I make the web part do that?

Step 4: customize XSLT to render additional fields

The Content Query web part utilizes XSLT to render its contents. This means that I can edit the way the web part renders content and configure exactly what is shown and how it's shown.

If I edit the web part and look at the toolpane, I'll see a couple of drop-downs that relate to Styles. These correspond to the Header and ItemStyle XSLT files that are located in the site collection's Style Library, which is in the root site.

I see that the web part is currently configured to use the "Image on left" style. If we open the ItemStyle file, we'll see several xsl templates. Each corresponds to an item style in the drop-down above. The Image on left style looks like this:

    <xsl:template name="Default" match="*" mode="itemstyle">
        <xsl:variable name="SafeLinkUrl">
            <xsl:call-template name="OuterTemplate.GetSafeLink">
                <xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>
            </xsl:call-template>
        </xsl:variable>




        <xsl:variable name="SafeImageUrl">
            <xsl:call-template name="OuterTemplate.GetSafeStaticUrl">
                <xsl:with-param name="UrlColumnName" select="'ImageUrl'"/>
            </xsl:call-template>
        </xsl:variable>



        <xsl:variable name="DisplayTitle">
            <xsl:call-template name="OuterTemplate.GetTitle">
                <xsl:with-param name="Title" select="@Title"/>
                <xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>
            </xsl:call-template>
        </xsl:variable>




        <xsl:variable name="LinkTarget">
            <xsl:if test="@OpenInNewWindow = 'True'" >_blank</xsl:if>
        </xsl:variable>


        <div id="linkitem" class="item">
            <xsl:if test="string-length($SafeImageUrl) != 0">
                <div class="image-area-left"> 
                    <a href="{$SafeLinkUrl}" mce_href="{$SafeLinkUrl}" target="{$LinkTarget}">
                        <img class="image" src="{$SafeImageUrl}" mce_src="{$SafeImageUrl}" alt="{@ImageUrlAltText}" />
                    </a>
                </div>
            </xsl:if>



            <div class="link-item">
                   <xsl:call-template name="OuterTemplate.CallPresenceStatusIconTemplate"/>
                <a href="{$SafeLinkUrl}" mce_href="{$SafeLinkUrl}" target="{$LinkTarget}" title="{@LinkToolTip}">
                    <xsl:value-of select="$DisplayTitle"/>
                </a>
                <div class="description">
                    <xsl:value-of select="@Description" />
                </div>
            </div>
        </div>
    </xsl:template>

The style breaks down into two sections:

The first section (the part that begins with an "xsl:variable") processes the data, and ensures that it is properly formatted. Some of these functions called here ensure the styles can be shared between the Summary Links and the Content Query web parts. Other functions are there to ensure that the information passed to the XSLT doesn't contain improper markup that could render out as unescaped HTML.
The second section (the part that begins with a "div id") renders HTML and includes the data.

We see that this style renders an image, a title, and a description. For the scenario above, all I have to do is change that description line:

                <div class="description">
                    <xsl:value-of select="@Description" />
                </div>

and make it show the Body content field:

                <div class="description">
                    <xsl:value-of select="@Body_x005F_x0020_content" />
                </div>

If I save the XSLT and reload the page with my web part, I see:

Great, I'm finally done!

Tips and tricks

Often you may want to see how the cross-list query data is getting thrown to the XSLT, so you can devise the right statements to display the data. Here's a quick way to render the names of the fields that are getting passed to you. For a given item style that the web part is using, add the following markup:

                <xsl:for-each select="@*">
                       P:<xsl:value-of select="name()" />
                </xsl:for-each>

A quick sidenote on web part property editing: while exporting the web part as I did above is certainly valid, it only applies to one instance of a web part on one page. You have two other options:

You can configure a Content Query web part as above, and have it be available in the web part gallery, for authors to add to their pages.
You can edit a web part on a web part page or page layout in SharePoint Designer, and configure it as above. If you edit a web part in a web part zone in a page layout, then all new pages that use this layout will get your customized web part.

Pay attention to details when editing XSLTs. Missing closed tags matter, as do letter casings when referring to field names. I speak from experience here.

I hope this walkthrough helps people configure and use the Content Query Web Part. I'd be interested to hear and see examples of how people are using the web part, as well as field questions. So, post your comments!

--George Perantatos, Program Manager