LinkFieldValue Class

A field value class for a LinkField object that represents an <A> tag and specific key attributes for that tag.

Inheritance Hierarchy

System.Object
  Microsoft.SharePoint.Publishing.Fields.HtmlTagValue
    Microsoft.SharePoint.Publishing.Fields.LinkFieldValue

Namespace:  Microsoft.SharePoint.Publishing.Fields
Assembly:  Microsoft.SharePoint.Publishing (in Microsoft.SharePoint.Publishing.dll)

Syntax

'Declaration
<SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel := True)> _
<SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel := True)> _
Public Class LinkFieldValue _
    Inherits HtmlTagValue

'Usage
Dim instance As LinkFieldValue

[SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
[SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
public class LinkFieldValue : HtmlTagValue

Remarks

This value object wraps an HTML string for a hyperlink and allows users to get and set certain value object properties and then get the resulting <A> tag HTML markup string. If the href property does not have a value, the ToString method returns an empty string. In other cases, the ToString method returns an HTML string that contains an <A> tag. Only certain properties are recognized on the <A> and <IMG> tags and used to generate the HTML string.

Recognized properties for <A> tag:

• href (required)

• title

• target (only "_blank" is allowed)

Recognized properties for <IMG> tag:

• src

• Instances are usually retrieved from a SPListItem field value for the LinkField column. It is also the object used to store the posted value in a Value and Value control. You can also construct a new instance directly either as an empty value or based on HTML string that conforms to the basic pattern of an <A> tag optionally containing an icon <IMG> tag. After retrieving this value from an SPListItem field and changing any properties on this object, you must set the value object back into the SPListItem field value and use the Update method to store the value.

Examples

using SPListItem = Microsoft.SharePoint.SPListItem;
using LinkFieldValue = Microsoft.SharePoint.Publishing.Fields.LinkFieldValue;

namespace Microsoft.SDK.SharePointServer.Samples
{
public static class LinkFieldValueSamples
  {
  // You can change any of the following data that will be set into the LinkFieldValue.
  private const string Newhref = "/Documents/SampleFile.docx";
  private const bool NewUseDefaultIcon = false;
  private const string NewTarget = "_blank";
  private const string NewToolTip = "Sample tool tip for the link";
  private const string NewTextPrefix = "Open [";
  private const string NewTextSuffix = "] in a new window";

  // You can change the following default LinkFieldValue HTML markup.
  private const string DefaultLinkFieldValueHtml = "<A href=\"/Documents/SampleFile.docx\" target=\"_blank\"><IMG src=\"/_layouts/images/icdoc.gif\" alt=\"\">Open [SampleFile.docx] in a new window</a>";

  public static string GetAndSetLinkFieldValue(
  SPListItem listItemWithLinkField,
  string linkFieldName)
    {
    if (null == listItemWithLinkField)
      {
      throw new System.ArgumentNullException("listItemWithLinkField", "The listItemWithLinkField argument must be a valid SPListItem");
      }

    if (string.IsNullOrEmpty(linkFieldName))
    {
    throw new System.ArgumentNullException("linkFieldName", "The linkFieldName argument must be a valid link field name on the SPListItem");
    }
    // Retrieve the current value from an SPListItem object
    // with a column of the LinkField type with the
    // name linkFieldName.
    LinkFieldValue currentFieldValue = 
    listItemWithLinkField[linkFieldName] as LinkFieldValue;

    // If there is no current value, construct a new empty value.
    if (null == currentFieldValue)
    {
      currentFieldValue = new LinkFieldValue();
    }

    // If this property is not set to a value, the ToString() for the
    //  LinkFieldValue returns String.Empty and nothing is stored in
    //  the field value when it is set back into the SPListItem.
    currentFieldValue.href = Newhref;

    // These properties are optional for a LinkFieldValue.
     currentFieldValue.Target = NewTarget;
     currentFieldValue.ToolTip = NewToolTip;
     currentFieldValue.UseDefaultIcon = NewUseDefaultIcon;

    // Use the static GetDefaultIconUrl method to find the correct
    //  icon URL in the given Web site for the file extension in Newhref.
    currentFieldValue.IconUrl =
    LinkFieldValue.GetDefaultIconUrl(Newhref, listItemWithLinkField.Web);

     // Use the static GetDefaultDisplayText method to find the default
     // link text for the given Newhref.
     currentFieldValue.Text = NewTextPrefix +
     LinkFieldValue.GetDefaultDisplayText(Newhref) +
     NewTextSuffix;

    // The changes to the properties of the LinkFieldValue object are
    // local to this specific object instance and not stored in the SPListItem.
    // To store the changes, the value must be set back to the SPListItem field value.
    listItemWithLinkField[linkFieldName] = currentFieldValue;
    listItemWithLinkField.Update();

    // The ToString() returns the HTML markup that reflects the new LinkFieldValue properties.
    return currentFieldValue.ToString();
    }
  }
}

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

Reference

LinkFieldValue Members

Microsoft.SharePoint.Publishing.Fields Namespace