Microsoft Enterprise Content Management (ECM) Team Blog : design

Building tylerbutler.com, Part 2: Building Content Types and Page Layouts

ecmblog — Mon, 06 Nov 2006 22:27:00 GMT

Part 1 :: Part 2 :: Part 3 :: Part 4 :: Part 5 :: Part 6

This is part 2 of an ongoing series of posts about my experience building a custom site on top of Office SharePoint Server 2007. If you haven't yet read part 1, I'd strongly suggest reading it first.

In my last post, I discussed planning and building out my site structure, as well as customizing my master page. In this post, I'll cover creating page layouts and their backing content types, and customizing the Content Query (CQWP) web part to roll up individual posts into a summary page.

Creating Content Types

The first thing I needed to do before I could go about creating my custom page layouts was create a content type. Because I wanted it to be used by pages in my site, I used the Page content type as the parent for my custom content type, which I called TBPost. I then added a few custom fields to my content type, with the following column types:

Column Name	Column Type
Post Author	Person or Group
Page Content	Publishing HTML
Post Time	Date and Time
Featured Post	Choice
Post Category	Lookup

Most of these custom columns are straightforward, with the exception of the "Featured Post" and "Post Category" fields.

The Featured Post field is used to determine whether a given post is featured on my site. In practice, posts that are featured get displayed at the top of the rollup pages and have a slightly different style applied to them. I have three options for this field: Not Featured, Section Only, and Front Page. By setting this field on a given page, I can make it display at the top of either the front page of the site, or only on the rollup page for a specific section. If a post is set to be featured on the front page, it's implicitly meant to be featured within the section as well. I'll explain how I do this a bit later.

The Post Category field is a lookup field to a custom list that I created that contains all the categories that a post can be in. You may be wondering why I use a lookup field in this case, instead of just a choice field, like I did for the Featured Post field. Well, a given category has an image associated with it, and by using a custom list to store the categories, I can associate an image with each category as an additional column in the list. In the end, I have not been able to leverage this in the way I initially planned, but with this design I do have capability to associate additional data with a category and look it up using code if I need to.

I should also note that both the custom columns and content type I created are in the root site. This is so that the entire site hierarchy can use them, and so that the Content Query web parts can filter on them. But both content types and columns can be scoped to a subweb.

Building Page Layouts

With my new content type created, I set about building my page layouts. I started with the Post layout, which is used by every individual post in the site. Whenever I want to post something new, I simply create a new Page in the appropriate subweb using the Post page layout.

To build the layout, I followed pretty much the same steps that I did when building my master page: I opened up a page on my old site and copied the HTML source for the main post body into the PlaceHolderMain content placeholder in my page layout in SharePoint Designer. Then I removed the content of the post, and dragged in field controls from the handy SharePoint Designer toolbox. Here's what the page layout looks like in SharePoint Designer:

The Post page layout in SharePoint Designer

This whole process was very easy, because SharePoint Designer automatically loads the appropriate fields and controls into the toolbox based on content type that I associated with the page layout when I created it. It really is as easy as dragging and dropping these fields into the right spot on the layout. One other thing I did was add an Edit Mode Panel to the top of the layout. This nifty little thing only displays its contents when the page is brought into edit mode, so it's perfect for controls that you want only your authors to see or edit. In my case, I put the Featured Post and Post Category field controls there. You can find the Edit Mode Panel in the toolbox, under SharePoint Controls -> Server Controls.

The trickiest problem I ran into was how to display the category image for a post. It couldn't be hard coded into the layout, because then I'd need a separate layout for every category, which would be a pain to maintain later. I could also have used an image field control, but then every time I created a new post I would have to select the image. I wanted it to be done automatically based on the category I selected.

My initial plan was to create a custom field control or web part that would render out the right image based on the category I'd selected on the page. However, I really wanted to avoid writing code, so I made a compromising solution. Every site in MOSS has an associated site image. This image is what's displayed in the top left-hand corner of the site when you're using default.master. I changed this for each of my subwebs by going to Site Settings -> Title, description, and icon. Then, in my page layout, I used some markup from default.master to insert that site image into the layout:

<SharePointWebControls:splinkbutton runat="server" NavigateUrl="~site/" id="onetidProjectPropertyTitle">
	<SharePointWebControls:sitelogoimage id="onetidHeadbnnr0" runat="server"/>
</SharePointWebControls:SPLinkButton>

As you can see, the sitelogoimage control is wrapped in a splinkbutton control that points to the subweb, not the site collection. This means that if I click the category image for a given post, I am taken to the subweb that that page is in, which essentially takes me to the rollup page for that category. This is the exact functionality I had on my old site. This solution is pretty elegant, and prevents me from having to use different page layouts on different sites or pick images manually for every post. It's not ideal, however, for reasons I'll point out a bit later.

Rollup Layouts

Now that I had a layout for my individual posts, I wanted to make some layouts for my rollup pages that would aggregate all the pages in various categories, and across the whole site. I started with the individual site rollup page layout, since most of the rollup pages in the site would use this layout. My main home page would be slightly different, but I'll get to that in a minute.

