BaseFieldControl.CreateChildControls Method
Creates any child controls necessary to render the field, such as a label control, link control, or text box control.
Namespace: Microsoft.SharePoint.WebControls
Assembly: Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Available in Sandboxed Solutions: No
Syntax
'Declaration
Protected Overrides Sub CreateChildControls
'Usage
Me.CreateChildControls()
protected override void CreateChildControls()
Remarks
CreateChildControls is inherited from the Control class of Microsoft ASP.NET 2.0 and for objects of the latter type it does most of the work in rendering a control. However, BaseFieldControl and its derivations are also templated controls that inherit from TemplateBasedControl: for most of these controls, a template defined in an .ascx file located in C:\Program Files\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\ControlTemplates does much of the rendering work. Often the CreateChildControls only does a "final polish" on the controls, such as setting the tab index of the child controls, or specifying the CSS file that styles the controls, or inserting a default value into a child control in New mode.
Notes to Inheritors
If you override this method, your override must call the base method.
You may also want to validate data that users enter into the field's UI control on the New or Edit (list item) forms. In particular, if the field is required to have a value, this requirement should be enforced. (The Required property records whether the field is required or not.) If you are using one of the built-in Windows SharePoint Services 3.0 classes that derive from BaseFieldControl to render your field, then you can rely on its internal validation to enforce Required. If you are deriving your own control from BaseFieldControl or one of its derivations and you override the CreateChildControls method, then you will need to provide the enforcement of Required as well as any other UI-level validation you want to do. Depending on the complexity of your field type and rendering control, your UI validation logic can be in either the Validate method or the CreateChildControls method or a combination of the two. But keep in mind that if your validation logic is entirely in CreateChildControls and you update the field directly through the object model, rather than through the form, CreateChildControls is not called and your data validation is not invoked.
Examples
The following example shows a typical override of CreateChildControls. For the full example, see Walkthrough: Creating a Custom Field Type.
protected override void CreateChildControls()
{
if (this.Field != null && this.ControlMode != SPControlMode.Display)
{
// Make sure inherited child controls are completely rendered.
base.CreateChildControls();
// Associate child controls in the .ascx file with the
// fields allocated by this control.
this.ISBNPrefix = (Label)TemplateContainer.FindControl("ISBNPrefix");
this.textBox = (TextBox)TemplateContainer.FindControl("TextField");
if (!this.Page.IsPostBack)
{
if (this.ControlMode == SPControlMode.New)
{
textBox.Text = "0-000-00000-0";
} // end assign default value in New mode
}// end if this is not a postback
//Do not reinitialize on a postback.
}// end if there is a non-null underlying ISBNField and control mode is not Display
// Do nothing if the ISBNField is null or control mode is Display.
}
Protected Overrides Sub CreateChildControls()
If Me.Field IsNot Nothing AndAlso Me.ControlMode <> SPControlMode.Display Then
' Make sure inherited child controls are completely rendered.
MyBase.CreateChildControls()
' Associate child controls in the .ascx file with the
' fields allocated by this control.
Me.ISBNPrefix = CType(TemplateContainer.FindControl("ISBNPrefix"), Label)
Me.textBox = CType(TemplateContainer.FindControl("TextField"), TextBox)
If Not Me.Page.IsPostBack Then
If Me.ControlMode = SPControlMode.New Then
textBox.Text = "0-000-00000-0"
End If ' end assign default value in New mode
End If ' end if this is not a postback
'Do not reinitialize on a postback.
End If ' end if there is a non-null underlying ISBNField and control mode is not Display
' Do nothing if the ISBNField is null or control mode is Display.
End Sub
See Also
Reference
Microsoft.SharePoint.WebControls Namespace
Other Resources
How to: Create a Custom Field Type