SharePoint Magazine » usx

Customizing the User Experience of SharePoint: Custom fields deep dive (Part 5 of 6)

furuknap — Wed, 25 Feb 2009 07:12:58 +0000

Part 5 of the “Customizing the User Experience of SharePoint” series. This day we also celebrate the third day of SharePoint User Experience week here on SharePoint Magazine. One full week, focusing only on understanding SharePoint architecture from a user experience point of view. If it could be any better it would have to be covered in chocolate.

The Customizing the User Experience of SharePoint series aims to explain how the user experience works, from how the interface is built down to details on how columns of lists get created.

The series is also an exclusive preview of the topics from my upcoming book, “Building the SharePoint User Experience”, which deals with SharePoint user experience for 350 pages. Actually, as with this series, the book explains the SharePoint architecture from a user experience perspective.

Here is an article outline for the six parts:

Part 1: Overview of the default SharePoint interface from a technical point of view

In the first article we will look at how the default SharePoint interface is built. We will look at a site, going from top-down, explore some of the the default lists, the fields used to create the basic field types, which content types are available, and how list forms are rendered.

Part 2: Modifying the default experience

This article will show you which options are available for you to modify and improve the default setup. Learn how to override the default rendering of fields or forms without voiding your supported state.

Part 3: Lists and custom list forms

The third article will cover the basics of customizing lists using different views, custom list forms, and fields.

Part 4: Content types user interface

The next article will explore how you can utilize content types to display different input forms and display forms.

Part 5: Custom fields deep dive

Ever wanted to create a new field type? SharePoint enables you to do this and it is a very powerful tool for customizing the user experience.

Part 6: Fast track to feature generation

Writing custom lists with content types by hand can take a massive amount of time. In the final installment I will share with you some tools and techniques that makes list, field, and content type generation very fast.

Don’t fear if you think the previous parts have contain too little code, however, for this time we are creating custom field types. But first, we need to understand how columns work in SharePoint

Columns or fields?

Before we go any further I’d like to clarify the use of the names fields, field types, and columns.

In most cases columns and fields refer to the same thing, namely the names of the individual items we use to store data in a SharePoint list item. The confusion may come from the use of the name Column in the web interface and the name Field in code. when you go to add a new column/field to a list or a content type the term ‘column’ is used, but when you write a feature to deploy a new site column or a content type that has columns you suddenly use the name Field.

To confuse even further there’s the concept of field types. Field types are types of data. Compare this to SQL you may think of nvarchar, bigint, and datetime. However, field types are more complex as they also include the visual rendering of the data, both for input and display.

To make sure we are clear in this article I’ll use the name Column and not Field while referring to the columns of a list.

Site columns and list columns

You can define columns on two levels, either on the site level or on the list level. Site columns are useful if you intend to use a column in multiple lists. Rather than having to define all the settings for every list, you can define a site column with all the settings and add that site column to the lists.

Site columns are your only option if you intend to use your columns in content types. List columns are available only for a particular list. For lists, you can use either site columns or list columns. Or, actually, you can use list columns only. Or, actually, you can add site columns, but they become list columns. Oh, I know this may be confusing. Let me explain.

On the list or library settings page, you have the option to either create a new column or add an existing site column. If you choose the latter, a copy of the site column is made using the same field ID as the site column. The copy becomes a list column.

The use of similar ID values for both the site column and the list column maintains the parent-child relationship. This relationship means you can make changes to the site column and optionally have all child columns inherit those changes.

This is a good thing, because it means that the list column is detached from the site column when you want it to be, but it can still maintain its relationship to the parent site column. An example might clarify this.

Let’s say you have a site column named Recipient used to store who will receive reports from different departments. You add that field to a new list for a new department, but then the department head comes to you and says that the column needs to be named “Target manager” instead.

In this situation, you can simply go to the list settings and change the name of the column on that list. Had you changed the site columns, every occurrence of the Recipient column would be changed, and other departments might not like that.

Site Columns in Content Types

What might spin your head a bit later is when we start to consider how content types work in this scenario. As I mentioned in the previous part of the series, content types use only site columns, so if we want to change a column for a content type on a list, we might be in trouble. And, if content types are so cool and we should use them as often as we can, how can we have such a limitation?

The answer is that content types also create list column copies of their respective site columns. When you add a content type to a list or library, all the site columns of that content type are copied into list columns on a list.

Problem solved.

Site Columns in CAML

To add site columns using the web interface, you simply go to the site where you want to column, then go to the Site Settings page and finally select the site columns. Create your site column by clicking Create, fill in the form, submit it, and live happily ever after. You can do this on any site.

Creating a basic field using a feature is slightly more complex, but not much. First, create a new feature, and make sure your feature scope is set to site, not web. With WSPBuilder, this is as easy as creating a new WSPBuilder project and adding a new item of the Blank Feature. You’ll learn plenty more about WSPBuilder in the next part of this series.

As with content types, site column features are site scoped, and of course you remember that site in this feature context means site collection. The ID of the field needs to be unique to the entire site collection to support content type inheritance and to allow site columns to be used in child sites.

Yes, that’s correct. Columns have scope just like content types. If you define a site column in one site, all child sites will also be able to use that column. Site columns and content types are closely connected.

Let’s get back to your feature. now—In your elements file, add a Field element as such:

http://schemas.microsoft.com/sharepoint/”>
ID=”{053EC00E-D451-4733-8CA0-31532C974E91}” Type=”Text” >

Now, before you take even a sip of your coffee or even draw another breath, pay very close attention to the following: Unlike other GUID examples, you must use brackets in the GUID ID value when defining site columns. Do not forget this.

