Sometimes when I am working with SharePoint I really feel like I got it. You now that feeling you get when you know exactly what you are doing and have no problems implementing it...then there are times when I really just want to smash something. And it really doesn't matter what...it could be anything! This is the feeling I got in the last couple of days working with custom field types in SharePoint.
It seems there are lots of blogs and articles out there talking about how to do it, but from what I could see (and to be fair I did not read them all so if you know of some good posts that would be great) it felt like most of the time I was only getting half the story. I just finished putting together a very basic Custom Field Type that will display a multi line textbox in edit/new mode and simply display the value in a literal control in display mode. In the grand scheme of things I am building a base XML Field Type to use for a series of additional Custom field types so essentially I want to store a string (yes I could use the XmlDocument)...but alas thats a story for another day.
So a bit of a primer, or rehash so I don't forget, when developing custom field types there are many pieces to it....not all of them required. Here is a list of the items and what they do:
- Field Type class - this class acts as the controller and hooks the rendering control, field type xml definition and the value class together. It also provides validation at the field level via the GetValidatedString() method of the SPField object
- Field Control class - this is the rendering engine and gives you the power to display your control in any manner you wish as well as perform validation on the data being saved via the UI.
- Field Value class - allows for custom logic to be put around mutiple column fields and different data structures that will be storing data for your field type.
- .ascx file in CONTROLTEMPLATES directory - this supplies rendering markup via a user control and hooks into the field control class
- fldtypes_* - this file that gets installed into the 12/TEMPLATES/XML directory and contains the information that SharePoint requires in order to load your field type into the system. Such as the assembly to use, the parent type and other information. This is required if the type is going to be applied to content types and become a field on a list.
So for my requirements I only needed the field type, the field control and the fldtypes_xxx.xml file. Lets look at the field type class I built
public class XmlFieldType : SPField
{
public XmlFieldType(SPFieldCollection fields, string fieldName) : base(fields, fieldName) { }
public XmlFieldType(SPFieldCollection fields, string fieldName, string displayName) : base(fields, fieldName, displayName) { }
public override BaseFieldControl FieldRenderingControl
{
get
{
BaseFieldControl fldControl = new XmlFieldControl();
fldControl.FieldName = InternalName;
return fldControl;
}
}
public override object GetFieldValue(string value)
{
if (string.IsNullOrEmpty(value))
return null;
return value;
}
public override Type FieldValueType
{
get { return typeof(string); }
}
public override string DefaultValue
{
get
{
XmlDocument doc = new XmlDocument();
doc.LoadXml(this.SchemaXml);
XmlNode nodeInFieldSchema = doc.SelectSingleNode("Field/Default");
if (nodeInFieldSchema != null)
return nodeInFieldSchema.InnerXml;
return null;
}
set { base.DefaultValue = value; }
}
public override string GetValidatedString(object value)
{
base.GetValidatedString(value);
if (value == null)
{
if (this.Required) throw new SPFieldValidationException("Invalid value for required field.");
return string.Empty;
}
else
{
return value.ToString();
}
}
}
Lets review
- The two constructors are required...don't even bother
- FieldRenderingControl() method tells the field type which control to use
- GetFieldValue() method returns the value of the field....if we were using a custom type you would cast that to the appropriate type here
- FieldValueType() - get the type of the Value class
- DefautValue() - this gets the default value from the field if one is defined
- GetValidatedString() - perform field level validation
The Field Control Class is fairly simple as well:
public class XmlFieldControl : BaseFieldControl
{
protected Literal _values;
protected TextBox _editor;
protected override void OnInit(EventArgs e)
{
base.OnInit(e);
EnsureChildControls();
}
protected override void CreateChildControls()
{
if (this.Field == null || this.ControlMode == SPControlMode.Invalid)
return;
Controls.Clear();
base.CreateChildControls();
_editor = new TextBox();
_editor.TextMode = TextBoxMode.MultiLine;
_editor.Height = new Unit(300);
_editor.Width = new Unit(500);
Controls.Add(_editor);
if (ControlMode == SPControlMode.Display)
{
_values = new Literal();
_values.Text = Convert.ToString(ItemFieldValue);
Controls.Add(_values);
}
}
protected override void Render(HtmlTextWriter output)
{
EnsureChildControls();
if (ControlMode == SPControlMode.Display)
{
if (_values != null)
_values.RenderControl(output);
}
else
{
if (_editor != null)
_editor.RenderControl(output);
}
}
public virtual string Text
{
get
{
this.EnsureChildControls();
if (this._editor == null)
{
return null;
}
return this._editor.Text;
}
set
{
this.EnsureChildControls();
if (this._editor != null)
{
this._editor.Text = value;
}
}
}
public override object Value
{
get
{ return this.Text; }
set
{
if (base.Field != null)
{
this.Text = base.Field.GetFieldValueForEdit(value);
base.Value = (string)value;
base.UpdateFieldValueInItem();
}
}
}
}
Lets take a look at what this class is doing:
- OnInit() - come on, do I have to explain?
- CreateChildControls() - initialize your controls and add to the Controls collection
- Render() - writes the controls to the HtmlTextWriter
- Text - This sets/gets the value in the controls
- Value - this sets the value in the Text property and notice the base.UpdateFieldValueInItem(); statement...this oushes the value from Value to ItemFieldValue and allows you to access this value in display mode because Value returns null (which i did not find the documentation on M$ thank you very much).
So that leaves the last piece of the pie for my simple implementation the fldtypes file:
<FieldTypes>
<FieldType>
<Field Name="TypeName">XmlFieldType</Field>
<Field Name="ParentType"></Field>
<Field Name="InternalType">Note</Field>
<Field Name="SQLType">ntext</Field>
<Field Name="TypeDisplayName">Xml Field</Field>
<Field Name="TypeShortDescription">Xml controls</Field>
<Field Name="UserCreatable">TRUE</Field>
<Field Name="ShowOnListCreate">TRUE</Field>
<Field Name="Sortable">FALSE</Field>
<Field Name="AllowBaseTypeRendering">FALSE</Field>
<Field Name="Filterable">FALSE</Field>
<Field Name="FieldTypeClass">Website.CustomFields.XmlFieldType, Website.CustomFields, Version=1.0.0.0, Culture=neutral, PublicKeyToken=346fcdd567259ee6</Field>
<RenderPattern Name="HeaderPattern">
<Property Select="DisplayName" HTMLEncode="TRUE"/>
</RenderPattern>
<RenderPattern Name="DisplayPattern">
<Column/>
</RenderPattern>
</FieldType>
</FieldTypes>
So there you have it. All I need to do in order to inherit from this is to remove the rendering (which i dont need anyway as this is going to be a base type) and it should be good to go. Those three pieces of code can be installed into your SharePoint environment and should help you get started to understanding custom field types.
Don't forget to add the SafeControl entry, Adjust your trust level and move the .dll into your bin folder as well.
Download the code here
Resources I found useful:
- I did work through the example in Andrew Connell's book (Professional SP 2007 WCM development) and that worked fine and he actually does a great job of explaining most of whats going on here.
- MSDN...where else
- Charlie Holland has a pretty good article series on this stuff but unfortunately I couldn't get it working. I also wanted a simple bare bones implementation.
Sometimes when I am working with SharePoint I really feel like I got it. You now that feeling you get when you know exactly what you are doing and have no problems implementing it...then there are times when I really just want to smash something. And it really doesn't matter what...it could be anything! This is the feeling I got in the last couple of days working with custom field types in SharePoint. It seems there are lots of blogs and articles out there talking about how to do it, but from what I could see (and to be fair I did not read them all so if you know of some good posts that would be great) it felt like most of the time I was only getting half the story. I just finished putting together a very basic Custom Field Type that will display a multiline textbox in edit/new mode and simply display the value in a literal control in display mode. In the grand scheme of things I am building a base XML Field Type to use for a series of additional Custom field types so essentially I want to store a string (yes I could use the XmlDocument)...but alas thats a story for another day.
So a bit of a primer, or rehash so I don't forget, when developing custom field types there are many pieces to it....not all of them required. Here is a lit of the items and what they do:
* Field Type class - this class acts as the controller and hooks the rendering control, field type xml definition and the value class together. It also provides validation at the field level via the GetValidatedString() method of the SPField object
* Field Control class - this is the rendering engine and gives you the power to display your control in any manner you wish as well as perform validation on the data being saved via the UI.
* Field Value class - allows for custom logic to be put around mutiple column fields and different data structures that will be storing data for your field type.
* .ascx file in CONTROLTEMPALTES directory - this supplies rendering markup via a usercontrol and hooks into the field control class
* fldtypes_* - this file that gets installed into the 12/TEMPLATES/XML directory and contrains the information that SharePoint requires in order to load your field type into the system. Such as the assembly to use, the parent type and other information. This is required if the type is going to be applied to content types and become a field on a list.
So for my requirements I only needed the field type, the field control and the fldtypes_xxx.xml file. Lets look at the field type class I built
public class XmlFieldType : SPField
{
public XmlFieldType(SPFieldCollection fields, string fieldName) : base(fields, fieldName) { }
public XmlFieldType(SPFieldCollection fields, string fieldName, string displayName) : base(fields, fieldName, displayName) { }
public override BaseFieldControl FieldRenderingControl
{
get
{
BaseFieldControl fldControl = new XmlFieldControl();
fldControl.FieldName = InternalName;
return fldControl;
}
}
public override object GetFieldValue(string value)
{
if (string.IsNullOrEmpty(value))
return null;
return value;
}
public override Type FieldValueType
{
get { return typeof(string); }
}
public override string DefaultValue
{
get
{
XmlDocument doc = new XmlDocument();
doc.LoadXml(this.SchemaXml);
XmlNode nodeInFieldSchema = doc.SelectSingleNode("Field/Default");
if (nodeInFieldSchema != null)
return nodeInFieldSchema.InnerXml;
return null;
}
set { base.DefaultValue = value; }
}
public override string GetValidatedString(object value)
{
base.GetValidatedString(value);
if (value == null)
{
if (this.Required) throw new SPFieldValidationException("Invalid value for required field.");
return string.Empty;
}
else
{
return value.ToString();
}
}
}
Lets review
* The two constructors are required
* FieldRenderingControl() method tells the field type which control to use
* GetFieldValue() method returns the value of the field....if we were using a custom type you would cast that to the appropriate type here
* FieldValueType() - get the type of the Value class
* DefautValue() - this gets the default value from the field if one is defined
* GetValidatedString() - perform field level validation
The Field Control Class is fairly simple as well:
public class XmlFieldControl : BaseFieldControl
{
protected Literal _values;
protected TextBox _editor;
protected override void OnInit(EventArgs e)
{
base.OnInit(e);
EnsureChildControls();
}
protected override void CreateChildControls()
{
if (this.Field == null || this.ControlMode == SPControlMode.Invalid)
return;
Controls.Clear();
base.CreateChildControls();
_editor = new TextBox();
_editor.TextMode = TextBoxMode.MultiLine;
_editor.Height = new Unit(300);
_editor.Width = new Unit(500);
Controls.Add(_editor);
if (ControlMode == SPControlMode.Display)
{
_values = new Literal();
_values.Text = Convert.ToString(ItemFieldValue);
Controls.Add(_values);
}
}
protected override void Render(HtmlTextWriter output)
{
EnsureChildControls();
if (ControlMode == SPControlMode.Display)
{
if (_values != null)
_values.RenderControl(output);
}
else
{
if (_editor != null)
_editor.RenderControl(output);
}
}
public virtual string Text
{
get
{
this.EnsureChildControls();
if (this._editor == null)
{
return null;
}
return this._editor.Text;
}
set
{
this.EnsureChildControls();
if (this._editor != null)
{
this._editor.Text = value;
}
}
}
public override object Value
{
get
{ return this.Text; }
set
{
if (base.Field != null)
{
this.Text = base.Field.GetFieldValueForEdit(value);
base.Value = (string)value;
base.UpdateFieldValueInItem();
}
}
}
}
sdfsdf
XmlFieldType
Note
ntext
Xml Field
Xml controls
TRUE
TRUE
FALSE
FALSE
FALSE
Website.CustomFields.XmlFieldType, Website.CustomFields, Version=1.0.0.0, Culture=neutral, PublicKeyToken=346fcdd567259ee6
I did work through the example in Andrew Connell's book (Professional SP 2007 WCM development) and that worked fine and he actually does a great job of explaining most of whats going on here.
http://msdn.microsoft.com/en-us/library/ms446361.aspx
Technorati Tags: controls, custom field type, Development, SharePoint, xml
