Implementation Design

Microsoft didn't provide a means to create a custom property. Therefore, we must use a type that already exists and modify the behavior of that type in such a way that our application can withstand Microsoft's updates.

The Single Line of Text is the most versatile existing type, so we will use that to house the data for the custom type. Everywhere the text field is used, a check will be made to see whether or not it's our custom property. If the field is a custom property, then it will be rendered appropriately, and if it's not, then the system will render the property as it normally would.

It's a fairly straightforward design, though it's a bit more difficult to implement. Before we venture much further, let's cover a major design consideration in the following sidebar.

Warning: Design Considerations

A major caveat to making modifications like these is that Microsoft's shipping code cannot be modified. Shipping code is defined as those files that can be overwritten in a service pack's hot fix and other updates. Microsoft's shipping code includes the site definitions that Microsoft provides out of the box. Several files in the layouts folder are also shipping code.

To give you a visualization of how this situation might affect the application, imagine that production support installs a new service pack without warning, and all the code you've modified is overwritten. There is a way to implement a custom property type (and other customizations) and still be impervious to Microsoft's benevolent updates.

Microsoft enables you to create custom site definitions and has promised not to harass them. When creating a custom site definition, many things can be customized, and they are certainly worth exploration. Because we are focusing on implementing custom properties, we are only going to touch on creating the new site definition and a new list to work with.

There are a few pages in the Layouts/1033 folder to which we will want to add our custom code as well. Keeping in mind Microsoft's update methods, it's easy to see that we will want to copy these few pages into our own folder.

Essentially, we shouldn't edit any files that Microsoft gives us out of the box. The best practice is to make a copy and modify the copy instead. This "copy and modify" method is becoming a mantranot only for this specific situation, but for almost every source file Microsoft ships.

Several pages are affected by customization like this one. The general areas of interest will be covered, followed by the detailed implementation later in the chapter.

What Is Affected?

There are a few places in SharePoint where the properties of a list make themselves apparentuploading and editing a document from the web interface and from Word, and creating and modifying properties in a list. In this section, we identify those areas and learn where they exist and how they are used. Armed with this knowledge, we can make short work of implementing a custom property.

Uploading and Modifying a Document

Uploading and modifying a document are handled in two different ASP.NET pages: UPLOAD.ASPX (see Figure 4.1) and EDITFORM. ASPX (see Figure 4.2), respectively. You can navigate to these pages by going to any document library and either uploading a new document or modifying an existing one. If you installed SharePoint in the default location, the documents for the Team site, Blank site, and Document Workspace site definitions are located in C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\1033\STS\LISTS\DOCLIB. For simplicity, we will be talking about changes to these site definitions throughout the rest of the chapter. But don't change anything yet! Changes in this location are unsupported by Microsoft for a good reason. These documents affect all lists for all sites using these site definitions. We'll soon see how to make these changes safely.

Figure 4.1. Upload.aspx.

Figure 4.2. EditForm.aspx.

Adding and Editing a Column

One of the greatest things about SharePoint is creating functionality without having to enlist the skills of a developer. Wearing our developer hat, we want to make the site as flexible as possible so that anybody can create new functionality. After the new property has been identified, it almost always becomes immediately apparent that the new property can be used in many places. Let's look at FLDNEW.ASPX and FLDEDIT.ASPX in Figures 4.3 and 4.4, respectively.

Figure 4.3. FldNew.aspx.

Figure 4.4. FldEdit.aspx.

As you can see, many property types are very generic and have somewhat robust functionality. When we try to integrate them with other applications, however, we find that these fields are extremely limited. The "Name and Type" section is where users select the type of property they want. Ultimately it would be nice to have a radio button for our custom property type. When selected, the optional settings specific to our column appear below. These pages are located at C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\LAYOUTS\1033. Again, don't modify anythingthese pages must be copied, and then you can make changes to the copies. For now, we are just trying to identify the pieces of the puzzle that can be modified to implement our custom property. Naturally, we'll take a closer look in the implementation example.

Word has a facility to manage the data stored in properties as well. Let's take a look at that next.

Modifying Properties in Microsoft Word

When saving a document to a document library, users are presented with the site name, the library name, and a list of documents in the library. This context helps users understand where they are saving their documents.

Figure 4.5. Saving a document in Word.

A couple files perform this particular brand of magicFILEDLG.HTM and SCHEMA.XML are both located at C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\1033\STS\LISTS\DOCLIB. Although we won't have to modify these pages, it's nice to know where everything is located.

After the save is committed, the user is presented with the Web File Properties dialog. This dialog also consists of a couple pages, EDIT-DLG.HTM and again SCHEMA.XML, which are located in the same folder mentioned previously. If you ever wanted to try out some CAML but didn't have a place to do it, these three pages can be your first stomping ground!

Here is one of those places where you could go off on a tangent. You could modify EDITDLG.HTM and FILEDLG.HTM for a branding issue or some other standardized customization.

Figure 4.6. Document properties in Microsoft Word.

It is a little-known fact that the properties defined by a document library can be modified in Word. To see this in action, open a document from a document library, select File, and then select Properties, and the same Web File Properties dialog appears.

The depth of what we've covered here has been basic. With the design principles behind us, let's move into implementation and actually make this technique work.