When you build and deploy your new feature, and of course remember to activate from the Site Collection Features page you should see your new site column on the Site Columns page. This also means that your site column is now ready to use in any content type or list as you see fit.

To limit the scope and ask you to notice the Type which is Text as this is important to our next step when we look at field types.

Field Types

Columns in SharePoint may be analogous to columns in a SQL table. If so, field types are analogous to the data types in SQL such as ntext, bigint, datetime, and bit. Actually, the correct way of thinking this is that a field type value is approximately the same as a SQL data type, while the field type itself is a bit more complex. Bear with me a second if you’re confused, I’ll try to clear things up a bit.

A SharePoint field type comprises several elements that handle the storage and the rendering of the field type. The easiest thing is to break these elements into three classes:

Field Type

This is the code element, defined as a .NET class, which ties together the value and visual representation of the field.

Field Type Control

This element is responsible for the visual rendering of the field, also a .NET class, and with an optional ASCX user control to render the output.

Field Type Value

Finally, the field type value handles storage of the data in columns based on the field type, again, this is a .NET class. For simple string values this class is optional.

When you first start to look at custom field types you may be very confused from how these elements interact, but once you start looking at what happens in each element, everything clears up a lot. We will get to that in a moment.

In addition to the three elements defined above you also have a Field Type Definition. This is really the simplest element as it is a plain XML file that only describes the field type to SharePoint. These field type definitions are stored in the [12]\TEMPLATE\XML folder inside files that are named fldtypes_XXXXXX.xml, where XXXXXX is an arbitrary string. The built-in field types are stored in the file called fldtypes.xml.

Let’s start out with this field type definition and work our way from there.

Before we being, however, note that field types are not deployed as features. Field types are global to the farm and as such should be deployed as a solution.

Building your first custom field type

Start by creating a new WSPBuilder project. You have WSPBuilder, right? Call it whatever you like, I’ve called mine SPMType. WSPBulder automatically creates a signing key and sets up your project to be signed.

Next, add a TEMPLATE folder under the 12 folder, and then an XML folder under the TEMPLATE folder.

Inside the XML folder, add a new XML file, called ‘fldtypes_SPMType.xml’. Or, choose another name, as long as you adhere to the fldtypes_XXXXXX.xml format.

Your solution explorer should now look like this:

Field Type Definition

Open the fldtypes_SPMType.xml file and add the following XML code. I’ll explain each element afterwards:

SPMType
Text
SPMType
Description for SPMType
TRUE
TRUE
TRUE
TRUE
[5-PART STRONG NAME]

You need to modify the FieldTypeClass element to insert the 5-part strong name of your field type class which we will create in a moment.

Each of the Field elements has a Name that is used to define the field type we are creating. The TypeName is the internal name used when we create columns from this field type. In the site column we created above this would match the Type attribute, which in our example was Text.

The ParentType is also vital, as it defines one of several root types from which our custom field type will inherit. You must always inherit your custom field type from another field type.

The TypeDisplayName and the TypeShortDescription are only for your eyes’ enjoyment, you can enter whatever values you like here. the UserCreatable states if users should be able to create new columns from this type, while the Sortable and Filterable states if the columns created from this field type should be sortable and filterable, respectively.

The AllowBaseTypeRendering specifies whether the field type should fall back to its parent rendering in case of problems rendering the field type.

Now for that FieldTypeClass.

WSPBuilder will happily sign your assembly for you to create a strong-named assembly. However, this only produces the four-part strong name. We need to prefix this four-part name with the name of our class. Which class you ask? Ah, we get to that when we create the…

Field Type Class

First, make sure you have added a reference to the Microsoft.SharePoint.dll to your project.

In the solution explorer, add a new class file to the root of your project. Name it something like SPMFieldType.cs. If you like, put it in a folder, but in any case, open the .cs file and add the following code:

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;

namespace SPMType
{
public class SPMFieldType : SPFieldText
{
public SPMFieldType(SPFieldCollection fields, string fieldName)
: base(fields, fieldName)
{
}

public SPMFieldType(SPFieldCollection fields, string typeName, string displayName)
: base(fields, typeName, displayName)
{
}
}
}

One small thing first, before I forget. Let’s grab that five-part strong name we needed for the field type definition. First, build your solution, you may use the the WSPBuilder->Build WSP. Next, find the four-part strong name of your assembly. Finally, add the namespace.classname to the front of the strong name to create a five-part strong name. In my assembly this looks like this:

“SPMType.SPMFieldType, SPMType, Version=1.0.0.0, Culture=neutral, PublicKeyToken=817b2cbd5ec31d67”

Your PublicKeyToken will be different, as may your assembly, class, and namespace names.

Add this string to the FieldTypeClass element in your fldtypes_SPMType.xml field definition file.

Back to the class, we are inheriting from the SPFieldText class which makes sense since our parent type is Text. However, we are not bound by this, we can use any of the other SPFieldXXXX classes as the parent class for our own field type class.

Next we need to implement the constructors for our class, and SPFieldText determines the signatures for these constructors. For our class we don’t actually need to do anything but call the base constructor, but you can add functionality here to implement custom property handling or add other features as you see fit.

At this point we have actually created all we need to get our custom field type up and running. Of course, we’ve just created the most useless custom field type there is, as all we have done is implement the SPFieldText type, which is quite well done already by the built-in field type Text. However, we have a frame into which we can put a beautiful picture, so for now, just build (WSPBuilder->Build WSP) and deploy (WSPBuilder->Deploy) and sit back and wait. No need to activate anything, remember that custom field types are not deployed in features, so your field type will be available once the solution is deployed. Check this out in the Create new column of a list or when you go to create a new site column:

