Templating field controls in MOSS page layouts

The very first MOSS 2007 project I worked on started last year, during the second beta release. There wasn’t a lot of information available yet on how to use the product, so I had to make a few discoveries on my own. Of them, this has turned out to be the most useful, and I still haven’t seen a lot written about it (although I haven’t had much time to keep up on blog reading lately, so I’m not claiming to be the only person who has discovered this technique).

The project had a requirement for a summary links field control with a heading over it, something like:

Useful Links

• Link 1
• Link 2
• Link 3

Here was the stickler requirement: the heading needed to be hidden if there were no links in the field control. One approach was to hard code the heading in the page layout and use JavaScript to dynamically hide the heading element if the field control was empty. Not very elegant, and wouldn’t work if someone happened to have JavaScript functionality turned off in their web browser. Another recommended approach was to create a page layout for each possible combination of hidden and displayed fields– an option that quickly becomes unmanageable the more optional fields you have.

I was really interested in the DisplayTemplate property available on all the out of box field controls, but at first I had no idea how to use it. Experimentation with the property showed that populating the DisplayTemplate for a simple text field worked like a charm, but for things like Summary Links & Rich HTML Content, it looked like the field controls just completely ignored the DisplayTemplate contents.

How annoying!

A couple of new articles cropped up in the SDK around the same time that gave me a big clue and I was able to work out the rest even though the documentation is still a little… incomplete.

I started with the vaguely useful “How to: Create a Custom Field Control“. Obviously if I wanted a field control that both displayed summary links data and used the DisplayTemplate property, I was going to have to write my own. That article got me started on writing a custom field control, but I still wasn’t 100% sure how I could implement the DisplayTemplate itself. However, one clue was that you could create an .ascx file that would allow you to template a field control.

Since we were dealing with .ascx files, I had a look in the 12\TEMPLATE\CONTROLTEMPLATES folder and examined DefaultTemplates.ascx file for more information. This had a lot of markup in it that went something like:


<SharePoint:RenderingTemplate ID="*unique identifier*" runat="server">
<Template>
*Markup stuff here*
</Template>
</SharePoint:RenderingTemplate>


So I set up a new .ascx file with the above and my own markup & copied that to CONTROLTEMPLATES. It looked more or less like this:


<SharePoint:RenderingTemplate ID="CustomLabelField" runat="server">
<Template>
<div class="field_section" id="field_wrapper" runat="server">
<h1><SharePoint:FieldProperty ID="FieldProperty1" PropertyName="Title" runat="server"/></h1>
</div>
</Template>
</SharePoint:RenderingTemplate>


I then created an appropriate feature.xml and elements.xml and installed my new control as a feature by following the documentation here:
http://msdn2.microsoft.com/en-us/library/ms470880.aspx

Creating the feature centralised my DisplayTemplate so if I ever needed to modify the markup, I wouldn’t have to modify every single field control in every single page layout.

The next step was to create my own custom field control that worked out what type of field control it should be displaying and dynamically adding it into my field_wrapper div element before rendering, and then checking the ItemFieldValue for whether my field_wrapper div should be visible or not. For that I used the new How to: Create a Custom Field Control article for ideas. The key was using the TemplateContainer property to find the server side controls in my template that I needed to populate, e.g.

protected override void CreateChildControls() {
base.CreateChildControls();
// Check in the template for a div that wraps around all
// the content. The visibility on this div will be switched
// off if the field is empty of content.
this._divWrapper = this.TemplateContainer.FindControl("field_wrapper") as HtmlGenericControl;
// add in the field's display label, determine visibility for the wrapper div
...
}

After adding my new field control as a SafeControl to the web application, I can add the following into my page layout file:

<%@ Register Tagprefix="Custom" Namespace="Andrea.SharePoint.CustomControls" Assembly="Andrea.SharePoint.Custom" %>
...
<Custom:FieldWrapperFieldControl runat="server" FieldName="Useful_x0020_Links" DisplayTemplateName="CustomLabelField" />

Et voila! I had a custom field control that would “switch off” in published mode when empty, was editable and behaved exactly as the original field control for the type of field being displayed, and would display nicely formatted output with the field’s label as a heading tag above the field.

Hope you found this article useful.