I knew that I wanted to use Content Query web parts for rolling up the pages, so I put a web part zone in the center of my layout and added the web parts to the zone there. I added two web parts. The first CQWP was configured to roll up only pages that were featured on either the home page or the section (using the Featured Post field I mentioned earlier). I did this by configuring the part to look for Pages under the root site that had the content type TBPost. I also used the Filter properties, telling it to exclude pages that did not have their Featured Post property equal to "Front Page" or "Section Only." I also wanted to be sure that my rollup pages were excluded from the CQWP, so I set it to filter out pages whose category was "Rollup."

The second CQWP was configured to roll up all pages across the subweb, i.e. all pages in a given category. To accomplish this, I filtered the results only on the Rollup field and I excluded pages that had their Featured Post property equal to "Front Page" or "Section Only." This means that if a post is featured, it only shows up in one of the CQWPs. I also turned on the RSS feed for this second web part, but I'll discuss RSS at greater length later. Finally, I configured both web parts to only return 5 items apiece.

The other thing I needed to do was tell the CQWP to go and grab some of my extra fields. By default, the CQWP does not return all of the fields for a given page. However, you can override this behavior by setting the CommonViewFields property. There is more information on doing this in George's post on the CQWP. In my case, I set the property as follows:

CommonViewFields="Title,Text;Comments,Text;PostAuthor,User;PostCategory1,Lookup;Post_x0020_Time;"

I also didn't want to have to use the annoying name Post_x0020_Time in my XSL, so I used the DataColumnRenames property to tell the CQWP to remap that field name to another name in my XSL:

DataColumnRenames="Post_x0020_Time,PostDate;"

At this point, my CQWP's were configured to grab the right data, but of course they didn't render the content quite like I wanted them to. In order to get things looking right, I had to edit the XSLT that was being applied to the items, thus changing how they got rendered out. I'll tackle that particular task in my next post. Until next time...

Part 1 :: Part 2 :: Part 3 :: Part 4 :: Part 5 :: Part 6

Using the Minimal Master Page

ecmblog — Tue, 24 Oct 2006 02:09:00 GMT

Hey, my name is Lincoln DeMaris and I’m a Program Manager working on Web Content Management features in Microsoft Office SharePoint Server 2007. Today I’m going to write a little about building master pages that work in a MOSS 2007 Publishing site.

Building a master page is one of the most critical steps of building a highly customized, branded site. The master page is a crucial component in defining how your site looks and how your users will interact with it. Typically, master pages contain all the elements that are shared across most (if not all) the pages in your site collection, like search controls, navigation controls, logos, and CSS references. Every impressive MOSS portal out there is backed by an impressive master page (or set of master pages). The goal of this blog post, therefore, is to get you on the right track towards building a master page that not only fits your needs, but is maintainable and not overly complex.

There are essentially three options available to you regarding how to build your site master page:

Use an out of the box master page. This is certainly the easiest option, and hey, we’ll be flattered if you choose to fly our colors on your external portal. However, nothing says “I’m a MOSS 2007 site!” louder than the blue hues of BlueBand.master, so I’m willing to bet that most of you will want to craft a master page with little more individuality.

Customize one of the out of the box master pages. This is probably the best place to start if you aren’t very familiar with MOSS, or master pages in general. Pick one of our master pages that resembles what you want your site to look like, open up a copy in SharePoint Designer, and go to town. For example, you might like the multi-level vertical navigation scheme of BlueVertical.master, but not necessarily the color scheme or the drop shadows along the side – so you’d start by cracking open a copy of BlueVertical.master, swapping in some custom CSS, and removing the shadowLeft and shadowRight table cells. Once you get the hang of it, it’s pretty easy to start with something out of the box and massage it into something a little more personal.

Roll your own master page. Believe me, I know how frustrating it is to work with somebody else’s code. There’s always the impulse to start from scratch, and that is certainly an option you have. The problem is that it’s rather difficult to start with a totally blank master page and get something that actually will work in a Publishing site. For example, if you go File -> New -> Master Page in SharePoint designer, add some basic design, save, and set your creation as your Site Master page, you’ll probably be greeted by a nasty error message when you refresh your site.

The reason most home-grown master pages will fail is because they are missing the required content placeholders that allow them to work with our out of the box page layouts. If you look at one of these page layouts (like ArticleLeft.aspx), you will see a bunch of <asp:Content> tags similar to the following:

    <asp:Content ContentPlaceholder ID="PlaceHolderPageTitle" runat="server">
        <SharePointWebControls:FieldValue id="PageTitle" FieldName="Title" runat="server"/>
    </asp:Content>

Tags like this match up with content placeholders in the master page. Every <asp:Content> tag you see in a page layout or other content page must have a corresponding <asp:ContentPlaceholder> with the same ID present in the master page. You’ll find the following content placeholder in all of our master pages to match up with the PlaceHolderPageTitle tag shown above:

    <asp:ContentPlaceHolder id=PlaceHolderPageTitle runat="server" />