If you add a column based on your new field type, it will behave exactly like a regular Text type, since we haven’t really added anything ‘Custom’ yet. Let’s add custom to the equation now.

Custom Field Type Control

Our first order of business is to create a control class to act as the rendering control for our new field type.

Start by adding a reference to System.Web since we will now deal with creating web controls.

Continue by adding yet another class file to the root of your project, this time called ‘SPMFieldControl.cs’ or something along those lines. To that class, add the following code:

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;

namespace SPMType
{
public class SPMFieldControl : BaseTextField
{
}
}

Note that we are inheriting from the BaseTextField class. Again, this is nothing extraordinary since we are creating a text class field type. However, for other field type classes you might want to inherit from another control.Here is a list of some of the Field controls from which we can inherit:

AllDayEventField
AttachmentsField
AttendeeField
BaseChoiceField
BaseTextField
BooleanField
CalculatedField
ComputedField
CrossProjectLinkField
DateTimeField
FieldValue
FileField
FormField
LookupField
ParentInformationField
RatingScaleField
RecurrenceField
UrlField
UserField

In addition, several of these, such as the BaseTextField have child types from which you also can inherit. The BaseTextField for example has BaseNumberField, NoteField, and TextField as child classes, and even more grand-children classes.

For our purposes, however, I really just want to show you the anatomy of a custom field type control, so we’ll base our control on the BaseTextField class.

First we must tell the control which template to use for rendering the control. We do this by overriding the DefaultTemplateName property as such:

protected override string DefaultTemplateName
{
get
{
return “TextField”;
}
}

The TextField is the default rendering template used for the single line of text field types we are mimicking. If you recall from Part 2 we looked at the DefaultTemplates.ascx file in the [12]\TEMPLATE\CONTROLTEMPLATES folder. This file also contains the TextField rendering template. This template is incredibly simple, but will do for the moment.

At this point our control behaves like the default single line of text. Let’s add something to make sure we’re doing things right. Let’s override the RenderFieldForDisplay method which is use to, well, Render Field For Display. Bet you didn’t see that coming…

Add the following override to your SPMFieldControl class:

protected override void RenderFieldForDisplay(System.Web.UI.HtmlTextWriter output)
{
output.Write(“Custom displaymode: “);
base.RenderFieldForDisplay(output);
}

Again we’re simply relying on the underlying BaseTextField to do most of the manual labor, however adding the “Custom displaymode: “ enables us to see that we are in fact modifying the rendering of the field.

I’ll show you some more advanced samples in a moment, but for now, let’s connect our new field type control to the field type we created earlier. To do this, go back to your SPMFieldType.cs file, and add the following override to your class:

public override Microsoft.SharePoint.WebControls.BaseFieldControl FieldRenderingControl
{
get
{
SPMFieldControl c = new SPMFieldControl();
c.FieldName = this.InternalName;
return c;
}
}

You might want to add a ‘using Microsoft.SharePoint.WebControls;’ statement by the way, but that’s just for prettier code.

This code instantiates an object of our new control class and assigns the FieldName of that object to the field type internal name.

Finally, build your WSP as described above and redeploy. You may need to do an IISRESET to get your changes updated.

Try creating a new column based on your field type on a list and then add a new item. You will notice that the new column behaves exactly like a text field

I bet by now you’re going: “Aw, come one, we haven’t seen any custom rendering at all, only mimicking of the default single line of text”. Patience, young Skywalker.

Add your new item and the display that item. Let’s see if your 1 second of patience has paid off:

Wohoo! Congratulations, you’ve just made… Well, absolutely nothing if you ask your boss, but hey, you made it yourself, right? That’s got to be worth something. Let’s see if we can impress your boss as well.

Oh, yeah, the date. I got a bit delayed writing this article.

One Step Further

Ok, so we have wired up our field type and we have connected that field type to a field control. We might as well utilize that to our advantage.

We want to create our own rendering template and not rely on the DefaultTemplates.ascx template. After all, we might want to add a nice Ajax control, or perhaps even a Silverlight control? No, I wont do that for you, that’s a completely different show, but I’ll show you how to create your own rendering template.

First, in your solution explorer, add a folder named CONTROLTEMPLATES to the TEMPLATE folder under the 12 folder.

Inside the CONTROLTEMPLATES folder, still in solution explorer, add a new Text file, and name it MyCoolTextBox.ascx. Using a text file but naming it .ascx makes Visual Studio recognize the file as a web user control even if this is not a web project.

Next, open the MyCoolTextBox.ascx and add the following outline:

<%@ Control %>
<%@ Assembly Name=”Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c” %>
<%@ Register TagPrefix=”SharePoint” Assembly=”Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c”
Namespace=”Microsoft.SharePoint.WebControls” %>

Now, inside the Template tag, let your designers go bananas. Yes, I mean bananas, designers always love that. I’ll add one provision for now: Make sure you have an ASP:TextBox control with an Id of “TextField”. I’ll explain why in a moment. Besides that, do whatever you like.

Finally we need to tell our control to use the new rendering template. Go back into the SPMFieldControl and update the DefaultTemplateName override as such:

protected override string DefaultTemplateName
{
get
{
return “MyCoolTextBox”;
}
}

By the way, if you ever get the error ‘Corrupted control template. Please check RenderingTemplate of “TextField” in the control template ascx file.’ while working with the BaseTextField class, don’t bother checking your TextField template, as the name ‘TextField’ is hardcoded in the Microsoft.SharePoint.dll. I just spent two hours chasing after the wrong rendering template. Now you don’t have to.

