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

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.

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
        {
            get
            {
                BaseFieldControl control = 
                new RelationshipFieldControl();
                control.FieldName = base.InternalName;
                return control;
            }
        }
    }

    Public Class RelationshipField
        Inherits SPFieldText

        ' Methods
        Public  Sub New(ByVal fields As SPFieldCollection, &_
        ByVal fieldName As String) :  MyBase.New(fields, fieldName)
        End Sub

        Public  Sub New(ByVal fields As SPFieldCollection, &_
        ByVal typeName As String, ByVal displayName As String) :  &_
        MyBase.New(fields, typeName, displayName)
        End Sub

        ' Properties
        Public Overrides ReadOnly Property FieldRenderingControl() As BaseFieldControl
            Get
                Dim control As BaseFieldControl &_
                = New RelationshipFieldControl()
                control.FieldName = MyBase.InternalName
                Return control
            End Get
        End Property
    End Class

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;

Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.Publishing.WebControls
Imports 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)
        {
            base.OnLoad(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()
        {
            base.CreateChildControls();

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

        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 = 
                this.ListItemFieldValue.ToString();
            }
            base.Render(output);
        }
   }

    Public Class RelationshipFieldControl
        Inherits BaseFieldControl
        Protected urlSelector As AssetUrlSelector

        Protected Overrides Sub OnLoad(ByVal e As EventArgs)
            MyBase.OnLoad(e)

            ' Set the value if this is a postback.
            If Me.Page.IsPostBack And MyBase.ControlMode &_
            = SPControlMode.Edit Then
                Me.ListItemFieldValue = urlSelector.AssetUrl
            End If
        End Sub

        Protected Overrides Sub CreateChildControls()
            MyBase.CreateChildControls()

            ' Add the asset picker when in edit mode.
            If MyBase.ControlMode = SPControlMode.Edit Then
                urlSelector = New AssetUrlSelector()
                Me.Controls.Add(urlSelector)
            End If
        End Sub

        Protected Overrides Sub Render(&_
        ByVal output As HtmlTextWriter)

            ' If this is edit mode and has a 
            ' value, set the picker.
            If Not MyBase.ControlMode.Equals(SPControlMode.Edit) And &_
            Me.ListItemFieldValue Is Nothing Then
                Me.urlSelector.AssetUrl &_
                = Me.ListItemFieldValue.ToString()
            End If
            MyBase.Render(output)
        End Sub
    End Class

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"?>
<FieldTypes>
  <FieldType>
    <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=1.0.0.0, Culture=neutral, 
PublicKeyToken=7498984c8afdbdb9</Field>
  </FieldType>
</FieldTypes>

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

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

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.

Watch the Video

Video Length: 00:07:34

File Size: 5.02 MB WMV

• SharePoint Server 2007 Developer Center

• Enterprise Document Content and Workflow

• Referencing and Linking: Using Custom Fields to Display Relationships in SharePoint Server 2007

• Referencing and Linking: Using Secondary Lists to Maintain Relationships in SharePoint Server 2007