ImageFieldValue Class

A field value class for an ImageField object that represents an IMG tag and specific key attributes for that tag.

Inheritance Hierarchy


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


<SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel := True)> _
<SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel := True)> _
Public Class ImageFieldValue _
    Inherits HtmlTagValue
Dim instance As ImageFieldValue
[SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
[SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
public class ImageFieldValue : HtmlTagValue


This value object wraps an HTML string for an image and allows you to get and set certain value object properties and then get the resulting <IMG> tag HTML markup string. If the ImageUrl property does not have a value, then the ToString method returns an empty string. In other cases, the ToString method returns a string of HTML that contains an <IMG> tag, possibly enclosed in an <A> tag hyperlink, depending on the values of its Hyperlink property. Only certain properties are recognized on the <A> and <IMG> tags and are used to generate the HTML string.

For the <A> tag:

  • Href

  • Target (only "_blank" is allowed)

For the <IMG> tag:

  • Src (required)

  • Align

  • Alt

  • Border

  • Height

  • Hspace

  • Vspace

  • width

For an ImageField column, instances are usually retrieved from an SPListItem field value. SPListItem is also used to store the posted value in a RichImageField and RichImageSelector control. Additionally, you can construct a new instance directly as an empty value or a value based on an HTML string that conforms to the basic pattern of an <IMG> tag optionally enclosed in an <A> tag. After you retrieve this value from an SPListItem field and change any properties on this object, you must set the value object back to the SPListItem field value and update it to store the value.


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

namespace Microsoft.SDK.SharePointServer.Samples
    public static class ImageFieldValueSamples
    // You can change any of the following data that are set into the ImageFieldValue
    private const string NewImageUrl = "/SiteCollectionImages/SampleImage.jpg";
    private const string NewHyperlink = "/Pages/SamplePage.aspx";
    private const bool NewOpenHyperlinkInNewWindow = true;
    private const string NewAlignment = "right";
    private const string NewAlternateText = "Sample alternate text for the image";
    private const int NewBorderWidth = 4;
    private const int NewHeight = 100;
    private const int NewWidth = 150;
    private const int NewHorizontalSpacing = 10;
    private const int NewVerticalSpacing = 15;

    // You can change the following default ImageFieldValue HTML
    private const string DefaultImageFieldValueHtml = "<A href=\"/Pages/SamplePage.aspx\"><IMG src=\"/SiteCollectionImages/SampleImage.jpg\" alt=\"Default ALT attribute value\"></a>";

    public static string GetAndSetImageFieldValue(
    SPListItem listItemWithImageField,
    string imageFieldName)
      if (null == listItemWithImageField)
        throw new System.ArgumentNullException("listItemWithImageField", "The listItemWithImageField argument must be a valid SPListItem");

      if (string.IsNullOrEmpty(imageFieldName))
         throw new System.ArgumentNullException("imageFieldName", "The imageFieldName argument must be a valid image field name on the SPListItem");

      // Retrieve the current value from an SPListItem with a
      // column of the ImageField type with the name imageFieldName
      ImageFieldValue currentFieldValue = 
      listItemWithImageField[imageFieldName] as ImageFieldValue;

      // If there is no current value then construct a new empty value
      if (null == currentFieldValue)
         currentFieldValue = new ImageFieldValue();

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

      // These properties are all optional for an ImageFieldValue
      currentFieldValue.Hyperlink = NewHyperlink;
      currentFieldValue.OpenHyperlinkInNewWindow = NewOpenHyperlinkInNewWindow;
      currentFieldValue.Alignment = NewAlignment;
      currentFieldValue.AlternateText = NewAlternateText;
      currentFieldValue.BorderWidth = NewBorderWidth;
      currentFieldValue.Height = NewHeight;
      currentFieldValue.Width = NewWidth;
      currentFieldValue.HorizontalSpacing = NewHorizontalSpacing;
      currentFieldValue.VerticalSpacing = NewVerticalSpacing;

      // The changes to the properties of the ImageFieldValue object are
      // local to this specific object instance and not stored in the SPListItem.
      // To store the changes the value must be set back in to the SPListItem field value.
     listItemWithImageField[imageFieldName] = currentFieldValue;

     // The ToString() returns the HTML that reflects the new ImageFieldValue 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


ImageFieldValue Members

Microsoft.SharePoint.Publishing.Fields Namespace