Back to our fancy new rendering template. Before you go and deploy your new WSP, uninstall the old one using WSPBuilder->Uninstall. The reason is that by default WSPBuilder will upgrade your solution. Upgrading a solution does not add new files, and since we just added our new ascx control we need to make a clean install. After the uninstall completes, go ahead and deploy as normal.

Depending on what you decided to put inside the Template tag of your control you will see your changes when you refresh your Edit or New form. I’ve added

to my control and get this:

For some reason I never got a job offer as a designer. Go figure, I think this looks beautiful.

Before I wrap up with some final thoughts and some further resources for you, I’d like to explain a bit of the magic that goes on here. You see, when we inherited our control class from the BaseTextField class we got a ton of free functionality. The BaseTextField searches for a TextBox control with an Id of “TextField” inside whatever renderingtemplate we send it. If the BaseTextField finds such a TextBox it gladly hooks up all the required functionality for us, including populating the TextBox with the right values when editing. This happens in the CreateChildControls() method of the BaseTextField class.

By not overriding the CreateChildControls() in our own class we basically get that functionality for free. See why having a TextBox with an Id of “TextField” makes sense now? Of course, you can override the CreateChildControls() if you want absolute and complete control over the building of your control, but I think it makes sense to let Microsoft work a bit for all the money we send them, and letting them handle as much of the nitty-gritty details as possible is at least sensible to me.

Wrap Up and More Resources

Ok, before you all go yelling at me for not including details on writing your own field type value, remember that this is a user experience series, and I hardly see how managing data internally is part of the user experience. Also, this article is quite long enough as it is, so instead I’ll point you to another article here no SharePoint Magazine: Developing a SharePoint Custom Field Type for Displaying CRM 4.0 Data. This article also shows you how you can use a code-behind file as part of your control.

I do hope I have conveyed a bit of knowledge, however, both on columns and on custom field types, and that you are left with a bit more confidence when facing one of the most complex tasks a SharePoint developer will face.

Tomorrow I’ll take you on a fast-track to feature generation and show you how you can speed up your SharePoint feature development by using the right tools and utilizing the web interface to create a lot of the nitty-gritty CAML required for features.

Don’t forget to leave feedback. If you have questions or comments I love to hear about it!

Customizing the User Experience of SharePoint: Content Type User Interface (Part 4 of 6)

furuknap — Tue, 24 Feb 2009 07:00:12 +0000

After a considerably shorter break, it is time for the fourth part of the “Customizing the User Experience of SharePoint” series. This article is also the second day of SharePoint User Experience week here on SharePoint Magazine. One full week, focusing only on understanding SharePoint architecture from a user experience point of view. Christmas all week long, if you ask me.

The Customizing the User Experience of SharePoint series aims to explain how the user experience works, from how the interface is built down to details on how columns in lists get created.

Here is an article outline for the six parts:

Part 1: Overview of the default SharePoint interface from a technical point of view

Part 2: Modifying the default experience

Part 3: Lists and custom list forms

The third article will cover the basics of customizing lists using different views, custom list forms, and fields.

Part 4: Content types user interface

The next article will explore how you can utilize content types to display different input forms and display forms.

Part 5: Custom fields deep dive

Ever wanted to create a new field type? SharePoint enables you to do this and it is a very powerful tool for customizing the user experience.

Part 6: Fast track to feature generation

This time, however, we’ll focus on a really cool feature of SharePoint…

Content Types

If you haven’t worked with content types before you haven’t worked with SharePoint since WSS2 and the SPS2003 era. You may not realize this, but Content Types are the method by which you store data in SharePoint, whether you like it or not.

Content Types are schemas for information, defining what your items or documents should contain, how they should behave, and, most importantly for us in this article, how they should appear.

Before we go into user experience customization of content types, you should also know a few more things about content types:

Everything stored in SharePoint uses a content type, even if you do not explicitly enable content types on a list or library.
Folders themselves are just special items created from a folder content type.
Content types can also store metadata about their derived items.
Content Types support inheritance, meaning you can have a content type hierarchy and store common information in a parent type.
Scoping of content types means you can target content types to specific site collections or sites and have child sites have access to the same content types.

The second issue of Understanding SharePoint Journal deals exclusively with content types, showing off some of the magnificent things you can accomplish if you understand this technology.

However, for this article we will focus on learning how we can make content types appear the way we want.

The Anatomy of a List Form

As we have explored earlier in this series, list forms are customizable forms used to display, edit, or create new items in a list. These forms are made up of form pages, which we can customize to make a nicer interface for the users. For most of the default list templates in SharePoint, a single ASP.NET page, the [12]\TEMPLATE\Pages\form.aspx page, is used to render all list forms.

However, in a single list we can have multiple content types. For example we can have a document library store both Financial and Legal documents, each of which may require a separate set of metadata. There must be a way for SharePoint to know which set of metadata to display or which form fields we need to fill in to update or create an item.

The answer is that a list form is made up of two parts. One is the list form page, which determines the outline of the form. The other part is the content type form, which defines the specifics of the individual item or document.

In the above image, the area inside the red square is made from the content type’s display form, while the rest of the page is made up of the list’s display form. Of course, the list form page can also be made up of master pages and regular content, as is the case for all the default list forms.

There is also another option, which is to have the whole page tied to a content type. In such a case, the list form page would not be used at all. We will look at this in a moment.

Now, to understand how this anatomy is constructed we need to dig a bit into how content types are created and learn a bit about how content type inheritance works.

As you would also know you can override these forms by creating a new .ascx user contol in the CONTROLTEMPLATES folder and put a SharePoint:RenderingTemplate control inside with the same ID as the template you want to replace.