If the rendering engine comes across a <asp:Content> tag in a page layout, and there is no corresponding content placeholder in the master page, it doesn’t know where to put the content inside the <asp:Content> block. It will then throw an error, and your page will not render. However, the reverse is not true; If you have a <asp:ContentPlaceholder> with no corresponding <asp:Content> tag, there are no ill effects. Therefore, when building a master page, it’s generally a good idea to include ContentPlaceholders for all the the <asp:Content> tags you might come across, just to cover your bases, and ensure compatibility with as many page layouts as possible.

Good news: we’ve done this for you! Specifically, we have created what we call the Minimal Master Page, which is as about as bare-bones as a master page can get while maintaining compatibility with our page layouts. Think of it as a good substitute for the almost totally blank file you get from File -> New -> Master Page in SharePoint Designer. To get the markup for this master page, as well as some additional explanation around its contents, visit the following SDK article:

How to: Create a Minimal Master Page

Alright. Once you’ve copied that markup into a new .master file, saved it to your Master Page gallery (as per the instructions in the article), and set it as your Site Master page, you’ll get a site that looks something like this:

For reference, here is how the same site looked with BlueBand.master applied:

Note that all the content is still there (including our Flash file playing happily on the right in a custom field control), but we’re missing several things: the chrome, the top and left navigations, the page title, and the search control. You’ll notice that there’s still some evidence of CSS styling on the page (the red text with a blue background) – this is because I have an “alternate CSS URL” specified in my Site Master Page settings (Site Actions -> Site Settings -> Modify All Site Settings -> Master Page).

These classes are inherited regardless of the master page you use, and take precedence over any CSS classes files defined in files in the <head> section of your master page. You’ll also note that the console and site actions menu are there, but only because we specifically put controls in there for them (PublishingSiteAction:Console and PublishingSiteAction:SiteActionMenu, respectively). You can delete these controls without breaking the master page, but you might find it difficult to interact with your site afterwards.

Another field control worth mentioning is <asp:ContentPlaceHolder id=PlaceHolderMain runat="server"></asp>. This content placeholder defines where the main content of your page goes – in the first screenshot, everything you see rendered below the console is inside PlaceHolderMain. But really, PlaceHolderMain is just another ContentPlaceholder that makes room for the content defined in the page layout – this just happens to be where we put the field controls for the core page content. You can adopt this scheme, or modify it to fit your needs.

So now that you have a site running with our minimal master page, where do you go from here? Anywhere, really; you can start inserting your own markup, CSS, and controls to build your site the way you want it to look. Let me provide an example of how you might proceed: say you want to show the navigation breadcrumb above the page content similar to the way we do in BlueBand.master. The contentPlaceholder for this is:

    <asp:ContentPlaceHolder id="PlaceHolderTitleBreadcrumb" runat="server">

So, find this in the list of ContentPlaceholders within the <asp:Panel> included in the minimal master page, cut it, and paste it above the PlaceHolderMain tag. Save the master page, and your site will now render with a breadcrumb, as long as the page layout you’re using has a block overriding this placeholder. If this is not the case, you can define “default” behavior in the master page that defines what the ContentPlaceHolder will contain if is it not overridden in the page layout. For example, you could replace the empty ContentPlaceHolder tag with this markup:

    <asp:ContentPlaceHolder id="PlaceHolderTitleBreadcrumb" runat="server">
        <div class="breadcrumb">
            <asp:SiteMapPath ID="siteMapPath" Runat="server" 
              SiteMapProvider="CurrentNavSiteMapProviderNoEncode"
              RenderCurrentNodeAsLink="false" 
              CurrentNodeStyle-CssClass="breadcrumbCurrent"
              NodeStyle-CssClass="ms-sitemapdirectional"/>
        </div>
    </asp:ContentPlaceHolder>

Your site will now render with this specified “default” breadcrumb if your page layout doesn’t specify otherwise. Note that this markup was taken directly from BlueBand.master – even if you’re starting from scratch with a minimal master page, there’s nothing wrong with borrowing markup from the pros :)

Most of you will probably want to add some CSS references to your master page. Yet again, peering inside BlueBand.master, we see a bunch of markup in the that looks like the following:

    <SharePoint:CssRegistration name="<% $SPUrl:~SiteCollection/Style Library/~language/Core Styles/Band.css%>" runat="server"/>

You can substitute markup like this for a standard <link rel=StyleSheet href="blah/foo/yuk.css"> tag, but the cool thing about doing it our way is that your master page will continue to work if you copy it (along with the referenced CSS file) to another site collection, or the URL for your existing site collection changes. Feel free to reference our stylesheets (like Band.css, Controls.css, and the like) in your master page, or upload your own CSS files to the Style Library and refer to those.

Hopefully this will give some of the more adventurous web developers out there a head start towards building the perfect master page. I’ll be following up with more entries containing tips, tricks and guidelines for the intrepid MOSS 2007 developer – so shoot me feedback if you want me to talk about something specific!

- Lincoln DeMaris, Program Manager