Referencing and Linking: Using the Asset URL Selector in SharePoint Server 2007

SharePoint 2007

Summary:  Learn how you can create a custom field in Microsoft Office SharePoint Server 2007 that you can use to define a relationship between two documents.

Office Visual How To

Applies to:  2007 Microsoft Office System, Microsoft Office SharePoint Server 2007

Microsoft Corporation

March 2008


Custom fields are very helpful when you are creating custom functionality in Microsoft Office SharePoint Server 2007. This Microsoft Office Visual How To demonstrates how you can create a custom field that is used to define a relationship between two documents. In this case, a relationship defines one document as a version of another, that is, one document is a Microsoft Office Word 2007 document that has a text file version.

The example is divided into three parts:

  • Defining the relationship.

  • Storing the relationship information in a secondary list.

  • Retrieving and displaying the relationship information.

This example shows how you can provide functionality to select the related document, defining the relationship by using the AssetUrlSelector class. Instead of having the user manually type the URL to a version of a document, you can use an out-of-the-box SharePoint Server Asset Picker to provide a user interface (UI) for selecting the target item.

Code It

In this example, you create a custom field and field control that define a relationship between two files in a document library. However, you can also create an association between a document and a list item, or between two list items. From the first document, you select a second related document by using the AssetUrlSelector class in the Microsoft.SharePoint.Publishing.WebControls namespace.

The AssetUrlSelector class provides a UI for selecting documents and items within a SharePoint site. It is used in multiple places, such as the Image and HTML Editor field controls in a Publishing site, to provide out-of-the-box Office SharePoint Server functionality for selecting an image or a hyperlink. You can take advantage of this existing functionality in your custom field control to enable users to select related files.

To create the custom Relationship field, you can extend the text field from the SPFieldText class. The text field is used in this example because it provides basic functionality for displaying the field value. The first step is to create a class that derives from SPFieldText and override the FieldRenderingControl method to call the custom field control, RelationshipFieldControl.

    public class RelationshipField : SPFieldText

        // Methods
        public RelationshipField(SPFieldCollection fields, 
string fieldName) : base(fields, fieldName)

        public RelationshipField(SPFieldCollection fields, 
        string typeName, string displayName) : base(fields, typeName, displayName)

        // Properties
        public override BaseFieldControl FieldRenderingControl
                BaseFieldControl control = 
                new RelationshipFieldControl();
                control.FieldName = base.InternalName;
                return control;

The RelationshipFieldControl control derives from BaseFieldControl and uses the AssetUrlSelector class to enable users to select the related file. To use the AssetUrlSelector class, you must reference the Microsoft.SharePoint.Publishing.WebControls namespace in Microsoft.SharePoint.Publishing.dll, as shown in the following code example.

using Microsoft.SharePoint;
using Microsoft.SharePoint.Publishing.WebControls;
using Microsoft.SharePoint.WebControls;

Three classes are overridden: the CreateChildControls class, the Render class, and the OnLoad class. In the CreateChildControls class, the AssetUrlSelector is added to the controls collection if the form is in edit mode. This provides a Browse button and the functionality to select the related file, and a text box for displaying the URL to the selected file.

When the form is in edit mode, the relationship URL is displayed in the text box if the URL was previously set. You do this by setting the AssetUrl property of the AssetUrlSelector object within the Render method.

To persist the path of the related file that is selected by the user, the list item field value is set to the value of the AssetUrl property during a postback in the OnLoad event, as shown in the following example.

    public class RelationshipFieldControl : BaseFieldControl
        protected AssetUrlSelector urlSelector;

        protected override void OnLoad(EventArgs e)

            // Set the value if this is a postback.
            if (this.Page.IsPostBack && base.ControlMode 
            == SPControlMode.Edit)
                this.ListItemFieldValue = urlSelector.AssetUrl;

        protected override void CreateChildControls()

            // Add the asset picker when in edit mode.
            if (base.ControlMode == SPControlMode.Edit)
                urlSelector = new AssetUrlSelector();

        protected override void Render(HtmlTextWriter output)

            // If this is edit mode and has a value, set the picker.
            if (base.ControlMode.Equals(SPControlMode.Edit) 
            && this.ListItemFieldValue != null)
                this.urlSelector.AssetUrl = 

To register the custom RelationshipField, you create a field type definition file, as shown in the next example. This is an XML file that contains the settings for the custom field type and enables Office SharePoint Server to create an instance of this field. After you create the file, add it to the ..\12\TEMPLATE\XML directory.

<?xml version="1.0" encoding="utf-8"?>
    <Field Name="TypeName">RelationshipField</Field>
    <Field Name="ParentType">Text</Field>
    <Field Name="TypeDisplayName">Relationship Field</Field>
    <Field Name="TypeShortDescription">Relationship Field</Field>
    <Field Name="FieldTypeClass">AssetPicker.RelationshipField, 
AssetPicker, Version=, Culture=neutral, 

Read It

The AssetUrlSelector control provides much of the functionality that is necessary for the user to browse and select a document in an Office SharePoint Server library. When you add an instance of this control, a text box and browse button are displayed on the page.

Figure 1. Text box and browse button after adding AssetUrlSelector control

Text box and browse button

When users click the Browse button, the Select a Link dialog box appears and lets the user browse the SharePoint Server libraries and select the related file. The URL to the selected file is automatically set on the AssetUrl property file and appears in the text box.

Figure 2. Select a Link dialog box

Select a Link dialog box

You might want to scope the URL that is selected with the AssetUrlSelector. To allow users to select a document or item only within the current site collection, you can set the AllowExternalUrls property of the AssetUrlSelector class to false. To narrow the scope even more so that users can only select an item within the current web or a specific list or library, you can implement custom code to validate the selected URL.

The end result of this example is that the path of the related file is stored in the custom RelationshipField. However, the relationship remains unknown to the related file because its metadata is never updated. You can use event handlers to ensure that the related file is updated appropriately when a relationship is created or modified; however, this can become complex. There may be scenarios in which the related file cannot immediately be updated, such as if the user does not have edit permissions on the related file, or the related file is checked out by another user.

At this point, the example is basically a reimplementation of the Hyperlink column functionality. However, by using the AssetURLSelector control (or Asset Picker) in Office SharePoint Server, you can add a UI for selecting the corresponding document in the relationship. This example is intended to highlight the Asset Picker and the fact that you can use it in custom field controls. You can extend the example to provide additional useful functionality, such as letting users specify multiple-link relationships.

See It

Video splash screen

Watch the Video

Video Length: 00:07:34

File Size: 5.02 MB WMV

Explore It

Community Additions