Content Type inheritance

Content types support inheritance, with a bit of a peculiar method of defining inheritance. In simple terms this means that you can create a hierarchy of content types, just like a class hierarchy, and have child content types inherit properties from parents and grandparents.

What differs significantly from other hierarchical systems is a rather awkward method for describing inheritance in SharePoint content types. Every content type in SharePoint has a unique identifier, the content type Id. When you create a content type you define a content type id that is of the format 0xNNNNNNN where NNNNNNN is a number. That number not only identifies this content type but also from which parent content type we should inherit. That’s right, no kidding, inheritance is hidden inside the identifier string.

All you need to do to inherit from a content type is to include the parent content type id in your content type id and then add a few numbers.

Crafting Content Type IDs

Oh, yeah, how you add those numbers matter a great deal. Let’s look at the default content types to see how this is done. Open the [12]\TEMPLATE\FEATURES\ctypes folder and then the ctypeswss.xml file. This is where all the default content types are defined.

First, notice that the first ContentType element, named System, has an ID value of 0x. All content types must inherit at least from this system content type. The type itself defines only a single column or field reference, the ContentType field.

The next content type is the Item content type, and you can see from the ID value the first method of creating inheritance. Adding two numbers, for example 01, 02, or 99, is one way of inheriting from a parent type. If you wanted to inherit directly from System you could have your content type have and id of 0×02, 0×03, etc.

The other method for crafting content type ids is to add 00 and then a Guid string without the hypens. For example you may have an id that inherits directly from Item as such:

0x01001A48C1A2B071432EACA85A0A35FF5185

Break that ID down and you will see System (0x), Item (01), two zeros (00), and a GUID (1A48C1A2B071432EACA85A0A35FF5185).

The properties of a content type are inherited from its parent. In the Item content type this means we inherit the ContentType column from System, and, as you can see, adds a new field, the Title field. In addition the Item content type defines an XmlDocument which contain a FormTemplates element. Inside the FormTemplates are names of forms that will be used for display, edit, and new forms for items based on the Item content type. And, knowing that these properties are inherited we can deduce that all content types inheriting from Item will use the ListForm template.

Overriding property inheritance

Now, using the same form for all content types may be a bit too limiting for you. You’ll be thrilled, I’m sure, to learn that you can override any property for child content types simply by adding an overriding value. The Document content type is an examle of this. To examine property overriding, scroll further down in the ctypeswss.xml file to the Document content type, which, in my file, is around line 32.

Notice that the Document content type adds the Title field again, even if it is added in the parent Item content type. If you examine the FieldRef elements of Item and Document, however, you will notice that the attributes differs. This way, in Document based items, the Title is not required, and will not appear in NewForm.

Item Title FieldRef:

Document Title FieldRef:

Another thing to notice is that Document also overrides the FormTemplates to replace these with DocumentLibraryForm.

Customizing Content Type Forms

Now, as I am certain you have been reading the first and second parts of this series you know a few things about where these forms are actually stored. To remind you, the default forms used by SharePoint, such as ListForm and DocumentLibraryForm, as stored in the [12]\TEMPLATE\CONTROLTEMPLATES\DefaultTemplates.ascx file.

However, that may not be a possibility for you. First of all, overriding is am all-or-nothing deal; you override for all templates throughout the farm. Second you can only override once, meaning if you have overridden the ListForm template once you cannot add a second ListForm template and expect some magic to determine which one will be used. In fact, from what I’ve been able to deduce, file naming determines which rendering template will be used if you add two templates with the same Id. In the next image I have added two rendering template files, one called aform.aspx and one called bform.aspx, both of which simply displays a text, either A or B, and as you can see, the B Form is used:

However, I do not actually know this since this part of the code in Microsoft.SharePoint.dll is obfuscated.

Still, nothing prevents us from creating our own forms for use with our own content types.

Start out by creating a new .ascx file in the [12]\TEMPLATE\CONTROLTEMPLATES folder.
Name it whatever you like. Next, copy the directives from the defaulttemplates.ascx file:

<%@ Control Language=”C#” AutoEventWireup=”false” %>
<%@ Assembly Name=”Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c” %>
<%@ Register TagPrefix=”SharePoint” Assembly=”Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c”
Namespace=”Microsoft.SharePoint.WebControls” %>
<%@ Register TagPrefix=”SPHttpUtility” Assembly=”Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c”
Namespace=”Microsoft.SharePoint.Utilities” %>
<%@ Register TagPrefix=”wssuc” TagName=”ToolBar” Src=”~/_controltemplates/ToolBar.ascx” %>
<%@ Register TagPrefix=”wssuc” TagName=”ToolBarButton” Src=”~/_controltemplates/ToolBarButton.ascx” %>
<%@ Register TagPrefix=”WebPartPages” Namespace=”Microsoft.SharePoint.WebPartPages”
Assembly=”Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c” %>

Then, just to make things simple, copy the ListForm rendering template from the same file, but change the ID from ListForm to MyListForm. Make some random change to recognize your custom form, for example by adding My list form after the Span HTML tag:

Congratulations, you’ve just created a new content type form.

Now you need to attach it to a content type. I’ll walk you through a simple example to demonstrate.

Create a new site content type from the site settings page. Name it whatever you like, and inherit from the Item content type. Add some site columns if you like.
In a test list, go to list settings and then Advanced Settings. Enable ‘Allow management of content types’ and hit Ok.
Back in the site settings, add a content type from existing site content types, and add your new content type.
Go back the list and add a new item based on your content type.

Now we have an actual content type to which we can attach our new form.

Get SharePoint Manager 2007. Yeah, it’s free, and it’s the best tool you’ll ever own, including whatever free chocolate machine you may already have.
Browse to the site where you created your content type and open the Content Types node. Locate your new content type.
In the properties window, locate the DisplayFormTemplateName. Notice that it is set to ListForm. Change this to MyListForm and then hit Save. I’ll repeat the last instruction. Hit Save.

In case you missed it, you need to hit Save before your changes are added to SharePoint.

Next, re-open your item in the list.

And at this point you are likely going to be very angry with me because your form will not work at all and be completely blank. However, there is a very reasonable explanation for this, and I just wanted you to see this error, since I make it myself all the time.

You see, control templates are only read after an IISRESET. So, to make your wonderful new form appear, simply IISRESET (c:\>iisreset) and your form should appear just fine, including your customizations:

Cool, eh?

Stop being so cool!

Ok, I think we had enough for this article. We’ve covered the basics of content types and examined how inheritance works. You’ve seen how content types are defined and also how you can create your own content type forms.

However, this is only the beginning of content types. If you think what you have seen here is cool, issue 2 of Understanding SharePoint Journal will totally blow your mind. We’ll examine behavior with workflow and event receivers, look at how folders are content types and how you can use this in SharePoint, and also how you can extend your content types using XmlDocuments.

As of this writing, issue 2 is not out yet, but you can always sign up for the Understanding SharePoint Journal mailing list to be notified when the issue ships. Or, if you are reading this article later than the issue date you can visit the USP Journal webpage and grab a copy.

The next part of this series will deal with columns and field types, teaching you the basics you need to understand how these elements influence the user experience.

Until next time, however I hope you have a great time with what you’ve learned here.

Customizing the User Experience of SharePoint: Lists, Custom list forms, and CAML Views (Part 3 of 6)

furuknap — Mon, 23 Feb 2009 06:55:36 +0000

Finally, after a very, very, very, vey, very, very long break, here is part 3 of the “Customizing the User Experience of SharePoint” series. This article also launches the SharePoint User Experience week here on SharePoint Magazine. One full week, focusing only on understanding SharePoint architecture from a user experience point of view. It doesn’t get any better than this.

The Customizing the User Experience of SharePoint series aims to explain how the user experience works, from how the interface is built down to details on how columns of lists get created.

Here is an article outline for the six parts:

Part 1: Overview of the default SharePoint interface from a technical point of view

Part 2: Modifying the default experience

Part 3: Lists and custom list forms

The third article will cover the basics of customizing lists using different views, custom list forms, and fields.

Part 4: Content types user interface

The next article will explore how you can utilize content types to display different input forms and display forms.

Part 5: Custom fields deep dive

Ever wanted to create a new field type? SharePoint enables you to do this and it is a very powerful tool for customizing the user experience.

Part 6: Fast track to feature generation

A Short Recap

It’s been a while since the last article, so I thought that at least I should post a short recap of where we have been, in case you cannot be bothered to read Part 1 and Part 2.

In the first part we examined how a site was built from various different XML files, including webtemp.xml, onet.xml, and the global site definition. We then briefly touched on list templates, content types, list forms, columns and fields, and views, mostly to know what was ahead.

In the second part we looked at some methods we can use to customize the default user experience and learned what will break out supportability. We examined CustomActions and saw how we can override ControlTemplates to modify how visual elements of a SharePoint site are rendered. I also mentioned two other articles here on SharePoint Magazine that deal with custom master pages and feature stapling.

On that note, however, I would like to point out that these methods are not your only options for customizing the default user experience. One thing that really deserves more attention is DelegateControls, a method by which you can add content to a page using a feature. This is how Search Server and MOSS changes the search box and adds ‘My Site’ and ‘My Links’ as well as the publishing console.

Back to lists.

Lists and List Templates

When I talk to developers, and especially developers who are new to SharePoint, talking about lists is a bit confusing. First, lists seems to be a somewhat ambiguous term, sometimes referring to lists and sometimes referring to list templates. Before we dive into details I want to just make sure you are up to snuff on the difference.

A list template is a template for how new list instances will be created. A list template holds most of the content which will make up the lists, including the default columns, permissions, views, content type bindings, and forms. When you go to the Create page of a SharePoint site, the columns you see, with the exception of the Web Pages column, are filled with the default List Templates that get deployed as part of the Team Collaboration Lists feature.

That last statement is important; the list templates get deployed using features. While you have the option of defining list templates as part of a site definition, you don’t want to do that. If you watched the SharePoint blogosphere a few months back there was a gentle reminder from absolutely every sane person alive to keep as little as possible inside the site definition. I think Andrew Connell has a very nice explanation of why you want to keep stuff in features and leave your site definitions as small as possible.

List instances, on the other hand, are what you create when you click one of the templates on the Create page. These are, as the name implies, instances of the list templates. You store data in a list instance, and this is also where you would add columns, attach workflows to items, etc.

You can deploy list instances using features, and this makes a lot of sense when you are creating a SharePoint solution in which you need to store data for your solution. However, your options for customizing a single list instance through features are a bit limited. For example, you cannot define additional columns to a list using an elements.xml file, nor can you add or modify views in a feature. At least not unless you add a feature receiver and modify the list instance using code.

With these distinctions out of the way, let’s get into the details of how these elements are built and how we can manipulate how the users experience our lists.

List User Experience Options

Users interact with lists using two visual interfaces, the list forms and the views. These are in fact closely tied together as we will see in a moment.

List forms

A list form is a regular ASP.net page the serves as the visual interface of a list. List forms are defined in the list template, but the forms are instantiated in a list instance. This means that we can override the list forms for each list by customizing the list forms that are instantiated with the list.

The list form definitions tell SharePoint from where each list form should be instantiated. If you examine the Custom List list template, located in the [12]\TEMPLATE\FEATURES\CustomList\CustList\schema.xml file, you can see the Forms section near the bottom:

Each of the Form elements you see here represents one state or display mode of list items, as specified in the Type attribute. The Url attribute defines the list-relative Url where the list form will be instantiated. I’ll skip the SetupPath for a moment and tell you that WebPartZoneID defines which webpart in the ASP.NET page should hold the contents of the list form.

The SetupPath tells SharePoint what should be the source of the list form. As we saw in the first part of the series, SetupPath is relative to the [12]\TEMPLATE folder, so if you open [12]\TEMPLATE\pages you should see a file called form.aspx. If you don’t, well, you’re either in trouble or you know extremely well what you are doing. If you open that file you will notice that it is indeed a very normal ASP.NET file. No magic here.

One really important thing to note, however, is that until you decide to customize a list form the form will still point to the source. Changes to the pages\form.aspx will reflect on every list form that still points to the original source.

If you decide to create your own list templates, however, you may point your list forms elsewhere. In that case you would likely replace SetupPath with Path, since Path is feature-relative, while SetupPath is [12]\TEMPLATE relative.

You may want to change a list form for a specific list instance. You now know that each of the list forms gets virtually stored in the path specified in Url attribute. These form pages can be customized using the customization framework of SharePoint. If you haven’t worked with this before, here’s the executive summary:

When you customize a page, meaning you change the ASP.NET code, SharePoint will unlink the page from the source, and copy the page into the SharePoint database. Then, al changes you make to the customized page gets written to the database instead of the source file. SharePoint will keep track of whether your page is customized and retrieve the page from the correct source.

To perform such a customization the easiest method is to grab a copy of SharePoint Designer, or SPD for short. SPD is tightly integrated with SharePoint and fully supports working with customized files. When you start SPD and connect to your site you will be able to browse into the list containing the form you wish to customize. Simply double-click any of the forms to open it and the hit Save to customize the form and remove its link to the source pages\form.aspx. SPD will warn you about customizing forms, but after you click Yes to acknowledge the warning, you are free to modify the list form as you see fit.

You can also define a completely new ASP.NET page to take over any of the existing list forms. This is done, in SPD, by going to the list properties and selecting Supporting Files where you will be allowed to browse for a different page. If you want to do this you must make sure that the new page contains the correct list form to use for the corresponding display mode, either NewForm, DisplayForm, or EditForm. To insert such a form on a page, place the cursor where you want the new form and go to Insert->SharePoint Controls->List forms.

You may not immediately realize that this is a cool thing, but consider this: You can link your list forms to a page stored in a library. That’s right, suddenly your list forms are editable from the web interface, allowing you to customize the user experience of modifying data in SharePoint, all through the web interface.

No more using SPD every time you want to modify the list forms. Cool, eh?

Of course, such an approach carries significant security issues, so you would need to limit permissions to the forms page library or pages. But you should know you have the option.

Speaking of content, which we weren’t, but I need a segue, where do the actual form content enter the scene? All the form elements derives from the same form.aspx source page, so there must be something that tells SharePoint which columns to put into which forms. The answer will be discussed more in part 4, however for now you should know that the actual form, meaning the columns, are not rendered from the list at all, but rather from the content types.

Content types carry their own set of forms that are used to render the display, editing, and new forms for items based of the content type. The cool thing about this is that you can tie the rendering of items to the type of item, not on where it is stored. Override the default forms used and you can create visually stunning displays. Here’s one example I have in the book “Building the SharePoint User Experience”:

You’ll learn how to create content type specific forms in the next art of the series. Note that the title is made using a custom field type, which will be covered in part five.

Views

Your other option for customizing the user experience of list is views. You’ve probably worked with view through the web interface. Basically it is a view of data of a list, such as the AllItems.aspx view, which shows all items or documents in a list.

Strictly speaking, AllItems.aspx is a view page, not a view. The view is All Items, or, as in the previous screenshot, All Documents, but it is displayed on a view page.

These views are declaratively defined in the list template, in the Views section of the schema.xml file. This section defines any views that are available by default for new list instances based on the template. In addition you can create new views after the list has been created either by using the web interface, or, as developers, through code.

However, some more advanced aspects of view creation can not be handled through code or the web interface at all. I am, of course, talking about the dreaded CAML View schema.

CAML view creation

Now, before you go hiding in the closet, swearing not to exit before I promise not to talk more about views, let me calm your fear of custom view development by saying that we will not be doing anything really advanced here. A lot of developers have a natural fear of SharePoint custom view development. However, if you beak down views into manageable chunks, creating custom views is no harder than learning to ice skate. Yes, it is painful the first times you fall, but once you get the hang of it is great fun. And cold. And hard. Oh, well…

Open the Custom List schema.xml, located in the [12]\TEMPLATE\FEATURES\CustomList\CustList folder. Close all elements except the Views element. Next, close the View element with BaseViewId=”0”. This is the default view that is used when you add a list view to a web part using the web interface. By the way, if you create your own list template and you’re unable to add lists based on that template to a web part page you are most likely missing the BaseViewId=”0” view. The error message would be ‘Unable to add selected web part(s). [List name]: List View Web Part could not be added, list may be hidden.

Next, inside the View with BaseViewId=”1”, close the first-level child elements. These would be GroupByHeader, GroupByFooter, ViewHeader, ViewBody, ViewFooter, PagedRowset, PagedClientCallbackRowset, PagedRecurrenceRowset, RowLimit, ViewEmpty, Toolbar, ViewFields, and Query. These elements are what constitutes a view. The good news is that quite often you wont need to deal with all of these, only 4-5 are really necessary. The bad news is that dealing with any of these requires you to write View CAML.

When you feel brave enough, open the ViewBody element, and I’ll walk you through the basics.

ViewBody, by the way, is called once for each list item in our list. This is in contrast with other View elements, such as ViewHeader and ViewFooter, which are called only once.

The Views of a list are usually used to output the HTML we need to send back to the browser, so if you keep thinking that we are building a HTML document it can be a bit easier to wade through all this stuff. And, since the View schema is completely XML based, we need to adhere to XML rules. This means that whenever we want to include plain HTML we must encapsulate that HTML in a CDATA element. This is exactly what happens in the first line (1505) where we say that we want to output HTML and then contain the actual HTML inside a CDATA element.

Our HTML so far is ‘’

Output, variables and conditions in View CAML

Next we pick up a variable using the GetVar element. The Name attribute tells SharePoint which variable to get, in this case AlternateStyle. Now, in this example, the first time we enter the ViewBody, which would be for the first list item, this value would be nothing or null since it is a custom variable and we need to set this ourselves. This will happen in this example in a few moments.

Immediately following the GetVar element is a new HTML element which outputs “>. So, for the first item in the list, the HTML output so far would be ‘’.

The IfEqual element that follows is a conditional element. For the IfEqual element we need at least three child elements, the Expr1, Expr2, and Then elements, and we may add an optional Else element. The structure is just like a normal conditional element from any other language. We evaluate Expr1, compare that to Expr2 and if these are equal, perform whatever is in Then. If the values are not equal and we have an Else element, as it the case here, perform whatever is in the Else element. If we don’t have a Then element, nothing happens if Expr1 is not equal to Expr2.

Basically, this is the same as writing

if (Expr1 == Expr2) {

}

else {

}

In our view the Expr1 and Expr2 compares the variable named AlternateStyle to see if it is set to ‘ms-alternating’. If it is, the Then element will set the variable, using the SetVar element, to nothing. Else, meaning the AlternateStyle is already set to nothing, set the AlternateStyle to ‘ms-alternating’ for the scope of this view request. the effect of this is that we alternate for each item whether we output the string ‘ms-alternating’ when we call ‘GetVar Name=”AlternateStyle”’ in line 1505. Or, in plain C#, given that we have a HTMLWriter object called writer, a string called AlternateStyle and an SPList called list:

foreach (SPListItem item in list.Items)
{
writer.Write(“ writer.Write(AlternateStyle);
writer.Write(“\”>”);
if (AlternateStyle == “ms-alternating”)
{
AlternateStyle = “”;
}
else
{
AlternateStyle = “ms-alternating”;
}

}

The next CAML element is Fields, which starts on line 1520 and ends on line 1541. As for the ViewBody, Fields is called for each Field, or column, in the list item on which we are currently working. We thus start the rendering of each field, or column, by outputting to finish the TD we started in line 1520.

However, more importantly, line 1540 outputs the field itself. The logic of exactly what will be output here depends on the field itself, and we’ll get back to that in part 5. For now you can assume that Field outputs the value of the field as it is accurate enough to understand what goes on.

Finally we close the TD html tag we started in line 1520 and, after completing the Fields iteration, close the TR html tag we started in line 1505.

Phew, that was a mouthful, however, the basic concept is that we build HTML for each list item. In this case a TR with a TD for each column. You can, of course, make this a lot simpler if you don’t want or need all the styling and conditions. As such, to just output a TR for each list item and a TD for each column, you might do just:

]]>

]]>

]]>

]]>

which is a lot less complex.

See? Custom view development isn’t really that hard. And if you want to learn more, start by creating your own list template and build views from scratch. There is also a complete chapter in my new book which deals with more advanced concepts of custom view creation, and in my completely unbiased opinion I highly recommend that book to learn CAML view development

Where to now?

Now that you have seen a bit on how you can use lists to tailor the user experience, you might want to explore a bit further on your own. Here are some resources which might help you along:

The MSDN documentation for CAML view schema is the most comprehensive documentation available. You get all the gritty details for all the root elements in a view as well as all the rendering elements. However, be advised that not all aspects of the documentation is as clear as can be, and some information is missing or plain wrong.

If you want a comprehensive guide there is a separate chapter in my book “Building the SharePoint User Experience” that covers views and takes you on a guided tour through creating a view using all the aspects of view creation, including sorting, grouping and paging.

Microsoft Office Online has a nice guide for walking you through setting up a new custom list form page.

And, of course, make sure you read the next part of this series where we will dive into content types and how you can modify appearance of certain types of information.

I do hope I’ll see you again for the future parts of this series,

SharePoint User Experience Week on SharePoint Magazine

Arno Nel — Sat, 21 Feb 2009 02:02:59 +0000

Starting from February 23rd 2009, SharePoint Magazine will hold a user experience week, where all the articles released will focus around the user experience of SharePoint.

Every workday, Monday through Friday, Bjørn Furuknap, our resident user experience expert, will release a new article in the Customizing SharePoint User Experience series. These articles are based on his book, “Building the SharePoint User Experience”, due for release this April. SharePoint Magazine has secured the exclusive rights to publish previews of the content from this book.

The “Customizing the SharePoint User Experience” series has only four articles left. Since there are five days in Bjørn has written a final bonus article, the title and topic of which will be revealed on Thursday’s article.

Stay tuned and you will find out the topic of the bonus article.